Crate migrant_lib[][src]

Build Status crates.io:migrant_lib docs

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:

FeatureBackend
d-postgresEnable postgres connectivity
d-sqliteEnable sqlite connectivity
d-mysqlEnable mysql connectivity
d-allEnable all backends

Notes:

  • No features are enabled by default
  • As of 0.20.0 the d-sqlite feature does not use rusqlites bundled feature. If you would like sqlite to be bundled with your application, you will have to include rusqlite and enable the bundled feature in your project.

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<dyn 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<dyn std::error::Error>> {
    print!(" Up!");
    Ok(())
}

fn down(_: migrant_lib::ConnConfig) -> Result<(), Box<dyn 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 crate::config::Config;
pub use crate::config::Settings;
pub use crate::errors::*;
pub use crate::migration::EmbeddedMigration;
pub use crate::migration::FileMigration;
pub use crate::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