Database Migrations

Overview

Database migrations provide a way to safely and consistently manage schema changes. Quantum's migration system supports creating, applying, reverting, and tracking migrations via CLI and programmatic APIs.

Migration Concepts

  • Migrations are PHP classes that contain up() and down() methods which apply and revert schema changes.
  • Migrations are stored in migration files located in the /migrations directory.
  • A migrations table tracks which migrations have been applied to the database.

Migration Actions

Supported actions include: - create - alter - rename - drop

Each action corresponds to templates used in generated migration files.

Example Create Migration

use Quantum\Database\Factories\TableFactory;
use Quantum\Migration\QtMigration;

class CreateTableUsers extends QtMigration
{
    public function up(?TableFactory $tableFactory): void
    {
        $table = $tableFactory->create('users');
        $table->addColumn('id', 'integer')->primary()->autoIncrement();
        $table->addColumn('uuid', 'char', 36);
        $table->addColumn('firstname', 'varchar', 255);
        $table->addColumn('lastname', 'varchar', 255);
        $table->addColumn('role', 'varchar', 255);
        $table->addColumn('email', 'varchar', 255);
        $table->addColumn('password', 'varchar', 255);
        $table->addColumn('activation_token', 'varchar', 255)->nullable();
        $table->addColumn('remember_token', 'varchar', 255)->nullable();
        $table->addColumn('access_token', 'varchar', 255)->nullable();
        $table->addColumn('refresh_token', 'varchar', 255)->nullable();
        $table->addColumn('reset_token', 'varchar', 255)->nullable();
        $table->addColumn('otp', 'integer')->nullable();
        $table->addColumn('otp_token', 'varchar', 255)->nullable();
        $table->addColumn('otp_expires', 'timestamp')->nullable();
    }

    public function down(?TableFactory $tableFactory): void
    {
        $tableFactory->drop('users');
    }
}

Generating a Migration

You can generate a migration file using the CLI:

php qt migration:generate <action> <table_name>

Example:

php qt migration:generate create users

This creates a migration file with an up/down template for the specified action.

Applying Migrations

Apply pending migrations with:

php qt migration:migrate

To downgrade migrations:

php qt migration:migrate down --step=1

You can increase --step to revert more migrations.

MigrationManager Responsibilities

  • Loads migration files and determines which migrations need applying or rolling back.
  • Checks for the presence of migration tracking table, and creates it if missing.
  • Executes migration classes' up() or down() methods to apply or revert changes.
  • Updates the migrations table with applied and removed migration entries.
  • Supports migration ordering and stepping through rollback.

Best Practices

  • Always use migrations for schema changes to keep environments synced.
  • Review generated migration templates before applying.
  • Use migration rollback during development cautiously.
  • Keep migration files under version control.

After migration basics, continue with: