rullst-orm 6.1.1

🚀 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.

[!WARNING] Kani Verifier is currently configured to allow failures (continue-on-error). It lacks upstream support for Rust 1.94+ (required by sqlx 0.9.0), so its badge may show as passing even if the pipeline was skipped or failed due to compiler incompatibility. Once Kani updates its compiler base, it will automatically run and pass again.

🚀 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.
• Data Governance & Privacy: Compile-time GDPR/LGPD compliance with at-rest encryption and log masking.
• Scout Search: Seamlessly sync models to full-text search engines.
• Database-First Introspection: The official framework CLI (cargo rullst generate:models) connects to legacy databases and generates your #[derive(Orm)] Rust structs automatically.
• Type-Safe Partial Updates: Virtual dirty checking with .update_partial() to intelligently modify only changed columns.
• Model Policies (Authorization): Laravel-style fine-grained access control securely tied to your structs via #[orm(policy = "MyPolicy")].
• Strict Lazy Loading Prevention: Enable a global toggle to instantly panic on N+1 queries during development.
• 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

We recently launched a brand-new Interactive Documentation Hub powered by VitePress!

👉 Explore the Full Documentation

Dive into the modules below to master Rullst ORM:

• Basics & Query Builder: Connecting to the DB, filtering, sorting, and raw bindings.
• Relationships: Has Many, Belongs To, Polymorphic relations, and Eager Loading.
• Advanced Features: Multi-Tenancy, Audit Trails, Redis Caching, and Observers.
• Migrations & Schema: Building tables programmatically and using the Artisan CLI.
• Security & Testing: UB detection, Fuzzing, Mutation testing, and CI pipelines.
• New Features: Native Enum Mapping and Partial Updates.

🎮 Try the Interactive Playground: Test our fluent query builder in a simulated environment!

🛡️ 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 highly-optimized O(N) linear byte scan (zero regex overhead) to guarantee absolute SQL safety without sacrificing performance.

📄 License

This project is licensed under the MIT License.