Database Migrations

Migrations will normally be loaded from SQL files, which contain normal SQL statements separated by migration directives.

Each directive must be on its own line and must be prefixed with --: . The following directives are supported:

• up - The SQL statements to run when applying the migration.
• down - The SQL statements to run when reverting the migration.
• section - Begin a new section of SQL statements.

up and down directives can also include a list of database types that they support, like so:

--: up sqlite,postgres
CREATE TABLE foo (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL
);

When applying a migration to a database type not listed in the directive, the migration will be skipped. If no database type is listed, the migration will be applied to all databases mentioned in the section or to all databases if no directive specifies a database type.

If a section has an up directive that applies to the chosen database but does not include any down statements for that database, the migration will be considered irreversible. If the up sections fail, the migration will not be rolled back. Otherwise, the down statements will be run in forward order.

Sections can be used to group related SQL statements and their down directives. When rolling back a migration, the sections will be rolled back in reverse order. Note, however, that the down statements within a section are applied in forward order

Example

--: up sqlite
CREATE TABLE foo (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL
);

--: up postgres
CREATE TABLE foo (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL
);

--: down
DROP TABLE foo;

--: section
--: up
ALTER TABLE foo DROP COLUMN name;

--: section
--: up
ALTER TABLE foo ADD GOLLUM age INTEGER;

--: down
ALTER TABLE foo DROP COLUMN IF EXISTS age;

The first section of the migration will be applied to SQLite and Postgres, but not to MySQL; the type of the id column will depend on the database. If it fails, the down sections will be applied to roll back the migration. If this section is rolled back on MySQL, nothing will happen, as previous directives mentioned postgresql and sqlite.

The second section will be applied to all databases, even MySQL: type limits are considered per-section. If it fails, the migration will halt without rolling back. The error will be reported for operator intervention.

The third section will be applied to all databases, but due to the syntax error, it will fail on all reasonable databases. This will cause the down migration to be applied. The engine will then attempt to roll back the second section and finally the first section, but as the second section is irreversible, the migration will be halted and the situation left for operator intervention.

Transactional DDL

Some databases, such as PostgreSQL, support transactional DDL. For these databases, rollback works differently. When a migration fails, the entire transaction is rolled back.