44 releases (8 breaking)

new 0.9.1 Jan 20, 2025
0.8.4 Jan 9, 2025
0.8.3 Dec 20, 2024
0.7.2 Nov 26, 2024
0.5.2 Jul 19, 2024

#471 in Database interfaces

Download history 49/week @ 2024-10-02 164/week @ 2024-10-09 60/week @ 2024-10-16 8/week @ 2024-10-23 59/week @ 2024-10-30 8/week @ 2024-11-06 77/week @ 2024-11-13 412/week @ 2024-11-20 253/week @ 2024-11-27 381/week @ 2024-12-04 149/week @ 2024-12-11 332/week @ 2024-12-18 12/week @ 2024-12-25 111/week @ 2025-01-01 200/week @ 2025-01-08 239/week @ 2025-01-15

564 downloads per month
Used in 4 crates

MIT license

305KB
5K SLoC

GeekORM

GitHub Crates.io Version Crates.io Downloads (recent) GitHub Stars GitHub Issues Licence

Overview

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

✨ Features

  • 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
  • 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

📦 Installation

🦀 Library

You can install the library from crates.io:

cargo add geekorm
Add the backend driver you want to use
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

🛠️ CLI

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

🏃 Getting Started

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

🏎️ Setting Up Migrations

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

🚀 Writing your first model

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 conn = rusqlite::Connection::open_in_memory().expect("Failed to open database");

    // 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(())
}

🏄 Create Features

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

🧑‍🤝‍🧑 Maintainers / Contributors

Mathew Payne
Mathew Payne

💻 👀
Cale
Cale

🎨

🦸 Support

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.

📓 License

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

Dependencies

~2–13MB
~165K SLoC