Struct sqlx_migrate::Migrator
source · [−]pub struct Migrator<DB>where
DB: Database,
DB::Connection: Migrations,{ /* private fields */ }
Expand description
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
sourceimpl<DB> Migrator<DB>where
DB: Database,
DB::Connection: Migrations,
impl<DB> Migrator<DB>where
DB: Database,
DB::Connection: Migrations,
sourcepub fn new(conn: DB::Connection) -> Self
pub fn new(conn: DB::Connection) -> Self
Create a new migrator that uses an existing connection.
sourcepub async fn connect(url: &str) -> Result<Self, Error>
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.
sourcepub async fn connect_with(
options: &<DB::Connection as Connection>::Options
) -> Result<Self, Error>
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.
sourcepub async fn connect_with_pool(pool: &Pool<DB>) -> Result<Self, Error>
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.
sourcepub fn set_migrations_table(&mut self, name: impl AsRef<str>)
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.
sourcepub fn add_migrations(
&mut self,
migrations: impl IntoIterator<Item = Migration<DB>>
)
pub fn add_migrations(
&mut self,
migrations: impl IntoIterator<Item = Migration<DB>>
)
Add migrations to the migrator.
sourcepub fn set_options(&mut self, options: MigratorOptions)
pub fn set_options(&mut self, options: MigratorOptions)
Override the migrator’s options.
sourcepub fn with<T: Send + Sync + 'static>(self, value: T) -> Self
pub fn with<T: Send + Sync + 'static>(self, value: T) -> Self
With an extension that is available to the migrations.
sourcepub fn set<T: Send + Sync + 'static>(&mut self, value: T)
pub fn set<T: Send + Sync + 'static>(&mut self, value: T)
Add an extension that is available to the migrations.
sourcepub fn local_migrations(&self) -> &[Migration<DB>]
pub fn local_migrations(&self) -> &[Migration<DB>]
List all local migrations.
To list all migrations, use Migrator::status
.
sourceimpl<DB> Migrator<DB>where
DB: Database,
DB::Connection: Migrations,
impl<DB> Migrator<DB>where
DB: Database,
DB::Connection: Migrations,
sourcepub async fn migrate(
&mut self,
target_version: u64
) -> Result<MigrationSummary, Error>
pub async fn migrate(
&mut 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.
sourcepub async fn migrate_all(&mut self) -> Result<MigrationSummary, Error>
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.
sourcepub async fn revert(
&mut self,
target_version: u64
) -> Result<MigrationSummary, Error>
pub async fn revert(
&mut 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.
sourcepub async fn revert_all(&mut self) -> Result<MigrationSummary, Error>
pub async fn revert_all(&mut self) -> Result<MigrationSummary, Error>
sourcepub async fn force_version(
&mut self,
version: u64
) -> Result<MigrationSummary, Error>
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.
sourcepub async fn verify(&mut self) -> Result<(), Error>
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
.