All of Migrator's features are exposed as Ant tasks (See the contents of migrator.xml). So to start using Migrator import the migrator.xml into your project's main build.xml file such as -

Once you have included migrator.xml you can invoke all the tasks specified in it from the command line.

Creating a New Migration

The lifecycle of a change starts by creating a new change script.Each change script can be tagged with a name based on what it does. Migrator generates an empty script file with the name you specify when you invoke the "new" task. The generated script's name is a combination of the version number prefix and the special tag you specified. A sample invocation of the new task looks like this -

This simple form of invocation will result in the creation of a script called 1_Change.sql. The number "1" stands for the version of the database schema. More on this later. If you want to tag the script differently use -

This invocation will result in the creation of a script called 1_AddUserTable.sql.

Anatomy of a migration script

A migration script used by Migrator mandates the presence of two sections in every script.

The "UP" section is a placeholder for specifying actions that are needed to move the schema forward and the "DOWN" section for specifying the converse of the "UP" action, i.e to revert the change. The "new" task will create an empty script that has these placeholders.

Writing a change script

Within each of the sections of a script you can write a valid SQL statement that can span across multiple lines. Each statement needs to be terminated with a ";" though.

Head Migration - Migrating to the latest version

Once you have written the sql statement the next task is to apply the change to the database. For this you will need to run another ant task called "migrate"

Here is a good occasion for us to understand how Migrator versions your schema. As we have seen already each change is prefixed with a number and this number represents the version of the database the change in it pertains to.

Internally when you apply the first change (i.e version number 1) Migrator actually creates a table called schema_info in your schema and initializes it to 1. Subsequently with every successive change migrator increments the version number stored in schema_info. You can always query it to find out what version your database is on.

Each time "migrate" is called Migrator determines the delta between the current version of your schema and the version of the latest script and runs each of the scripts in the range determined. Thus bringing your schema to the latest version. Such a migration is referred here as a head migration.

Generating SQL Dumps/Patch Scripts

Migrator provides an added facility to extract changes between any two versions of your schema. You could use this a patch and apply it to another schema in an environment where there is no migrator, or just use it as a rolled up sql script that contains all the schema changes.

The patch task can be invoked with two mandatory arguments the lower and higher version numbers. This task generates a file with a prefix like 1_10XXXXXXX.patch.sql under a directory called patches which inturn is nested within the location of your migration scripts. The task's log actually reports the full path of the newly generated script.