orbit-orm 0.4.0

An ORM for Rocket.rs apps, with MySQL and MariaDB, PostgreSQL and SQLite
Documentation

orbit-orm

Orbit is an ORM for Rocket.rs apps. It works with MySQL and MariaDB, PostgreSQL and SQLite.

Install

cargo add orbit-orm

Each database is a Cargo feature. mysql is on by default; enable the others, or turn mysql off:

Feature Database Default
mysql MySQL and MariaDB yes
postgres PostgreSQL no
sqlite SQLite (file or memory) no 
cargo add orbit-orm --features postgres
cargo add orbit-orm --no-default-features --features sqlite,derive

For the synchronous API, also enable the blocking feature:

cargo add orbit-orm --features blocking

Connect

The database is chosen by the URL's scheme. A scheme whose feature is not enabled is an error.

Database URL
MySQL mysql://user:password@host:3306/database
MariaDB mariadb://user:password@host:3306/database
PostgreSQL postgres://user:password@host:5432/database
SQLite sqlite:///absolute/path/app.db?mode=rwc, or sqlite://relative/app.db?mode=rwc

mode=rwc creates the SQLite file when it does not exist. A PostgreSQL URL must name the user: without one, sqlx connects as the role anonymous, which usually does not exist. sqlite::memory: is an in-memory database, one per connection.

MySQL:

use orbit_orm::Database;

let db = Database::connect("mysql://user:password@127.0.0.1/app").await?;
db.ping().await?;

PostgreSQL:

use orbit_orm::Database;

let db = Database::connect("postgres://user:password@127.0.0.1/app").await?;
db.ping().await?;

SQLite:

use orbit_orm::Database;

let db = Database::connect("sqlite:///var/lib/app/app.db?mode=rwc").await?;
db.ping().await?;

Call db.close().await to shut the connection pool down.

connect opens at most 5 connections and waits up to 10 seconds for one. To change that, pass PoolOptions to connect_with. Fields you leave out keep their defaults:

use std::time::Duration;
use orbit_orm::{Database, PoolOptions};

let db = Database::connect_with(
    "mysql://user:password@127.0.0.1/app",
    PoolOptions {
        max_connections: 10,
        acquire_timeout: Duration::from_secs(5),
        min_connections: 2,
    },
)
.await?;

Models and queries

A model maps a table to a Rust type and names the columns it may write. The OrbitModel derive writes the row mapping and the model from attributes. Without table, the table is the plural of the struct name, as in Laravel: Flight uses flights, UserProfile uses user_profiles.

use orbit_orm::OrbitModel;

#[derive(OrbitModel)]
#[orbit(table = "posts")]
struct Post {
    id: i64,
    #[orbit(fillable)]
    title: String,
    #[orbit(column = "view_count", fillable)]
    views: Option<i64>,
}

#[orbit(primary_key = "...")] sets the primary key, and #[orbit(skip)] leaves a field out of the row.

Without the derive, write the two impls by hand. Rows are read with sqlx's FromRow:

use orbit_orm::{Database, Direction, Model, Operator, Query};
use sqlx::mysql::MySqlRow;
use sqlx::{FromRow, Row};

struct Post {
    id: i64,
    title: String,
    views: i64,
}

impl<'r> FromRow<'r, MySqlRow> for Post {
    fn from_row(row: &'r MySqlRow) -> Result<Self, sqlx::Error> {
        Ok(Self {
            id: row.try_get("id")?,
            title: row.try_get("title")?,
            views: row.try_get("views")?,
        })
    }
}

impl Model for Post {
    const TABLE: &'static str = "posts";
    const FILLABLE: &'static [&'static str] = &["title", "views"];
}

let popular = Post::query()
    .where_op("views", Operator::Ge, 100)
    .order_by("views", Direction::Desc)
    .limit(10)
    .get(&db)
    .await?;

let post = Post::query().find_or_fail(&db, 1).await?;
let id = Query::<Post>::table().insert(&db, &[("title", "Hello".into())]).await?;

Methods: get, first, first_or_fail, find, find_or_fail, count, exists, insert, update, delete, replace, get_as and first_as.

get_as and first_as take the same clauses as get and first, but decode each row as any type that implements sqlx's FromRow. With select, that reads only some columns, into a tuple or a struct with only those fields:

let titles = Post::query()
    .select(&["id", "title"])
    .order_by("id", Direction::Asc)
    .get_as::<(i64, String)>(&db)
    .await?;

Filters: where_eq, where_op, where_in, where_null, where_not_null, and the or_where_* variants, which join with OR. Sorting and paging: order_by, select, limit, offset. Row locks: for_update.

Conditions are grouped in parentheses with where_group and or_where_group:

