#sqlite #sql #orm

geekorm

A simple and easy to use ORM for SQLite databases

52 releases (10 breaking)

Uses new Rust 2024

0.11.4 Mar 16, 2025
0.10.2 Mar 4, 2025
0.8.3 Dec 20, 2024
0.7.2 Nov 26, 2024
0.5.2 Jul 19, 2024

#260 in Database interfaces

Download history 12/week @ 2024-12-25 111/week @ 2025-01-01 200/week @ 2025-01-08 239/week @ 2025-01-15 22/week @ 2025-01-22 8/week @ 2025-01-29 33/week @ 2025-02-05 242/week @ 2025-02-12 65/week @ 2025-02-19 115/week @ 2025-02-26 184/week @ 2025-03-05 572/week @ 2025-03-12 29/week @ 2025-03-19 26/week @ 2025-03-26 9/week @ 2025-04-02 66/week @ 2025-04-09

161 downloads per month
Used in 4 crates

MIT license

325KB
5.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 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(())
}

🏄 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–14MB
~164K SLoC