Expand description

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.

Structs

One migration

Set of migrations

Enums

Enum listing possible errors.

Errors related to schema versions

Schema version, in the context of Migrations

Errors related to schema versions

Type Definitions

A typedef of the result returned by many methods.