Crate diesel_migrations

source ·
Expand description

Provides functions for maintaining database schema.

A database migration always provides procedures to update the schema, as well as to revert itself. Diesel’s migrations are versioned, and run in order. Diesel also takes care of tracking which migrations have already been run automatically. Your migrations don’t need to be idempotent, as Diesel will ensure no migration is run twice unless it has been reverted.

Migrations should be placed in a /migrations directory at the root of your project (the same directory as Cargo.toml). When any of these functions are run, Diesel will search for the migrations directory in the current directory and its parents, stopping when it finds the directory containing Cargo.toml.

Individual migrations should be a folder containing two files, up.sql and down.sql. up.sql will be used to run the migration, while down.sql will be used for reverting it. The folder itself should have the structure {version}_{migration_name}. It is recommended that you use the timestamp of creation for the version.

Migrations can either be run with the CLI or embedded into the compiled application and executed with code, for example right after establishing a database connection. For more information, consult the embed_migrations! macro.


  • This macro will read your migrations at compile time, and create a constant value containing an embedded list of all your migrations as available at compile time. This is useful if you would like to use Diesel’s migration infrastructure, but want to ship a single executable file (such as for embedded applications). It can also be used to apply migrations to an in memory database (Diesel does this for its own test suite).


  • A migration source that embeds migrations into the final binary
  • A migration source based on a migration directory in the file system
  • A migration harness that writes messages into some output for each applied/reverted migration


  • A migration harness is an entity which applies migration to an existing database