The 'up,down' commands

As discussed above, the migration scripts have both a do and an undo section in them. It’s therefore possible to evolve and devolve a database to simplify development and concurrent evolution of the database across development teams.

The up command runs the do section of all pending migrations in order, one after the other.

The down command runs the undo section of the last applied migration only.

These commands behave this way because you’re most likely to always want the latest revision of the database schema, and if you ever need to roll back, you’ll probably only want to do so for the last few versions – and do so in a controlled manner.

Here’s a more visual example of how the up and down commands work. We’ll use the status command in between to see the effect:

/home/cbegin/testdb$ migrate status
ID             Applied At          Description
==================================================================
20090802210445    ...pending...    create changelog
20090804225207    ...pending...    create author table
20090804225328    ...pending...    create blog table
20090804225333    ...pending...    create post table

/home/cbegin/testdb$ migrate up

/home/cbegin/testdb$ migrate status
ID             Applied At          Description
==================================================================
20090802210445 2009-08-04 22:51:17 create changelog
20090804225207 2009-08-04 22:51:17 create author table
20090804225328 2009-08-04 22:51:17 create blog table
20090804225333 2009-08-04 22:51:17 create post table

/home/cbegin/testdb$ migrate down

/home/cbegin/testdb$ migrate status
ID             Applied At          Description
==================================================================
20090802210445 2009-08-04 22:51:17 create changelog
20090804225207 2009-08-04 22:51:17 create author table
20090804225328 2009-08-04 22:51:17 create blog table
20090804225333    ...pending...    create post table

As mentioned, by default up applies all pending migrations, and down undoes just the most recent one. Both up and down commands can take an integer parameter to override these defaults. The integer specifies how many steps should be executed. For example:

/home/cbegin/testdb$ migrate down 2

/home/cbegin/testdb$ migrate status
ID             Applied At          Description
==================================================================
20090802210445 2009-08-04 22:51:17 create changelog
20090804225207    ...pending...    create author table
20090804225328    ...pending...    create blog table
20090804225333    ...pending...    create post table

There really isn’t much more to the up and down commands than that. They let you navigate the evolution of the database schema forward and backward. As usual, they operate on the repository in the current working directory, or the one specified in the option --path option.