GeekORM

GeekORM is a simple Object Relation Mapper for empowering your Rust development.

• Focus on simplicity
• Rely on Derive Macros to generate code for your structs
  • Using Table
  • Using Data
• Dynamically generate functions and corresponding SQL queries
  • .save(...) - Inserting new rows
  • .update(...) - Updating existing rows
  • .delete(...) - Deleting rows
• Support for Backends Drivers
  • rusqlite
  • libsql (Turso)
• Automatic Migration Generation
  • geekorm-cli init - Setup your migrations
• Extensive crate features
  • rand: Generate random strings (set lenght, set prefix, set enviroment)
  • hash or password: Generate secure Hashes of passwords (set algorithm)
  • and more...
• Documentation

You can install the library from crates.io:

cargo add geekorm

cargo add rusqlite
# OR
cargo add libsql

Along with the backend driver for geekorm:

cargo add geekorm -F rusqlite
# OR
cargo add geekorm -F libsql

If you want to manage your models and migrations using geekorm, you'll need to install the geekorm-cli command line tool.

cargo install geekorm-cli

GeekORM is easy to setup and use in your Rust project.

The first thing you'll need to decide is if you want to use the geekorm-cli to manage your migrations or if you want to manage them manually.

You can use the geekorm-cli to help you manage your migrations.

geekorm-cli init

This will prompt you to enter some information about your setup and will generate a crate or a module for you to use. Once you have setup your project, 2 new commands will be available to you:

# Generate a new migration (creates a new folders in your migrations directory)
geekorm-cli migrate 
# Validate your migrations (runs from your initial migration to the latest)
geekorm-cli test

Once you have installed geekorm, you can start using the derive macros like the following:

use anyhow::Result;
use geekorm::prelude::*;

/// Using the `Table` derive macro to generate the `Users` table
#[derive(Table, Debug, Default, serde::Serialize, serde::Deserialize)]
struct Users {
    #[geekorm(primary_key, auto_increment)]
    id: PrimaryKeyInteger,
    /// Unique username field
    #[geekorm(unique)]
    username: String,
    /// Password field with automatic hashing
    #[geekorm(hash)]
    password: String,
    /// User Type Enum (defaults to `User`)
    #[geekorm(new = "UserType::User")]
    user_type: UserType,
}

#[derive(Data, Debug, Default, Clone)]
enum UserType {
    Admin,
    Moderator,
    #[default]
    User,
}

#[tokio::main]
async fn main() -> Result<()> {
    // Setup the database and connection
    let database = ConnectionManager::connect(":memory:");
    let connection = database.acquire().await?;

    // Initialize or migrate the database using the `crate` or `module`.
    // This is done using the `geekorm-cli` function
    db::init(&conn).await?;
    // [OR] You can create the tables manually
    Users::create_table(&conn).await?;

    // Use the generated `new` function to create a new User
    // using the default values set in the struct.
    let mut user = Users::new("GeekMasher", "ThisIsNotMyPassword");
    // Saving the new User in the database
    user.save(&connection).await?;
    // Print the Primary Key value set by the database (auto_increment)
    println!("User ID: {:?}", user.id);

    // Updating the Users account type to Admin
    user.user_type = UserType::Admin;
    user.update(&connection).await?;

    // Fetch the Admin Users
    let admin_users = Users::fetch_by_user_type(&connection, UserType::Admin).await?;
    println!("Admin Users: {:?}", admin_users);

    // Counts the number of Users in the database
    let total_users = Users::total(&connection).await?;
    println!("Total Users: {:?}", total_users);

    Ok(())
}

There are a number of opt-in features supported by GeekORM. Features can be added either using cargo add geekorm -F all or added them directly in your Cargo.toml file.

• all: Enable all the major stable features
• new: Generate Table::new(...) functions
• helpers: Generate a number of helper functions
  • Select Table::select_by_primary_key()
  • Select column Table::select_by_{field}()
• rand: Support Generating random strings
• hash: Support Generating password hashes
• Backends
  • libsql: Add LibSQL backend support
  • rusqlite: Add Rusqlite backend support

Mathew Payne 💻 👀

Cale 🎨

Please create GitHub Issues if there are bugs or feature requests.

This project uses Semantic Versioning (v2) and with major releases, breaking changes will occur.

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.