Struct sqlx_migrate::Migrator [−][src]
pub struct Migrator<DB> where
DB: Database,
DB::Connection: Migrations, { /* fields omitted */ }
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(())
})
})
.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
Create a new migrator that uses an existing connection.
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>
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.
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.
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.
Add migrations to the migrator.
Override the migrator’s options.
List all local migrations.
To list all migrations, use Migrator::status
.
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.
Apply all local migrations, if there are any.
Errors
Uses Migrator::migrate
internally, errors are propagated.
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.
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.
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
.
Auto Trait Implementations
impl<DB> !RefUnwindSafe for Migrator<DB>
impl<DB> !UnwindSafe for Migrator<DB>
Blanket Implementations
Mutably borrows from an owned value. Read more
pub fn vzip(self) -> V
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more