Introduction

The entire Migrations system can be accessed through this one simple command. You can access the built-in help by typing: migrate --help.

Calling the migrate command with no options or invalid options also produces the help message. Here's the output of the help command:

Usage: migrate command [parameter] [--path=<directory>] [--env=<environment>]
               [--template=<path to template>]
--path=<directory>   Path to repository.  Default current working directory.
--env=<environment>  Environment to configure. Default environment is 'development'.
--force              Forces script to continue even if SQL errors or warnings are encountered.
--help               Displays this usage message.
--trace              Shows additional error details (if any).
--template           (Optional) Specify template to be used with ‘new'command
--quiet              Suppresses output.
--color              Colorize output.
Commands:
  init               Creates (if necessary) and initializes a migration path.
  bootstrap          Runs the bootstrap SQL script (see scripts/bootstrap.sql for more).
  new <description>  Creates a new migration with the provided description.
  up                 Run all unapplied migrations.
  down               Undoes the last migration applied to the database.
  version <version>  Migrates the database up or down to the specified version.
pending
status
script <v1> <v2>
Force executes pending migrations out of order (not recommended).
Prints the changelog from the database if the changelog table exists.
Generates a delta migration script from version v1 to v2 (undo if v1 > v2).

We'll go through each of these commands in detail, but first, let's talk about lifecycle.

The MyBatis Migrations Lifecycle

Database change management is difficult at the best of times, so to make the situation better, it’s important to have a good database evolution strategy. That employed by MyBatis Migrations targets a few key goals:

• Consistent – The schema should be predictable on every machine it’s created on.
• Repeatable – The schema can be destroyed and recreated a predictable way.
• Reversible – Changes should be able to be rolled back, or undone.
• Versioned – The version of the schema should be identifiable (via query or tool).
• Auditable – The schema evolution should be auditable and the changes to it logged.
• Automated – The evolution (or devolution) of the schema should be fully automated.
• Serial – The evolution in the database should never branch or evolve conditionally.
• Immutable Changes – No past applied alter or evolution of the database should be modified, instead a new change should be created.
• Concurrently Modifiable – The schema should be safely modifiable by multiple people or teams in a way that encourages teamwork, communication and easy identification of conflicts, without depending on text comparisons (diff) or any particular source control feature (conflicts), but should work very well with source control systems.

Thus, the lifecycle of a schema managed with MyBatis Migrations is as follows:

1. Initialize Repository
2. Bootstrap database schema
3. Create a new migration (or many migrations)
4. Apply migrations

Optional steps include:

• Revert migrations if necessary to resolve conflicts
• Apply pending migrations out of order if it’s safe to do so
• Generate migration scripts to be run “offline” in environments that are beyond your control
• Get the status of the system at any time

The following command discussions will provide more detail about how this lifecycle works.