Struct Migrator 

pub struct Migrator { /* private fields */ }

Runs an ordered list of Migrations, skipping any already applied.

Implementations

impl Migrator

pub fn new() -> Self

An empty migrator.

pub fn add(self, migration: impl Migration) -> Self

Append a migration.

pub fn add_arc(self, migration: Arc<dyn Migration>) -> Self

Append an already-shared migration.

pub fn create_table<E: Entity>(self, name: impl Into<String>) -> Self

Append a “create this entity’s table” step, whose down drops it.

pub fn step( self, name: impl Into<String>, up: impl Fn(Dialect) -> Vec<String> + Send + Sync + 'static, down: impl Fn(Dialect) -> Down + Send + Sync + 'static, ) -> Self

Append a step from up and down rendering closures.

pub fn raw( self, name: impl Into<String>, up: Vec<String>, down: Vec<String>, ) -> Self

Append a step running fixed SQL, with the SQL that undoes it.

pub fn raw_irreversible( self, name: impl Into<String>, up: Vec<String>, reason: impl Into<String>, ) -> Self

Append a step that cannot be undone, with the reason.

pub fn merge(self, other: Migrator) -> Self

Append every step of other, keeping its order.

How a component that owns tables contributes them to the application’s one migrator — DatabaseQueue::migrations() being the case that ships. Without this, a driver’s tables could only be created by running a second migrator, which the migrate command has no way to find.

pub fn names(&self) -> Vec<&str>

Every registered step’s name, in order.

pub fn len(&self) -> usize

How many steps are registered.

pub fn is_empty(&self) -> bool

Whether no steps are registered.

pub fn irreversible(&self, dialect: Dialect) -> Vec<&str>

Which registered steps declare themselves irreversible on dialect.

Worth printing before a deploy: it is exactly the list of things a rollback will refuse to undo.

pub async fn run(&self, db: &Database) -> Result<Vec<String>>

Apply every step that has not run yet, in order. Returns the names of the steps that were applied this time.

They share one batch, which is the unit rollback takes back off.

A step’s statements run before its ledger row is written, so a failure part-way leaves it unrecorded and it is retried next boot. That means a step must be idempotent where it can be — CREATE TABLE IF NOT EXISTS, which is what Rainier ORM’s generated DDL emits.

pub async fn rollback(&self, db: &Database, batches: u32) -> Result<Vec<String>>

Undo the last batches batches, most recent first. Returns the names that were rolled back.

Within a batch, steps are undone in reverse declaration order, because a later step may depend on an earlier one — dropping the table a foreign key points at before dropping the key fails on every backend that enforces them.

Refuses before running anything if any step in range is irreversible, or is in the ledger but no longer in this migrator. A rollback that half-completes leaves the schema in a state no migration describes, which is worse than one that never started.

pub async fn rollback_targets( &self, db: &Database, batches: u32, ) -> Result<Vec<String>>

The names the last batches batches applied, in the order a rollback would undo them.

What migrate:rollback --pretend prints.

pub async fn applied(&self, db: &Database) -> Result<Vec<String>>

Which migrations the ledger says have already run.

pub async fn pending(&self, db: &Database) -> Result<Vec<&str>>

Which registered migrations have not run yet, in order.

Trait Implementations

impl Debug for Migrator

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

Formats the value using the given formatter.

impl Default for Migrator

fn default() -> Self

Returns the “default value” for a type.