rullst-orm 5.0.0

🚀 Visit the Official Website & Documentation Hub 🚀

Built on top of sqlx and procedural macros, Rullst ORM brings the delightful, fluent syntax of Active Record frameworks (like Laravel's Eloquent) directly to the high-performance Rust ecosystem.

🚀 Why Rullst ORM?

In traditional Rust database handling, you have to write raw SQL queries, manage connection pools manually, and bind variables repetitively. Rullst ORM abstracts the heavy lifting behind a single #[derive(Orm)] macro, generating hundreds of safe, chainable query methods at compile time.

Key Features:

• Zero-Boilerplate CRUD: Insert, update, delete, and find records instantly.
• Fluent Query Builder: Chain .where_eq(), .limit(), and .order_by() effortlessly.
• Eager Loading: Solve N+1 problems with robust has_many, belongs_to, and morph_many relations.
• Built-in Multi-Tenancy: Automatically scope all queries by tenant ID.
• Automated Audit Logs: Track old_values and new_values history natively.
• Scout Search: Seamlessly sync models to full-text search engines.
• Enterprise Ready: Read/write replica splitting, query chunking, and Redis caching built-in.

🛠️ Quick Start

Installation

Add the library to your Cargo.toml:

cargo add rullst-orm
cargo add tokio -F full

Zero-to-Hero Example

use rullst_orm::{Orm, FromRow};

// 1. Just add the Orm macro to your struct!
#[derive(Debug, Clone, FromRow, Orm)]
pub struct User {
    pub id: i32, // ID = 0 means it hasn't been saved yet
    pub name: String,
    pub email: String,
    #[orm(hidden)] // Won't be exposed in JSON responses
    pub password: String,
}

#[tokio::main]
async fn main() -> Result<(), rullst_orm::Error> {
    // 2. Initialize the connection pool (Supports SQLite, Postgres, MySQL)
    Orm::init("sqlite::memory:").await?;

    // 3. Create a new user magically
    let mut user = User {
        id: 0,
        name: "Alice".to_string(),
        email: "alice@example.com".to_string(),
        password: "secret_password".to_string(),
    };
    
    user.save().await?; // Runs INSERT and hydrates the ID automatically!

    // 4. Fluent Queries
    let active_users = User::query()
        .where_like("email", "%@example.com")
        .order_by_desc("id")
        .limit(10)
        .get()
        .await?;

    println!("Found users: {:?}", active_users);

    Ok(())
}

📚 Documentation

The documentation is kept lean and straight to the point. Dive into the modules below to master Rullst ORM:

• 1. Basics & Query Builder: Connecting to the DB, filtering, sorting, and raw bindings.
• 2. Relationships: Has Many, Belongs To, Polymorphic relations, and Eager Loading.
• 3. Advanced Features: Multi-Tenancy, Audit Trails, Redis Caching, and Observers.
• 4. Migrations & Schema: Building tables programmatically and using the Artisan CLI.

🛡️ Security

Rullst ORM employs rigorous defenses against SQL Injection. All dynamic builder methods (like .where_eq()) automatically escape values using sqlx prepared statement bindings ($1 or ?). Raw queries (.where_raw()) actively force developers to provide an array of bindings directly in the function signature. Furthermore, all structural identifiers (table and column names) are validated strictly at runtime against a whitelist regex.

📄 License

This project is licensed under the MIT License.