Struct Migrator 

pub struct Migrator { /* private fields */ }

A resolved set of migrations, ready to be run.

Can be constructed statically using migrate!() or at runtime using Migrator::new().

Implementations

impl Migrator

pub async fn new<'s, S>(source: S) -> Result<Migrator, MigrateError>

where S: MigrationSource<'s>,

Creates a new instance with the given source.

Examples

use std::path::Path;

// Read migrations from a local folder: ./migrations
let m = Migrator::new(Path::new("./migrations")).await?;

See MigrationSource for details on structure of the ./migrations directory.

pub fn with_migrations(migrations: Vec<Migration>) -> Migrator

Creates a new instance with the given migrations.

Examples

use sqlx::{ SqlSafeStr, migrate::{Migration, MigrationType::*, Migrator}};

// Define your migrations.
// You can also use include_str!("./xxx.sql") instead of hard-coded SQL statements.
let migrations = vec![
    Migration::new(1, "user".into(), ReversibleUp, "create table users ( ... )".into_sql_str(), false),
    Migration::new(2, "post".into(), ReversibleUp, "create table posts ( ... )".into_sql_str(), false),
    // add more...
 ];
 let m = Migrator::with_migrations(migrations);

pub fn dangerous_set_table_name( &mut self, table_name: impl Into<Cow<'static, str>>, ) -> &Migrator

Override the name of the table used to track executed migrations.

May be schema-qualified and/or contain quotes. Defaults to _sqlx_migrations.

Potentially useful for multi-tenant databases.

Warning: Potential Data Loss or Corruption!

Changing this option for a production database will likely result in data loss or corruption as the migration machinery will no longer be aware of what migrations have been applied and will attempt to re-run them.

You should create the new table as a copy of the existing migrations table (with contents!), and be sure all instances of your application have been migrated to the new table before deleting the old one.

pub fn create_schema( &mut self, schema_name: impl Into<Cow<'static, str>>, ) -> &Migrator

Add a schema name to be created if it does not already exist.

May be used with Self::dangerous_set_table_name() to place the migrations table in a new schema without requiring it to exist first.

Note: Support Depends on Database

SQLite cannot create new schemas without attaching them to a database file, the path of which must be specified separately in an ATTACH DATABASE command.

pub fn set_ignore_missing(&mut self, ignore_missing: bool) -> &mut Migrator

Specify whether applied migrations that are missing from the resolved migrations should be ignored.

pub fn set_locking(&mut self, locking: bool) -> &mut Migrator

Specify whether or not to lock the database during migration. Defaults to true.

Warning

Disabling locking can lead to errors or data loss if multiple clients attempt to apply migrations simultaneously without some sort of mutual exclusion.

This should only be used if the database does not support locking, e.g. CockroachDB which talks the Postgres protocol but does not support advisory locks used by SQLx’s migrations support for Postgres.

pub fn iter(&self) -> Iter<'_, Migration>

Get an iterator over all known migrations.

pub fn version_exists(&self, version: i64) -> bool

Check if a migration version exists.

pub async fn run<'a, A>(&self, migrator: A) -> Result<(), MigrateError>

where A: Acquire<'a>, <<A as Acquire<'a>>::Connection as Deref>::Target: Migrate,

Run any pending migrations against the database; and, validate previously applied migrations against the current migration source to detect accidental changes in previously-applied migrations.

Examples

use sqlx::migrate::Migrator;
use sqlx::sqlite::SqlitePoolOptions;

let m = Migrator::new(std::path::Path::new("./migrations")).await?;
let pool = SqlitePoolOptions::new().connect("sqlite::memory:").await?;
m.run(&pool).await

pub async fn run_to<'a, A>( &self, target: i64, migrator: A, ) -> Result<(), MigrateError>

where A: Acquire<'a>, <<A as Acquire<'a>>::Connection as Deref>::Target: Migrate,

pub async fn skip<'a, A>( &self, migrator: A, target: Option<i64>, ) -> Result<(), MigrateError>

where A: Acquire<'a>, <<A as Acquire<'a>>::Connection as Deref>::Target: Migrate,

Skip any pending migrations until a specific version against the database; Additionally validate previously applied migrations against the current migration source to detect accidental changes in previously-applied migrations.

Skipping entails not executing the SQL of the migrations, but marking them as applied in the [_migrations] table.

Examples

use sqlx::migrate::Migrator;
use sqlx::sqlite::SqlitePoolOptions;

let m = Migrator::new(std::path::Path::new("./migrations")).await?;
let pool = SqlitePoolOptions::new().connect("sqlite::memory:").await?;
m.skip(&pool, Some(17)).await

pub async fn undo<'a, A>( &self, migrator: A, target: i64, ) -> Result<(), MigrateError>

where A: Acquire<'a>, <<A as Acquire<'a>>::Connection as Deref>::Target: Migrate,

Run down migrations against the database until a specific version.

Examples

use sqlx::migrate::Migrator;
use sqlx::sqlite::SqlitePoolOptions;

let m = Migrator::new(std::path::Path::new("./migrations")).await?;
let pool = SqlitePoolOptions::new().connect("sqlite::memory:").await?;
m.undo(&pool, 4).await

Trait Implementations

impl Debug for Migrator

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

Formats the value using the given formatter.