Crate migrant_lib

Embeddable migration management

Also see migrant CLI

migrant_lib allows defining and embedding management of database migrations and (connection) configuration in your compiled application.

Available Features:

Feature	Backend
d-postgres	Enable postgres connectivity
d-sqlite	Enable sqlite connectivity
d-mysql	Enable mysql connectivity
d-all	Enable all backends

Note: No features are enabled by default

Usage

• Migrations can be defined as files, string literals, or functions.
• File migrations can be either read from files at runtime or embedded in your executable at compile time (using include_str!).
• Migration tags must all be unique and may only contain the characters [a-z0-9-]. When running in a cli_compatible mode (see Config::use_cli_compatible_tags), tags must also be prefixed with a timestamp, following: [0-9]{14}_[a-z0-9-]+. See the embedded_cli_compatible example.
• Function migrations must have the signature fn(ConnConfig) -> Result<(), Box<std::error::Error>>. See the embedded_programmable example for a working sample of function migrations.
• When working with embedded and function migrations, the respective database feature must be enabled (d-postgres / d-sqlite / d-mysql).

fn up(_: migrant_lib::ConnConfig) -> Result<(), Box<std::error::Error>> {
    print!(" Up!");
    Ok(())
}

fn down(_: migrant_lib::ConnConfig) -> Result<(), Box<std::error::Error>> {
    print!(" Down!");
    Ok(())
}

config.use_migrations(&[
    migrant_lib::FileMigration::with_tag("create-users-table")
        .up("migrations/embedded/create_users_table/up.sql")?
        .down("migrations/embedded/create_users_table/down.sql")?
        .boxed(),
    migrant_lib::EmbeddedMigration::with_tag("create-places-table")
        .up(include_str!("../migrations/embedded/create_places_table/up.sql"))
        .down(include_str!("../migrations/embedded/create_places_table/down.sql"))
        .boxed(),
    migrant_lib::FnMigration::with_tag("custom")
        .up(up)
        .down(down)
        .boxed(),
])?;

CLI Compatibility

Migration management identical to the migrant CLI tool can also be embedded. This method only supports file-based migrations (so FileMigrations or EmbeddedMigrations using include_str!) and those migration files names must be timestamped with the format [0-9]{14}_[a-z0-9-]+, Properly named files can be generated by migrant_lib::new or the migrant CLI tool. This is required because migration order is implied by file names which must follow a specific format and contain a valid timestamp.

See the migrant_cli_compatible example for a working sample where migration files and a Migrant.toml config file are available at runtime.

See the embedded_cli_compatible example for a working sample where the migrant CLI tool can be used during development, and database configuration and migration file contents are embedded in the application.

Development

See CONTRIBUTING

---

Re-exports

pub use errors::*;

pub use config::Config;

pub use config::Settings;

pub use migration::FileMigration;

pub use migration::EmbeddedMigration;

pub use migration::FnMigration;

Modules

config	Configuration structs
errors	Error types
migration	Embedded / programmable migrations

Structs

ConnConfig	Database connection information
Migrator	Migration applicator

Enums

DbKind	Database type being used
Direction	Represents direction to apply migrations. Up -> up.sql Down -> down.sql

Traits

Migratable

A type that can be used to define database migrations

Functions

edit	Open a migration file containing tag in its name
list	List the currently applied and available migrations under migration_location
new	Create a new migration with the given tag
search_for_settings_file	Search for a Migrant.toml file in the current and parent directories
shell	Open a repl connection to the given Config settings