Struct Migrator 

pub struct Migrator { /* private fields */ }

Bootstraps, migrates, and verifies versioned SQLite schemas.

A migrator is built from two ordered migration sets: retired SQL migrations followed by active migrations. Retired migrations are pure SQL snapshots of older active migrations whose schema we retain, but whose upgrade path we no longer want to support. Because that old migration path is intentionally unsupported, retired migrations are only applied when creating a new database whose PRAGMA user_version is zero. Existing databases are never allowed to run only part of the retired SQL set; once a database has a non-zero version, it must already be at or beyond the end of the retired migrations.

Active migrations run after the retired SQL set and can be pure SQL or Rust functions. Bootstrap creates a new database and applies all migrations. Migration opens an existing bootstrapped database, verifies that the current schema hash matches the expected hash for its user_version, and then applies only the missing active migrations. Each migration runs in its own transaction and commits only after the resulting schema hash matches the hash computed by the builder.

Construct a migrator with Migrator::builder by pushing retired migrations first and active migrations second, or call Migrator::generate from a build.rs to generate that builder chain from a migration directory. Callers should snapshot Migrator::schema_hashes in tests so accidental schema changes are caught, especially when replacing active migrations with equivalent retired SQL.

Implementations

impl Migrator

pub fn generate(migration_dir: impl AsRef<Path>) -> Result<PathBuf>

Generates Rust source for a migrator from a migration directory.

Call this from a build.rs, then include the generated file in the crate:

// build.rs
fn main() -> Result<(), Box<dyn std::error::Error>> {
    miden_node_db::migration::Migrator::generate("migrations")?;
    Ok(())
}

// src/lib.rs
include!(concat!(env!("OUT_DIR"), "/db_migrator.rs"));

#[cfg(test)]
mod tests {
    use miden_node_db::migration::SchemaHash;

    const EXPECTED_SCHEMA_HASHES: [SchemaHash; 3] = [
        SchemaHash::from_hex(
            "1111111111111111111111111111111111111111111111111111111111111111",
        ),
        SchemaHash::from_hex(
            "2222222222222222222222222222222222222222222222222222222222222222",
        ),
        SchemaHash::from_hex(
            "3333333333333333333333333333333333333333333333333333333333333333",
        ),
    ];

    #[test]
    fn migration_schema_hashes_are_stable() -> anyhow::Result<()> {
        let migrator = super::migrator()?;

        assert_eq!(migrator.schema_hashes(), &EXPECTED_SCHEMA_HASHES);
        Ok(())
    }
}

The expected layout is:

migrations/
  retired/
    001_legacy.sql
  002_initial.sql
  003_backfill.rs
  003_backfill/
    fixture.bin

Retired migrations are loaded from lexicographically sorted .sql files in retired; the migration name is the file stem. Active migrations are loaded from lexicographically sorted direct .sql and .rs files in the migration directory; the migration name is the file stem. Rust migration files must expose a pub fn migrate(...) matching super::CodeMigrationFn. Direct subdirectories other than retired are ignored by the framework so callers can keep migration-specific support files next to a migration file.

The retired directory contains SQL retained for fresh database initialization after the corresponding active migrations no longer need to be supported. Relative migration paths are resolved from the package manifest directory, i.e. the crate root.

impl Migrator

pub fn builder() -> Result<MigratorBuilder>

Creates a migration builder backed by an in-memory SQLite database.

pub fn schema_hashes(&self) -> SchemaHashes<'_>

Returns the schema hashes expected after each migration.

Callers can use these hashes in tests when retiring active migrations into SQL: the replacement SQL should produce the same hash at the same migration index.

pub fn bootstrap(&self, database_filepath: impl AsRef<Path>) -> Result<()>

Creates a new database at database_filepath and applies all migrations.

The database file must not already exist. Every migration runs in its own transaction, updates user_version, and commits only after the resulting schema hash matches the expected hash.

pub fn migrate(&self, database_filepath: impl AsRef<Path>) -> Result<()>

Applies missing migrations to the existing database at database_filepath.

The database file must already exist and must have been bootstrapped. Existing databases must already be past the retired migration range; only missing active migrations are applied. Every migration runs in its own transaction, updates user_version, and commits only after the resulting schema hash matches the expected hash.

pub fn verify_latest_schema( &self, database_filepath: impl AsRef<Path>, ) -> Result<()>

Verifies that the database at database_filepath is already at the latest schema version.

This does not create the database file and does not apply any missing migrations. Callers should use this on normal startup paths which must reject databases that have not been explicitly bootstrapped or migrated.

This checks SQLite’s PRAGMA user_version and verifies that the current schema hash matches the expected hash for that version.

Trait Implementations

impl Debug for Migrator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.