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.

This workflow is for relational databases only.

If your project is still using the starter default sleekdb adapter, migration commands are not the active schema-management path yet.

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\Migration;

class CreateTableUsers extends Migration
{
    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.

These commands apply only when the active database driver is:

  • mysql
  • pgsql
  • sqlite

They do not run against sleekdb.

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: