Struct Migrator

pub struct Migrator<Db>
where
    Db: Database,
    Db::Connection: Migrations,
{ /* private fields */ }

A Migrator that is capable of managing migrations for a database.

Example

use crate::{Error, Migration, Migrator};
use sqlx::{Executor, Postgres};

async fn migrate() -> Result<(), Error> {
   let mut migrator: Migrator<Postgres> =
        Migrator::connect("postgres://postgres:postgres@localhost:5432/postgres").await?;

    let migration = Migration::<Postgres>::new("initial migration", |tx| {
        Box::pin(async move {
            tx.execute("CREATE TABLE example ();").await?;
            Ok(())
        })
    })
    .reversible(|tx| {
        Box::pin(async move {
            tx.execute("DROP TABLE example;");
            Ok(())
        })
    });

    migrator.add_migrations([migration]);

    // Make sure all migrations are consistent with the database.
    migrator.check_migrations().await?;

    // Migrate
    let summary = migrator.migrate(migrator.local_migrations().len() as _).await?;

    assert_eq!(summary.new_version, Some(1));

    // List all migrations.
    let status = migrator.status().await?;

    // Verify that all of them are applied.
    for migration in status {
        assert!(migration.applied.is_some());
    }

    Ok(())
}

Implementations

impl<Db> Migrator<Db>

where Db: Database, Db::Connection: Migrations, for<'a> &'a mut Db::Connection: Executor<'a>,

pub fn new(conn: Db::Connection) -> Self

Create a new migrator that uses an existing connection.

pub async fn connect(url: &str) -> Result<Self, Error>

Connect to a database given in the URL.

If this method is used, SQLx statement logging is explicitly disabled. To customize the connection, use Migrator::connect_with.

Errors

An error is returned on connection failure.

pub async fn connect_with( options: &<Db::Connection as Connection>::Options, ) -> Result<Self, Error>

Connect to a database with the given connection options.

Errors

An error is returned on connection failure.

pub async fn connect_with_pool(pool: &Pool<Db>) -> Result<Self, Error>

Use a connection from an existing connection pool.

note: A connection will be detached from the pool.

Errors

An error is returned on connection failure.

pub fn set_migrations_table(&mut self, name: impl AsRef<str>)

Set the table name for migration bookkeeping to override the default DEFAULT_MIGRATIONS_TABLE.

The table name is used as-is in queries, DO NOT USE UNTRUSTED STRINGS.

pub fn add_migrations( &mut self, migrations: impl IntoIterator<Item = Migration<Db>>, )

Add migrations to the migrator.

pub fn set_options(&mut self, options: MigratorOptions)

Override the migrator’s options.

pub fn with<T: Send + Sync + 'static>(&mut self, value: T) -> &mut Self

With an extension that is available to the migrations.

pub fn set<T: Send + Sync + 'static>(&mut self, value: T)

Add an extension that is available to the migrations.

pub fn local_migrations(&self) -> &[Migration<Db>]

List all local migrations.

To list all migrations, use Migrator::status.

impl<Db> Migrator<Db>

where Db: Database, Db::Connection: Migrations, for<'a> &'a mut Db::Connection: Executor<'a>,

pub async fn migrate( self, target_version: u64, ) -> Result<MigrationSummary, Error>

Apply all migrations to the given version.

Migration versions start at 1 and migrations are ordered the way they were added to the migrator.

Errors

Whenever a migration fails, and error is returned and no database changes will be made.

pub async fn migrate_all(self) -> Result<MigrationSummary, Error>

Apply all local migrations, if there are any.

Errors

Uses Migrator::migrate internally, errors are propagated.

pub async fn revert( self, target_version: u64, ) -> Result<MigrationSummary, Error>

Revert all migrations after and including the given version.

Any migrations that are “not reversible” and have no revert functions will be ignored.

Errors

Whenever a migration fails, and error is returned and no database changes will be made.

pub async fn revert_all(self) -> Result<MigrationSummary, Error>

Revert all applied migrations, if any.

Errors

Uses Migrator::revert, any errors will be propagated.

pub async fn force_version( self, version: u64, ) -> Result<MigrationSummary, Error>

Forcibly set a given migration version in the database. No migrations will be applied or reverted.

This function should be considered (almost) idempotent, and repeatedly calling it should result in the same state. Some database-specific values can change, such as timestamps.

Errors

The forced migration version must exist locally.

Connection and database errors are returned.

Truncating the migrations table and applying migrations are done in separate transactions. As a consequence in some occasions the migrations table might be cleared and no migrations will be set.

pub async fn verify(self) -> Result<(), Error>

Verify all the migrations.

Errors

The following kind of errors can be returned:

• connection and database errors
• mismatch errors

Mismatch errors can happen if the local migrations’ name or checksum does not match the applied migration’s.

Both name and checksum validation can be turned off via MigratorOptions.

pub async fn status(self) -> Result<Vec<MigrationStatus>, Error>

List all local and applied migrations.

Errors

Errors are returned on connection and database errors. The migrations themselves are not verified.