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 |

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 embeddedclicompatible 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).

```rust fn up(: migrantlib::ConnConfig) -> Result<(), Box> { print!(" Up!"); Ok(()) }

fn down(: migrantlib::ConnConfig) -> Result<(), Box> { print!(" Down!"); Ok(()) }

config.usemigrations(&[ migrantlib::FileMigration::withtag("create-users-table") .up("migrations/embedded/createuserstable/up.sql")? .down("migrations/embedded/createuserstable/down.sql")? .boxed(), migrantlib::EmbeddedMigration::withtag("create-places-table") .up(includestr!("../migrations/embedded/createplacestable/up.sql")) .down(includestr!("../migrations/embedded/createplacestable/down.sql")) .boxed(), migrantlib::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 migrantclicompatible example for a working sample where migration files and a Migrant.toml config file are available at runtime.

See the embeddedclicompatible 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

License: MIT