#barrel #refinery #database-migrations #core #database-tools #sql-migration #sql #tiberius

refinery-core

This crate should not be used directly, it is internaly related to Refinery

13 unstable releases (5 breaking)

0.8.4 Jan 9, 2022
0.8.1 Dec 31, 2021
0.7.0 Oct 16, 2021
0.6.0 Jul 10, 2021
0.3.1 May 24, 2020

#3 in #database-migrations

Download history 2261/week @ 2021-10-07 2005/week @ 2021-10-14 1890/week @ 2021-10-21 2130/week @ 2021-10-28 1904/week @ 2021-11-04 2131/week @ 2021-11-11 2367/week @ 2021-11-18 1676/week @ 2021-11-25 1797/week @ 2021-12-02 2383/week @ 2021-12-09 1735/week @ 2021-12-16 614/week @ 2021-12-23 1338/week @ 2021-12-30 2277/week @ 2022-01-06 2135/week @ 2022-01-13 2199/week @ 2022-01-20

8,050 downloads per month
Used in 15 crates (3 directly)

MIT/Apache

89KB
2K SLoC

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, rusqlite and tiberius are supported.
If you are using a driver that is not yet supported, namely SQLx you can run migrations providing a Config instead of the connection type, as Config impl's Migrate. You will still need to provide the postgres/mysql/rusqlite/tiberius driver as a feature for Runner::run and tokio-postgres/mysql_async for Runner::run_async.
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

  • Add refinery to your Cargo.toml dependencies with the selected driver as feature eg: refinery = { version = "0.3", features = ["rusqlite"]}
  • Migrations can be defined in .sql files or Rust modules that must have a function called migration that returns a String.
  • Migrations can be strictly versioned by prefixing the file with V or not strictly versioned by prefixing the file with U.
  • Migrations, both .sql files and Rust modules must be named in the format [U|V]{1}__{2}.sql or [U|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 embed_migrations macro, or via refinery_cli.

Example

use rusqlite::Connection;

mod embedded {
    use refinery::embed_migrations;
    embed_migrations!("./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.

Unversioned VS Versioned migrations

Depending on how your project / team has been structured will define whether you want to use Versioned migrations V{1}__{2}.[sql|rs] or Unversioned migrations U{1}__{2}.[sql|rs]. If all migrations are created synchronously and are deployed synchronously you won't run into any problems using Versioned migrations. This is because you can be sure the next migration being run is always going to have a version number greater than the previous.

With Unversioned migrations there is more flexibility in the order that the migrations can be created and deployed. If developer 1 creates a PR with a migration today U11__update_cars_table.sql, but it is reviewed for a week. Meanwhile, developer 2 creates a PR with migration U12__create_model_tags.sql that is much simpler and gets merged and deployed immediately. This would stop developer 1's migration from ever running if you were using Versioned migrations because the next migration would need to be > 12.

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

MSRV

refinery aims to support stable Rust, the previous Rust version, and nightly.

Async

Starting with version 0.2 refinery supports tokio-postgres, mysql_async and Tiberius For Rusqlite, the best way to run migrations in an async context is to run them inside tokio's spawn_blocking for example.

Contributing

🎈 Thanks for your help to improve 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.

Dependencies

~4–12MB
~273K SLoC