Crate diesel_migrations

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

Example

- 20151219180527_create_users
    - up.sql
    - down.sql
- 20160107082941_create_posts
    - up.sql
    - down.sql

-- 20151219180527_create_users/up.sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name VARCHAR NOT NULL,
  hair_color VARCHAR
);

-- 20151219180527_create_users/down.sql
DROP TABLE users;

-- 20160107082941_create_posts/up.sql
CREATE TABLE posts (
  id SERIAL PRIMARY KEY,
  user_id INTEGER NOT NULL,
  title VARCHAR NOT NULL,
  body TEXT
);

-- 20160107082941_create_posts/down.sql
DROP TABLE posts;

Modules

connection

Macros

embed_migrations

This macro will read your migrations at compile time, and embed a module you can use to execute them at runtime without the migration files being present on the file system. 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).

Structs

MigrationName

Enums

MigrationError

Errors that occur while preparing to run migrations

RunMigrationsError

Errors that occur while running migrations

Traits

Migration

Represents a migration that interacts with diesel

MigrationConnection

A connection which can be passed to the migration methods. This exists only to wrap up some constraints which are meant to hold for all connections. This trait will go away at some point in the future. Any Diesel connection should be useable where this trait is required.

Functions

any_pending_migrations

See the module level documentation for information on how migrations should be structured, and where Diesel will look for them by default.

find_migrations_directory

Returns the directory containing migrations. Will look at for $PWD/migrations. If it is not found, it will search the parents of the current directory, until it reaches the root directory. Returns MigrationError::MigrationDirectoryNotFound if no directory is found.

mark_migrations_in_directory

Compares migrations found in migrations_dir to those that have been applied. Returns a list of pathbufs and whether they have been applied.

migration_from

name

revert_latest_migration

Reverts the last migration that was run. Returns the version that was reverted. Returns an Err if no migrations have ever been run.

revert_latest_migration_in_directory

run_migrations

Run all pending migrations in the given list. Apps should likely be calling run_pending_migrations or run_pending_migrations_in_directory instead.

run_pending_migrations

Runs all migrations that have not yet been run. This function will print all progress to stdout. This function will return an Err if some error occurs reading the migrations, or if any migration fails to run. Each migration is run in its own transaction, so some migrations may be committed, even if a later migration fails to run.

search_for_migrations_directory

Searches for the migrations directory relative to the given path. See find_migrations_directory for more details.