Skip to content
Powerful SQL migration toolkit for Rust.
Rust
Branch: master
Clone or download
jxs Merge pull request #38 from tmcw/patch-1
Typo and list style tweaks
Latest commit 7915d67 Jan 9, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci fix typo in dir names embeded -> embedded Jan 1, 2020
assets Adding something to look it Jan 23, 2018
examples
refinery update changelog, release 0.2 Jan 3, 2020
refinery_cli update changelog, release 0.2 Jan 3, 2020
refinery_macros update changelog, release 0.2 Jan 3, 2020
refinery_migrations update changelog, release 0.2 Jan 3, 2020
.gitignore add migrate function for .sql files migrations Jul 22, 2019
CHANGELOG.md update changelog, release 0.2 Jan 3, 2020
Cargo.toml add initial migration traits and macros May 30, 2019
LICENSE Initial commit Jan 11, 2018
README.md Typo and list style tweaks Jan 8, 2020
example_config.toml - simplify traits, use only Transaction and Query traits, Dec 17, 2019

README.md

refinery Logo

Powerful SQL migration toolkit for Rust.

Crates.io docs.rs MIT licensed Build Status

refinery makes running migrations for different databases as easy as possible. It works by running your migrations on a provided database connection, either by embedding them on your Rust code, or via refinery_cli. Currently postgres, tokio-postgres , mysql, mysql_async and rusqlite are supported. refinery works best with Barrel but you can also have your migrations in .sql files or use any other Rust crate for schema generation.

Usage

  • Migrations can be defined in .sql files or Rust modules that must have a function called migration that returns a String.
  • Migrations, both .sql files and Rust modules must be named in the format V{1}__{2}.sql or V{1}__{2}.rs, where {1} represents the migration version and {2} the name.
  • Migrations can be run either by embedding them in your Rust code with embedded_migrations and include_migration_mods macros, or via refinery_cli.

Example

use ttrusqlite::Connection;

mod embedded {
    use refinery::embed_migrations;
    embed_migrations!("refinery/tests/sql_migrations");
}

fn main() {
    let mut conn = Connection::open_in_memory().unwrap();
    embedded::migrations::runner().run(&mut conn).unwrap();
}

For more examples, refer to the examples.

Implementation details

refinery works by creating a table that keeps all the applied migrations' versions and their metadata. When you run the migrations Runner, refinery compares the applied migrations with the the ones to be applied, checking for divergent and missing and executing unapplied migrations.
By default, refinery runs each migration in a single transaction. Alternatively, you can also configure refinery to wrap the entire execution of all migrations in a single transaction by setting set_grouped to true.

Rollback

refinery's design is based on flyway and so, shares its perspective on undo/rollback migrations. To undo/rollback a migration, you have to generate a new one and write specifically what you want to undo.

Compatibility

refinery aims to support stable Rust, the previous Rust version, and nightly. To build Refinery with Rust 1.39 you have to select feature postgres-previous instead of postgres so that refinery builds with postgres version 0.15 instead of version 0.17

Async

Starting with version 0.2 refinery supports tokio-postgres and mysql_async. To migrate async you have to call Runner's run_async. There are plans to support Tiberius when futures 0.3 support stabilizes. For Rusqlite, the best way to run migrations in an async context is to run them inside tokio's block_in_place for example.

Contributing

🎈 Thanks for your help improving the project! No contribution is too small and all contributions are valued, feel free to open Issues and submit Pull Requests

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in refinery by you, shall be licensed as MIT, without any additional terms or conditions.

You can’t perform that action at this time.