Mallard

Mallard is a tool to apply schema (or data) migrations to a (currently MySQL) database.

Successfully run migrations are recorded in the database itself, and will not be re-run.

Migrations

Each migration is a directory, with between one and four SQL files in it:

• up.sql contains the queries to execute when running the migration.
• down.sql contains the queries to execute when rolling back the migration.
  • If down.sql does not exist, a warning will be shown when the migration is run.
• pre.sql contains queries to execute before running the migration or rollback.
  • If pre.sql does not exist, the parent directory (the directory containing all migration directories) will also be checked for a file named pre.sql.
• post.sql contains queries to execute after running the migration or rollback.
  • If post.sql does not exist, the parent directory (the directory containing all migration directories) will also be checked for a file named post.sql.

Building

• Install the dependencies (either manually or if on a Debian/derivative by using the install-deps.sh script)

• Build & install the tool:

  ./configure
  make
  sudo make install
  

Dependencies

Mallard is written in shell, and needs a somewhat-recent mysql client installation available. The configure script will try to find the mysql binary on the $PATH at build time.

Additionally, Mallard uses the config module of Koalephant Shell Script Library, which depends on the cfget tool.

Configuration

Mallard will try to load a configuration file: - at the path specified by --config/-c; or - in a file called mallard.conf in the current directory

Any option that can be specified on the command line (except --config/-c) can be specified in a config file, using the 'long' format.

Recording State

Before a migration tries to run, it is recorded in the database in a dedicated table (called mallard-migrations by default), with a 'state' of pending. Once it has run successfully, the table row will be updated to have a 'state' of 'applied'.

Using a 'pending' and 'applied' state (rather than simply inserting once run) allows for a basic type of 'locking', where multiple workers may be trying to apply migrations in a similar timeframe. When a rollback ocurrs, the entry is first changed to pending before the rollback script is executed, and then removed from the table once the rollback completes.

Why is this tool called "Mallard"?

Because a Mallard is a type of Duck that migrates. Quack quack!