Lorm - A light ORM for SQLx

Lorm is an async and lightweight ORM for SQLx that uses derive macros to generate type-safe database operations at compile time.

Features

• Zero-cost abstractions - All code is generated at compile time
• Type-safe queries - Leverages Rust's type system for compile-time query validation
• Async-first - Built on tokio and async/await
• Automatic CRUD - Generate create, read, update, and delete operations
• Flexible querying - Builder pattern for complex queries with filtering, ordering, and pagination
• Pool and Transaction support - Works seamlessly with both connection pools and transactions
• Timestamp management - Automatic handling of created_at and updated_at fields
• Custom field generation - Support for UUID, custom types, and database-generated values

Quickstart

Installation

Add Lorm to your Cargo.toml:

[dependencies]
lorm = "0.2"
sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite"] }
tokio = { version = "1", features = ["full"] }
uuid = { version = "1", features = ["v4"] }
chrono = "0.4"

Note: Replace sqlite with your preferred database driver (postgres, mysql).

Supported Databases

Lorm supports almost all databases that SQLx supports:

• PostgreSQL - Use features = ["postgres"] in sqlx
• MySQL / MariaDB - Use features = ["mysql"] in sqlx
• SQLite - Use features = ["sqlite"] in sqlx

All features work consistently across database backends.

Usage

Define your model by adding #[derive(ToLOrm)] alongside SQLx's #[derive(FromRow)]:

use sqlx::{FromRow, SqlitePool};
use lorm::ToLOrm;
use uuid::Uuid;

#[derive(Debug, Default, FromRow, ToLOrm)]
struct User {
    #[lorm(pk, new = "Uuid::new_v4()")]
    pub id: Uuid,

    #[lorm(by)]
    pub email: String,

    #[lorm(created_at, new = "chrono::Utc::now().fixed_offset()")]
    pub created_at: chrono::DateTime<chrono::FixedOffset>,

    #[lorm(updated_at, new = "chrono::Utc::now().fixed_offset()")]
    pub updated_at: chrono::DateTime<chrono::FixedOffset>,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pool = SqlitePool::connect("sqlite::memory:").await?;

    // Create a user
    let mut user = User::default();
    user.email = "alice@example.com".to_string();
    user.save(&pool).await?;

    // Find by email (generated from #[lorm(by)])
    let found = User::by_email(&pool, "alice@example.com").await?;
    println!("Found user: {}", found.email);

    // Update the user
    user.email = "alice.updated@example.com".to_string();
    user.save(&pool).await?;

    // Delete the user
    user.delete(&pool).await?;

    Ok(())
}

Lorm works seamlessly with both Pool and Transaction connections. Check the tests directory for more examples.

Attribute Reference

Lorm provides several attributes to customize code generation. Attributes can be applied at struct level or field level.

Field-Level Attributes

Struct-Level Attributes

Naming Conventions

• Table names: Struct name pluralized and converted to snake_case
  • User → users
  • UserDetail → user_details
• Column names: Field name converted to snake_case
  • userId → user_id
  • createdAt → created_at

Attribute Combinations

Common attribute combinations:

// Auto-generated UUID primary key
#[lorm(pk, new = "Uuid::new_v4()")]
pub id: Uuid

// Timestamp managed by application
#[lorm(created_at, new = "chrono::Utc::now().fixed_offset()")]
pub created_at: DateTime<FixedOffset>

// Timestamp managed by database
#[lorm(created_at, readonly)]
pub created_at: DateTime<FixedOffset>

Query Builder API

Lorm generates a fluent query builder using ::select(). The builder supports filtering, ordering, grouping, and pagination.

Available Methods

