Struct sqlx_migrate::Migrator

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

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(())
        })
    })
    .with_checksum(b"CREATE TABLE example ();".as_slice())
    .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, 

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 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, 

pub async fn migrate(&mut self, 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(&mut self) -> Result<MigrationSummary, Error>

Apply all local migrations, if there are any.

Errors

Uses Migrator::migrate internally, errors are propagated.

pub async fn revert(&mut self, 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(&mut self) -> Result<MigrationSummary, Error>

Revert all applied migrations, if any.

Errors

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

pub async fn force_version(
    &mut 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(&mut 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(&mut 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.