Migrations

Migrations are a type of version control for your database. They allow a team to modify the database schema and stay up to date on the current schema state. Migrations are typically paired with the Schema Builder to easily manage your database’s schema.

Note

For the migrations to actually work, you need a configuration file describing your databases. It can be a orator.yml file or a orator.py located where the orator command is executed, or any other yaml or python file (these must then be explicitely specified when executing commands with the --config\-c) which follow the following requirements:

  • yaml files must follow this structure:
databases:
    mysql:
        driver: mysql
        host: localhost
        database: database
        username: root
        password: ''
        prefix: ''
  • python files must follow this structure
DATABASES = {
    'mysql': {
        'driver': 'mysql',
        'host': 'localhost',
        'database': 'database',
        'username': 'root',
        'password': '',
        'prefix': ''
    }
}

Creating Migrations

To create a migration, you can use the migrations:make command on the Orator CLI:

orator migrations:make create_users_table

This will create a migration file that looks like this:

from orator.migrations import Migration


class CreateTableUsers(Migration):

    def up(self):
        """
        Run the migrations.
        """
        pass

    def down(self):
        """
        Revert the migrations.
        """
        pass

By default, the migration will be placed in a migrations folder relative to where the command has been executed, and will contain a timestamp which allows the framework to determine the order of the migrations.

If you want the migrations to be stored in another folder, use the --path/-p option:

orator migrations:make create_users_table -p my/path/to/migrations

The --table and --create options can also be used to indicate the name of the table, and whether the migration will be creating a new table:

orator migrations:make add_votes_to_users_table --table=users

orator migrations:make create_users_table --table=users --create

These commands would respectively create the following migrations:

from orator.migrations import Migration


class AddVotesToUsersTable(Migration):

    def up(self):
        """
        Run the migrations.
        """
        with self.schema.table('users') as table:
            pass

    def down(self):
        """
        Revert the migrations.
        """
        with self.schema.table('users') as table:
            pass
from orator.migrations import Migration


class CreateTableUsers(Migration):

    def up(self):
        """
        Run the migrations.
        """
        with self.schema.create('users') as table:
            table.increments('id')
            table.timestamps()

    def down(self):
        """
        Revert the migrations.
        """
        self.schema.drop('users')

Note

Migration instances have a db attribute which is an instance of the current Connection.

Running Migrations

To run all outstanding migrations, just use the migrations:run command:

orator migrations:run -c databases.py

Note

By default, all migrations are run inside a transaction. If you want queries to be executed directly just set the transactional attribute to False. You then must explicitely declare the transactions:

class CreateTableUsers(Migration):

    transactional = False

    def up(self):
        """
        Run the migrations.
        """
        with self.db.transaction():
            with self.schema.create('users') as table:
                table.increments('id')
                table.timestamps()

    def down(self):
        """
        Revert the migrations.
        """
        with self.db.transaction():
            self.schema.drop('users')

Rolling back migrations

Rollback the last migration operation

orator migrations:rollback

Rollback all migrations

orator migrations:reset

Getting migrations status

To see the status of the migrations, just use the migrations:status command:

orator migrations:status

This would output something like this:

+----------------------------------------------------+------+
| Migration                                          | Ran? |
+----------------------------------------------------+------+
| 2015_05_02_04371430559457_create_users_table       | Yes  |
| 2015_05_04_02361430725012_add_votes_to_users_table | No   |
+----------------------------------------------------+------+