Database migration management for Rust programs.
All code in the
src folder is licensed under LGPL v3+.
All code in the
examples folder is available under the MIT license.
To use Trek from crates.io in your project, add it as a dependency in your
[dependencies] trek = "0.3.1"
The heart of Trek is the
MigrationIndex class, which keeps track of all
migrations and manages applying and rolling them back. It's recommended that
you add an implementation of the
Default trait in your program for
MigrationIndex. This allows creating a single source of truth for the list of
database migrations that exist for your program. Unfortunately Rust doesn't
allow implementing traits on structs from other crates, so you'll have to
MigrationIndex wrapper in your own program and implemennt the
Default trait on that. Fortunately the boilerplate code for this is simple
and can be copied from the example program's implementation at
examples/migration_index.rs. Remember after copying to edit the
trait in that file and set it to an empty migration list. When you add new
migrations, you'll add them to the
Default impl in this file.
You'll also need a folder in your source tree to hold the migrations, and a
mod.rs file that exports them. Each migration is its own struct in its own
file in this folder. The example program uses the
to store its migrations.
For ease of use, check out the example program at
examples/example.rs to see
how to hook Trek into your own program so you can use Trek's migration
management through your own program's CLI interface.
Note: Trek expects migration names to be snake-cased like
If you integrated Trek into your program's CLI interface like the example
program does, then adding a new migration is as easy as
cargo run my_program -- trek g migration new_migration_name (if you want to try it out with the
cargo run --example example -- trek g migration new_migration_name). Otherwise you'll have to call
programmatically, passing in the path to your migrations folder and the
migration's snake-cased name. Either way, you'll get a new migration skeleton
in your migrations folder. With the skeleton generated, there are a couple
manual steps to turning into a fully-prepared migration:
- Fill out the new migration skeleton with your SQL. The
upmethod provides the SQL to apply the migration, and the
downmethod provides the SQL to undo it.
- Add a
pub mod <migration file name>line to the
mod.rsfile in your migrations folder. This exports your new migration so it can be used in step 3.
- Update your MigrationIndex's
Defaultimpl to include the new migration. For an example, see the bottom of
The example program provides sample code at
integrating Trek's facilities for applying and rolling back migrations. It's
recommended that you copy this code into your own program so that you can apply
or roll back migrations from your own program's CLI interface.
Trek expects an empty PostgreSQL database that it can test against. To set it up for testing:
- Create a new, empty database named
trek_test: connect to your postgres database and run
create database trek_test;
- Set environment variables giving connection information for the new database: there's a skeleton shell script at
tests/env_vars_example.sh. Copy this file to
env_vars.shto have your database name, user name, and other information filled in. The connection parameters are expected to be in the format used by the rust-postgres crate.
- Load environment variables by running
- Run tests with