Rusqlite Migration

Rusqlite Migration is a simple schema migration library for rusqlite using user_version instead of an SQL table to maintain the current schema version.

It aims for:

• simplicity: define a set of SQL statements. Just add more SQL statement to change the schema. No external CLI, no macro.
• performance: no need to add a table to be parsed, the user_version field is at a fixed offset in the sqlite file format.

It works especially well with other small libraries complementing rusqlite, like serde_rusqlite.

Example

Here, we define SQL statements to run with Migrations::new and run these (if necessary) with .to_latest().

use rusqlite::{params, Connection};
use rusqlite_migration::{Migrations, M};

// 1️⃣ Define migrations
let migrations = Migrations::new(vec![
    M::up("CREATE TABLE friend(name TEXT NOT NULL);"),
    // In the future, add more migrations here:
    //M::up("ALTER TABLE friend ADD COLUMN email TEXT;"),
]);

let mut conn = Connection::open_in_memory().unwrap();

// Apply some PRAGMA, often better to do it outside of migrations
conn.pragma_update(None, "journal_mode", &"WAL").unwrap();

// 2️⃣ Update the database schema, atomically
migrations.to_latest(&mut conn).unwrap();

// 3️⃣ Use the database 🥳
conn.execute("INSERT INTO friend (name) VALUES (?1)", params!["John"])
    .unwrap();

Please see the examples folder for more, in particular:

• migrations with multiple SQL statements (using for instance r#"…" or include_str!(…))
• use of lazy_static
• migrations to previous versions (downward migrations)

I’ve also made a cheatsheet of SQLite pragma for improved performance and consistency.

Built-in tests

To test that the migrations are working, you can add this in your test module:

#[test]
fn migrations_test() {
    assert!(MIGRATIONS.validate().is_ok());
}

Contributing

Contributions (documentation or code improvements in particular) are welcome, see contributing!

Acknowledgments

I would like to thank all the contributors, as well as the authors of the dependencies this crate uses.