Migrations

Migrations are an useful feature to ease deployment and changes in your database schema without having to use a DBMS and that allows you to keep control of the said changes made to the application, for example you can apply them incrementally and then rollback if there's a breaking change.

To create a migration class run the command:

php aurora create:migration AddUserTable

The command described above will create a file named AddUserTable.php in your app/Database/Migrations directory with the following structure:

<?php

declare(strict_types = 1);

namespace App\Database\Migrations;

use Aurora\Database\Migrations\MigrationInterface;
use Aurora\Database\Schema\Schema;

class MyMigration implements MigrationInterface {

    /**
     * Migration up
     * @return bool
     */
    public function up(): bool {
        $schema = resolve(Schema::class);
        # Add your migration up logic here
        return true;
    }

    /**
     * Migration down
     * @return bool
     */
    public function down(): bool {
        $schema = resolve(Schema::class);
        # Add your migration down logic here
        return true;
    }
}

A Migration has two methods: up and down, where up is to be invoked when the migration is applied and down when it is rolled back; that is, you do with up and undo with down.

As a good practice you should provide the logic in both methods where applicable to ensure that every change can be rolled back.

Now, in our example we will be adding a new table, so in resume our logic in each method should:

• Create the user table in up
• Drop the user table in down

Let's get at it:

public function up(): bool {
    $schema = resolve(Schema::class);
    if (! $schema->hasTable('user') ) {
        $schema->create('user', function($table) {
            $table->bigInteger('id', 'integer')->autoIncrement();
            $table->string('uid', 180);
            $table->string('login', 100);
            $table->string('email', 180);
            $table->string('nicename', 100);
            $table->string('password', 255);
            $table->string('status', 25);
            $table->string('type', 25);
            $table->dateTime('created');
            $table->dateTime('modified');
            $table->index('key_uid', 'uid');
            $table->index('key_login', 'login');
            $table->index('key_email', 'email');
            $table->index('key_status', 'status');
            $table->index('key_type', 'type');
            $table->primary('pk_id', 'id');
        });
    }
    return true;
}

In this case we're using the Schema class to perform the table operations, in the code above we just added a new table with a few fields and keys using the create method.

public function down(): bool {
    $schema = resolve(Schema::class);
    $schema->dropIfExists('user');
    return true;
}

The same goes for the down method, just destroy the table.

Running migrations

Once you've created your migration classes you can run them to change the schema of the database.

To be able to use migrations on a given project you must setup the migrations support first by using the following command:

php aurora migrate:setup

That will create a migration table to keep track of the applied migrations.

Now you must run the migrate command:

php aurora migrate

It will apply all the pending migrations in order.

Rolling back migrations

To rollback the changes you may use the migrate:rollback command:

php aurora migrate:rollback

Note that it will rollback the last migration, however you may specify how many steps you wanna rollback with the --steps options:

# Rollback the last 2 applied migrations
php aurora migrate:rollback --steps=2

Also you may undo all the migrations by specifying -1 as the number of steps:

# Rollback all the applied migrations
php aurora migrate:rollback --steps=0

Resetting the database

Another way of resetting the database to its initial state is by running the migrate:reset command:

php aurora migrate:reset

Rebuilding the database

Also if you want to reset the database and then apply all the migrations again you can do it with the migrate:rebuild command:

php aurora migrate:rebuild

This command in particular can also run the seeding if the --seed option is specified:

# Rollback all the applied migrations
php aurora migrate:rebuild --seed

View migration status

Finally, if you want to check the current state of the migrations you can use the migrate:status command:

# Rollback all the applied migrations
php aurora migrate:status

It will show the applied and pending migrations.

Next up, Seeding.