let posts = Post::query()
    .where_op("views", Operator::Ge, 100)
    .where_group(|q| q.where_eq("title", "Hello").or_where_eq("title", "Hi"))
    .get(&db)
    .await?;

Values are always bound as parameters. Table and column names are quoted, and a name that is empty or contains a backtick is an error.

insert and update accept only columns listed in FILLABLE. Any other column returns Error::NotFillable.

replace writes a row the way MySQL's REPLACE INTO does: it overwrites the row that has the same unique key, and returns the rows affected.

let affected = Query::<Post>::table()
    .replace(&db, &[("title", "Hello".into())])
    .await?;

Timestamps and bytes

Value has DateTime(NaiveDateTime), Date(NaiveDate) and Bytes(Vec<u8>), with From impls. They bind to DATETIME (with microseconds), DATE and BLOB columns, and the same types read back. A model field can use NaiveDateTime, NaiveDate or Vec<u8>:

use chrono::{NaiveDate, NaiveDateTime};

let published = NaiveDateTime::parse_from_str("2026-11-10 18:35:07.123456", "%Y-%m-%d %H:%M:%S%.f")?;
let id = Query::<Post>::table()
    .insert(
        &db,
        &[
            ("published_at", Value::from(published)),
            ("day", Value::from(NaiveDate::from_ymd_opt(2026, 11, 10).unwrap())),
            ("thumbnail", Value::from(vec![0x89, 0x50, 0x00])),
        ],
    )
    .await?;

A NaiveDateTime has no time zone, and Orbit does not convert it.

Blocking API

With the blocking feature, orbit_orm::blocking has the same terminal methods without async. Build the query as usual, then call blocking():

use orbit_orm::blocking::Database;

let db = Database::connect("mysql://user:password@127.0.0.1/app")?;
let post = Post::query().blocking().find_or_fail(&db, 1)?;

db.transaction(|tx| {
    Post::query().blocking().insert(tx, &[("title", "Hello".into())])?;
    Ok::<_, orbit_orm::Error>(())
})?;

In async code, call it from tokio::task::spawn_blocking. See docs/blocking.md for how it runs and how its transactions roll back.

Transactions

transaction runs a closure in a transaction. It commits when the closure returns Ok and rolls back when it returns Err or panics. Pass the transaction to queries as &mut *tx; a query given &db runs outside it.

use orbit_orm::{Database, Error, Model};

let id = db
    .transaction(async |tx| {
        let id = Post::query()
            .insert(&mut *tx, &[("title", "Hello".into())])
            .await?;
        Post::query().where_eq("id", id).for_update().first_or_fail(&mut *tx).await?;
        Ok::<_, Error>(id)
    })
    .await?;

for_update locks the matching rows. In a transaction the lock lasts until it ends. Outside one, the statement runs in autocommit and the lock lasts only for that statement, as in Laravel. tx.connection() gives the raw connection for SQL that Orbit does not wrap.

Errors

Some database errors have their own variants, so they can be matched:

match Post::query().insert(&db, &[("title", "Hello".into())]).await {
    Ok(id) => println!("inserted {id}"),
    Err(Error::UniqueViolation { index }) => println!("unique index {index:?} was violated"),
    Err(Error::ForeignKeyViolation { constraint }) => println!("foreign key {constraint:?} was violated"),
    Err(Error::Deadlock) | Err(Error::LockWaitTimeout) => println!("retry the transaction"),
    Err(other) => return Err(other),
}

UniqueViolation and ForeignKeyViolation carry the index or constraint name when the server reports it. Other errors are Error::Database.

Raw SQL

orbit_orm::raw runs SQL that the query builder does not cover. Each function takes &db or &mut *tx, as the terminal methods do:

use orbit_orm::{Value, raw};

let changed = raw::execute(&db, "UPDATE posts SET views = views + 1 WHERE id = ?", &[Value::from(1)]).await?;
let popular: Vec<(i64, String)> = raw::fetch_all(&db, "SELECT id, title FROM posts WHERE views >= ?", &[Value::from(100)]).await?;
let post: Option<(i64, String)> = raw::fetch_optional(&db, "SELECT id, title FROM posts WHERE id = ?", &[Value::from(1)]).await?;
let count: i64 = raw::fetch_scalar(&db, "SELECT COUNT(*) FROM posts", &[]).await?;
  • execute returns the rows affected. fetch_all and fetch_optional decode each row as T: FromRow, and fetch_scalar decodes the first column of the first row. It is an error when no row comes back.
  • The SQL string is not escaped and is not checked. It must not contain user input. Put every value in the binds, in the order of the ? placeholders.
  • LAST_INSERT_ID() belongs to one connection, so read it in the transaction that made the insert:
