Rusqlite Migration

Rusqlite Migration is a small schema migration library built specifically for the rusqlite crate. Instead of creating a metadata table to track applied migrations like most migration tools, it stores the current schema version in SQLite’s built-in user_version pragma, which is just an integer at a fixed offset in the database file. That avoids the overhead of parsing and querying an extra table on every database open, and keeps the migration runner’s own footprint small since there are no macros involved in defining migrations.

Migrations are plain SQL strings defined as M::up("...") entries in a Migrations value, applied atomically with .to_latest(&mut conn). The crate also supports downward migrations, loading .sql files from a directory via the optional from-directory feature, and validating a migration set’s integrity in tests with .validate().

What You Get

• A Migrations/M API for defining ordered SQL migrations as plain strings, with no macros required
• Version tracking via SQLite’s built-in user_version pragma instead of a bookkeeping table, keeping database opens fast
• Atomic .to_latest(&mut conn) application of all pending migrations in one transaction
• Support for downward (rollback) migrations alongside forward ones
• An optional from-directory feature to load migrations from .sql files in a directory instead of inline strings
• A .validate() method for asserting migration integrity in your own test suite, plus insta snapshot compatibility

Common Use Cases

• Rust CLI tools and desktop apps that ship an embedded SQLite database and need to evolve its schema across versions
• Server backends using rusqlite that want migrations without pulling in a heavier ORM’s migration system
• Projects needing fast startup time, since checking migration state only reads a single pragma value rather than querying a table
• Teams that want migrations loaded from a directory of .sql files for easier review and version control

Under The Hood

Architecture - The workspace splits the migration engine (rusqlite_migration/src/lib.rs, builder.rs, loader.rs) from a separate rusqlite_migration_tests integration-test crate and a rusqlite_migration_benches benchmarking crate, keeping the core library free of test-only dependencies; loader.rs (148 lines) implements the optional directory-based migration loading behind the from-directory feature flag, while lib.rs (976 lines) holds the core Migrations/M types and the user_version-based version tracking. Tech Stack - Rust 2021 edition, Apache-2.0 licensed, built directly on rusqlite with an optional include_dir dependency for the directory-loading feature; the crate explicitly avoids proc-macros to keep compile times low, per the README’s stated design goals. Code Quality - 16 files across the repo contain #[test] blocks, and the project publishes coverage via Coveralls and uses cargo-mutants for mutation testing per its contributing docs, plus an unsafe forbidden badge indicating no unsafe code in the core crate. API Design - The API is deliberately minimal: migrations are declared as a &[M] slice of plain SQL strings and applied with a single .to_latest() call, so there’s very little to learn beyond that one entry point, and the crate’s own test suite doubles as a documented pattern (assert!(MIGRATIONS.validate().is_ok())) for validating a project’s migration set.