rullst-orm-macros 6.0.2

🚀 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.
• 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.
• 5. Security & Testing: Execution order for Miri, Kani, Fuzzing, and Mutation tools.

🛡️ 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.