Filtering (available for #[lorm(by)] fields):

• where_{field}(Where::Eq, value) - Equals comparison
• where_{field}(Where::NotEq, value) - Not equals comparison
• where_{field}(Where::GreaterThan, value) - Greater than
• where_{field}(Where::GreaterOrEqualTo, value) - Greater than or equal
• where_{field}(Where::LesserThan, value) - Less than
• where_{field}(Where::LesserOrEqualTo, value) - Less than or equal
• where_between_{field}(start, end) - Between two values (inclusive)

Ordering (available for #[lorm(by)] fields):

• order_by_{field}().asc() - Ascending order
• order_by_{field}().desc() - Descending order

Grouping (available for #[lorm(by)] fields):

• group_by_{field}() - Group results by field

Pagination:

• limit(n) - Limit number of results
• offset(n) - Skip first n results

Query Examples

use lorm::predicates::Where;

// Simple query with exact match
let users = User::select()
    .where_email(Where::Eq, "alice@example.com")
    .build(&pool)
    .await?;

// Filtering and ordering
let recent_users = User::select()
    .where_created_at(Where::GreaterOrEqualTo, yesterday)
    .order_by_created_at()
    .desc()
    .build(&pool)
    .await?;

// Pagination
let page_2 = User::select()
    .order_by_email()
    .asc()
    .limit(10)
    .offset(10)
    .build(&pool)
    .await?;

// Complex query combining multiple conditions
let results = User::select()
    .where_between_id(100, 200)
    .where_email(Where::NotEq, "banned@example.com")
    .order_by_created_at()
    .desc()
    .limit(20)
    .build(&pool)
    .await?;

// Grouping with ordering
let grouped = User::select()
    .group_by_email()
    .group_by_id()
    .order_by_email()
    .asc()
    .build(&pool)
    .await?;

Direct Field Queries

For fields marked with #[lorm(by)], convenience methods are generated:

// Find single record by field (returns first match)
let user = User::by_email(&pool, "alice@example.com").await?;

// Find all records matching field value
let users = User::with_email(&pool, "alice@example.com").await?;

// Delete a specific record (by primary key)
user.delete(&pool).await?;

Examples

Complete, runnable examples are available in the examples/ directory:

• basic_crud.rs - Create, read, update, and delete operations
• query_builder.rs - Advanced querying with filtering, ordering, and pagination
• transactions.rs - Transaction handling and atomic operations

Run an example with:

cargo run --example basic_crud -p lorm

Additional examples are documented in the test cases at tests/main.rs.

FAQ

How does Lorm differ from Diesel?

Lorm is significantly lighter and simpler than Diesel:

• Lorm: Focused on CRUD operations with SQLx integration, minimal features
• Diesel: Full-featured ORM with query builder, migrations, and advanced relationship handling

Choose Lorm for simple CRUD with SQLx, choose Diesel for comprehensive ORM features.

How does Lorm compare to SeaORM?

• Lorm: Lightweight macro-based code generation, no runtime overhead, limited to CRUD
• SeaORM: Full async ORM with entities, relations, migrations, and active record pattern

Lorm is better for simple use cases; SeaORM is better for complex applications with relationships.

Can I use raw SQL with Lorm?

Yes! Lorm is built on SQLx, so you can mix Lorm-generated methods with raw SQLx queries:

// Use Lorm for simple operations
let user = User::by_email(&pool, "alice@example.com").await?;

// Use SQLx for complex queries
let results = sqlx::query_as::<_, User>(
    "SELECT * FROM users WHERE created_at > ? AND status = ?"
)
.bind(yesterday)
.bind("active")
.fetch_all(&pool)
.await?;

Does Lorm support relationships/joins?

No. Lorm focuses on single-table CRUD operations. For relationships and joins, use SQLx directly.

How do I handle migrations?

Lorm doesn't provide migrations. Use:

• SQLx migrations: Built-in support with sqlx migrate
• Refinery: Alternative migration tool
• Custom scripts: SQL files or custom tooling

What's the compile-time impact?

Lorm uses proc macros which add to compile time, but the impact is minimal for small to medium projects. The generated code is optimized and adds no runtime overhead.

Can I inspect the generated code?

Yes! Use cargo expand to see exactly what code Lorm generates:

cargo install cargo-expand
cargo expand --test main

Does Lorm work with connection pools?

Yes! Lorm works seamlessly with both:

• SQLx connection pools (Pool)
• Transactions (Transaction)

The same methods work with both.

How do I handle composite primary keys?

Lorm currently supports single-field primary keys only. For composite keys, use SQLx directly.

Can I customize the SQL queries Lorm generates?

No. Lorm generates standard CRUD operations. For custom queries, use SQLx alongside Lorm.

Is Lorm production-ready?

Lorm is in early development (0.x.y versions). The API may change. Use with caution in production and pin your version.

Design Philosophy

Lorm is designed to be:

• Lightweight - Minimal runtime overhead with compile-time code generation
• Pragmatic - Cover 80% of common use cases without complexity
• Composable - Works alongside raw SQLx queries when needed
• Transparent - Generated code can be inspected with cargo expand

Requirements

• Rust Edition: 2024 or later
• SQLx: 0.8 or later
• Tokio: 1.0 or later (for async runtime)

Limitations

• No automatic schema migrations (use SQLx migrations or other tools)
• No relationships/joins (use SQLx for complex queries)
• Requires Default trait on structs for most operations
• Primary key field name detection is attribute-based, not convention-based

When to Use Lorm

Use Lorm when:

• You need simple CRUD operations
• You want type safety with minimal boilerplate
• You're building on top of SQLx
• You want explicit control over your database schema

Consider alternatives when:

• You need complex relationships and joins
• You want automatic schema migrations
• You need an Active Record pattern
• You require ORM-managed relationships

License

Licensed under Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

Contribution

Unless you explicitly state otherwise, any Contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.