let id: u64 = db
    .transaction(async |tx| {
        raw::execute(&mut *tx, "INSERT INTO posts (title) VALUES (?)", &[Value::from("Hello")]).await?;
        raw::fetch_scalar(&mut *tx, "SELECT LAST_INSERT_ID()", &[]).await
    })
    .await?;

Migrations

A migration is a folder named <timestamp>_<name>, such as 20261108000000_create_users, with an up.sql and a down.sql. The timestamp is 14 digits (YYYYMMDDHHMMSS). Migrations run in name order.

use orbit_orm::{Database, Migrator};

let db = Database::connect(&url).await?;
let migrator = Migrator::from_dir("migrations")?;

migrator.run(&db).await?;                  // applies every pending migration as one batch
let status = migrator.status(&db).await?;  // each migration as Applied (with its batch) or Pending
migrator.rollback(&db).await?;             // reverts the last batch, in reverse order

A migration can also be written in code with the schema builder, so one migration serves every database. Migration::schema(name, up, down) takes the up and down statements, and the migrator renders them for the connected database when it runs or rolls back the migration:

use orbit_orm::{schema, Migration, Migrator};

let users = Migration::schema(
    "20261108000000_create_users",
    vec![schema::create("users", |t| {
        t.id();
        t.string("email");
        t.unique(["email"]);
    })],
    vec![schema::drop_if_exists("users")],
);
let migrator = Migrator::new(vec![users])?;

A statement that cannot be rendered (an invalid table name, for example) fails the migration with that error before any of its SQL runs. Batches, the per-migration transaction and the DDL caveat below are the same as for SQL migrations. The public up and down fields of a schema migration are empty.

migrations!("migrations", "20261108000000_create_users") embeds the files in the binary at build time. List the names by hand; a missing file is a build error.

Migrations are recorded in Diesel's __diesel_schema_migrations table, so a database that Diesel migrated keeps its history. run, status and rollback add the batch column to a table that has only Diesel's columns, so nothing needs to be imported first. unmatched_diesel_versions lists the versions in the table that have no folder in the migrator.

Each recorded migration has its batch number. Each migration runs in its own transaction. MySQL does not roll back DDL, so a failing migration can leave the DDL it ran before the failure in place; only its DML is rolled back.

run and rollback hold a lock named after the database: a named lock on MySQL, an advisory lock on PostgreSQL. A second process waits up to 10 seconds, then fails with MigrationsLocked. Change the wait with Migrator::with_lock_timeout. SQLite has no named lock, so its lock covers one process only; see docs/laravel-differences.md.

Schema builder

orbit_orm::schema describes a table once and renders it for SQLite, MySQL and MariaDB, and PostgreSQL, after Laravel's Schema::create and Blueprint:

use orbit_orm::schema::{self, Action};

let posts = schema::create("posts", |t| {
    t.id();
    t.string("title");
    t.text("body").nullable();
    t.big_integer("user_id");
    t.foreign("user_id").references("users", "id").on_delete(Action::Restrict);
    t.unique(["title"]);
    t.timestamps();
});

for sql in posts.to_sql(db.driver()) {
    orbit_orm::raw::execute(&db, &sql, &[]).await?;
}

to_sql returns one SQL statement per element, to run in order: PostgreSQL and SQLite create a plain index with a separate CREATE INDEX. Columns are NOT NULL unless nullable(). id() is BIGINT AUTO_INCREMENT PRIMARY KEY on MySQL, BIGSERIAL PRIMARY KEY on PostgreSQL and INTEGER PRIMARY KEY AUTOINCREMENT on SQLite. string is VARCHAR(255) (TEXT on SQLite; change the length with .length(n)). Also: text, integer, big_integer, boolean, date_time, timestamp, binary, timestamps, index, primary, schema::table, schema::create_if_not_exists, schema::drop, schema::drop_if_exists and schema::statement. Names follow the query builder's rule, so try_to_sql returns Error::InvalidIdentifier for a name that is empty or has a quote character; to_sql panics in that case. An operation the database cannot do is Error::Unsupported.

Changing a table

schema::table changes an existing table, as Laravel's Schema::table. A column described in the closure is added. A column that ends with .change() is modified: it takes the type, nullability and default described. rename_column and drop_column rename and drop columns:

use orbit_orm::schema;

let posts = schema::table("posts", |t| {
    t.string("subtitle").nullable();
    t.string("title").length(100).change();
    t.rename_column("body", "content");
    t.drop_column("legacy_slug");
});

Each operation is its own statement, run in the order it was called, as in Laravel 11 and later. So t.drop_column("slug"); t.string("slug"); drops the column and adds it again, and t.rename_column("name", "full_name"); t.string("name"); renames a column and adds a new one under the old name. SQLite cannot change a column in place, so .change() is Error::Unsupported there. On SQLite, a column added to a table that has rows cannot take use_current ("Cannot add a column with non-constant default"), and a NOT NULL column needs a default; Laravel has the same limit. rename_column needs MySQL 8.0.3 or MariaDB 10.5.2 or later, or SQLite 3.25 or later, and drop_column needs SQLite 3.35 or later.

Indexes and keys

index, unique and foreign take .name() to choose the name. Without it the name is Laravel's: {table}_{columns}_index, {table}_{columns}_unique or {table}_{column}_foreign. drop_index and drop_foreign take the name:

use orbit_orm::schema::{self, Action};

let up = schema::table("posts", |t| {
    t.index(["user_id"]).name("posts_author_index");
    t.foreign("user_id").references("users", "id").on_delete(Action::Cascade);
});

let down = schema::table("posts", |t| {
    t.drop_foreign("posts_user_id_foreign");
    t.drop_index("posts_author_index");
});

primary(["team_id", "user_id"]) adds a primary key over several columns. For one column, .primary() on the column does the same, for a key that is not an id(), such as t.string("token").length(64).primary().

SQLite cannot add or drop a constraint on an existing table. There, a foreign in schema::table and drop_foreign render nothing, and primary in schema::table is Error::Unsupported. drop_index drops a unique index on MySQL, and on SQLite when schema::table added it. It does not drop a unique on PostgreSQL, and there is no drop_unique; see docs/laravel-differences.md.

Column types

binary is a column of raw bytes. timestamp is a TIMESTAMP, after Laravel's timestamp. .precision(p) sets the fractional seconds of a date_time or timestamp, from 0 to 6, and .use_current() makes the current time its default:

use orbit_orm::schema;

let sessions = schema::create("sessions", |t| {
    t.string("id").length(128).primary();
    t.binary("payload");
    t.timestamp("last_seen_at").precision(6).use_current();
    t.date_time("expires_at").nullable();
});

binary is BLOB, or BYTEA on PostgreSQL. timestamp is TIMESTAMP on MySQL, TIMESTAMP(0) WITHOUT TIME ZONE on PostgreSQL and DATETIME on SQLite. SQLite keeps DATETIME whatever the precision. use_current is DEFAULT CURRENT_TIMESTAMP, or CURRENT_TIMESTAMP(p) on MySQL when the precision is above 0.

text is TEXT on every database. On MySQL and MariaDB, TEXT holds up to 64 KB. For larger values, medium_text and long_text follow Laravel's mediumText and longText:

use orbit_orm::schema;

let posts = schema::create("posts", |t| {
    t.id();
    t.string("title");
    t.text("excerpt");
    t.medium_text("summary");
    t.long_text("content");
});

medium_text is MEDIUMTEXT (up to 16 MB) and long_text is LONGTEXT (up to 4 GB) on MySQL and MariaDB. Both are TEXT on PostgreSQL, where text has no size limit, and on SQLite, where text is limited only by the database's size limits. WordPress stores post content and option and meta values as LONGTEXT.

Creating a table if it does not exist

schema::create_if_not_exists renders CREATE TABLE IF NOT EXISTS. An existing table is left as it is, even when its columns differ:

use orbit_orm::schema;

let users = schema::create_if_not_exists("users", |t| {
    t.id();
    t.string("email");
    t.string("name");
    t.unique(["email"]);
    t.index(["name"]);
});

Laravel has no such method; a Laravel migration checks Schema::hasTable first. On PostgreSQL and SQLite, a plain index takes CREATE INDEX IF NOT EXISTS, so it is still created when the table already exists.

Raw statements

schema::statement runs SQL as written, as Laravel's DB::statement in a migration. .only(Dialect) limits a statement to one database family; on the others it renders nothing:

use orbit_orm::schema::{self, Dialect};

let seed = schema::statement("INSERT INTO roles (name) VALUES ('admin')");
let avatar = schema::statement("ALTER TABLE users MODIFY avatar MEDIUMBLOB").only(Dialect::MySql);

The SQL is database-specific. Orbit does not check, quote or translate it, and runs the same string on every database unless only limits it. It takes no bound values, so it must not contain user input. only works on every statement, including create, table and drop.

Tests

The database tests run against the database that ORBIT_DATABASE_URL names. Run them once per database, with the matching feature:

ORBIT_DATABASE_URL='mysql://user:password@127.0.0.1:3306/orbit_test' cargo test
ORBIT_DATABASE_URL='postgres://user:password@127.0.0.1:5432/orbit_test' cargo test --no-default-features --features postgres
ORBIT_DATABASE_URL='sqlite:///tmp/orbit_test.db?mode=rwc' cargo test --no-default-features --features sqlite

Without ORBIT_DATABASE_URL, the database tests are skipped. The tests create and drop their own tables.

Differences from Laravel

See docs/laravel-differences.md.

License

MIT. Copyright (c) 2026 Jenny Martinez.