The 'init' command

The init command initializes a new 'migration path', also called a 'repository' (of migration scripts). Regardless of whether your working with a new database or an existing one, you'll run init to create the workspace in which you'll place everything you need to manage database change. Running this command will create the directory specified by the --path option (which is the current working directory by default). Here's an example of running the init command:

/$ migrate --path=/home/cbegin/testdb init

If I was already in the /home/cbegin/testdb directory, I could simply run:

/home/cbegin/testdb$ migrate init

When the command is completed, the directory will contain the following sub-directories:

Since version 3.2.1, you can change the default timestamp based file prefix to number sequence by specifying --idpattern option. With the following command, for example, the prefix of the generated scripts will be three digit zero-padded number like '001'.

/home/cbegin/testdb$ migrate --idpattern=000 init

Instead of specifying the pattern as a command line argument, you can set it in the configuration file $MIGRATIONS_HOME/migration.properties as follows.

# Example of migration.properties
idpattern=000

./drivers

Place your JDBC driver .jar or .zip files in this directory. Upon running a migration, the drivers will be dynamically loaded.

./environments

In the environments folder you will find .properties files that represent your database instances. By default a development.properties file is created for you to configure your development time database properties. You can also create test.properties and production.properties files. Details about the properties themselves follow later in this document. The environment can be specified when running a migration by using the --env=<environment> option (without the path or ".properties" part).

The default environment is "development". The properties file is self documented, but here it is for reference:

## Base time zone to ensure times are consistent across machines
time_zone=GMT+0:00
## The character set that scripts are encoded with
# script_char_set=UTF-8
## JDBC connection properties.
driver=
url=
username=
password=
# Name of the table that tracks changes to the database
changelog=CHANGELOG
# If set to true, each statement is isolated
# in its own transaction.  Otherwise the entire
# script is executed in one transaction.
auto_commit=false
# This controls how statements are delimited.
# By default statements are delimited by an
# end of line semicolon.  Some databases may
# (e.g. MS SQL Server) may require a full line
# delimiter such as GO.
delimiter=;
full_line_delimiter=false
# This ignores the line delimiters and
# simply sends the entire script at once.
# Use with JDBC drivers that can accept large
# blocks of delimited text at once.
send_full_script=true
# If set to false, warnings from the database
# will interrupt migrations.
ignore_warnings=true
# Custom driver path to avoid copying your drivers
# driver_path=

Since version 3.3.6, it is possible for users to override environment settings via environment variables or system properties. For example, instead of writing the database password in the environment file, you can declare an environment variable MIGRATIONS_PASSWORD.

Database specific information

MySQL
  • send_full_script must be set to false to execute a script with multiple statements.

./scripts

This directory contains your migration SQL files. These are the files that contain your DDL to both upgrade and downgrade your database structure. By default, the directory will contain the script to create the changelog table, plus one empty example migration script. To create a new migration script, use the "new" command. To run all pending migrations, use the "up" command. To undo the last migration applied, use the "down" command etc.