Database Migrations

Relevant source files

The following files were used as context for generating this wiki page:

• source/dbmgmt/migration.rst
• source/cli/database_commands.rst
• source/libraries/migrations.rst
• source/database/configuration.rst
• source/installation/troubleshooting.rst
• README.md

Database migrations provide a version-controlled system for managing your application's database schema. Instead of writing SQL statements manually, migrations allow you to describe database changes in PHP classes. This approach simplifies schema modifications, makes them repeatable across different development environments, and facilitates collaboration within a team by keeping the database structure synchronized with the codebase.

Migrations are typically used in conjunction with the Database Forge class to programmatically create, modify, and delete tables and columns. The entire migration system can be enabled or disabled via a configuration file, and all migration activity is tracked in a dedicated database table.
Sources: source/dbmgmt/migration.rst:3-11

Migration Workflow

The process of creating and applying a database migration follows a straightforward command-line-driven workflow. A developer first generates a new migration file, defines the schema changes in PHP, and then runs a command to apply those changes to the database.

The following diagram illustrates the typical migration lifecycle.
Sources: source/dbmgmt/migration.rst:112-114, source/cli/database_commands.rst:11-13

Creating a Migration

A new migration file is created using the migrate:create Spark command. This command generates a skeleton migration class in the app/Database/Migrations directory with a timestamp-based filename to control the execution order.
Sources: source/dbmgmt/migration.rst:26-30, source/cli/database_commands.rst:11-13

Command:

php spark migrate:create <class_name>

Sources: source/cli/database_commands.rst:13

This creates a file like YYYY-MM-DD-HHIISS_ClassName.php. The generated class contains two primary methods: up() and down().

• up(): This method is executed when the migration is run. It should contain the code to create new tables, add columns, or perform any other schema modifications.
• down(): This method is executed when a migration is rolled back. It must reverse the changes made by the up() method to restore the previous database state.

Sources: source/dbmgmt/migration.rst:43-50

An example of a newly created migration file for adding a blog table:

<?php namespace App\Database\Migrations;

use CodeIgniter\Database\Migration;

class AddBlog extends Migration
{
    public function up()
    {
        $this->forge->addField([
            'blog_id'          => [
                'type'           => 'INT',
                'constraint'     => 5,
                'unsigned'       => true,
                'auto_increment' => true,
            ],
            'blog_title'       => [
                'type'           => 'VARCHAR',
                'constraint'     => '100',
            ],
            'blog_description' => [
                'type'           => 'TEXT',
                'null'           => true,
            ],
        ]);
        $this->forge->addKey('blog_id', true);
        $this->forge->createTable('blog');
    }

    public function down()
    {
        $this->forge->dropTable('blog');
    }
}

Sources: source/dbmgmt/migration.rst:52-87

Running Migrations

Migrations are managed through a set of Spark commands. These commands allow you to apply, revert, and check the status of your database migrations.
Sources: source/cli/database_commands.rst:11-13

The following sequence diagram shows the process when the php spark migrate command is executed.

Command-Line Tools

The following table summarizes the available migration commands.

Command	Description	Options
migrate	Locates and runs all migrations that have not been run.	-g (group), -n (namespace), --all (all namespaces)
migrate:rollback	Reverts the last migration batch.	-g (group), -b (batch number)
migrate:refresh	Rolls back all migrations and then runs them all again. Useful for resetting the database.	-g (group), -f (force)
migrate:status	Displays a list of all migrations and the date and time they were run.	-g (group)
migrate:create	Creates a new skeleton migration file.	-n (namespace)

Sources: source/cli/database_commands.rst:11-73

Configuration

Migration behavior is configured in the app/Config/Migrations.php file. This allows you to enable or disable migrations and customize how they operate.
Sources: source/dbmgmt/migration.rst:14-16

Property	Type	Default Value	Description
enabled	boolean	true	Enables or disables the migration feature entirely.
table	string	migrations	The name of the database table used to store migration history.
timestampFormat	string	Y-m-d-H-i-s	The date format used in the filenames of new migrations.

Sources: source/dbmgmt/migration.rst:18-24

Example configuration in app/Config/Migrations.php:

class Migrations extends BaseConfig
{
    public bool $enabled = true;
    public string $table = 'migrations';
    public string $timestampFormat = 'Y-m-d-His_';
}

Sources: source/dbmgmt/migration.rst:18-24

The MigrationRunner Class

The core logic for handling migrations is encapsulated in the CodeIgniter\Database\MigrationRunner class. While most interaction is done via Spark commands, you can instantiate and use this class directly for more advanced programmatic control over migrations.
Sources: source/libraries/migrations.rst:13-15

This class is responsible for finding migration files, checking their status against the database history table, and executing the up() or down() methods.

The following diagram shows the main components of the MigrationRunner class.

Namespaced Migrations

CodeIgniter's migrations can discover and run migrations from any defined namespace. This is particularly useful for modular applications or when using third-party modules that ship with their own migrations. To enable this, the discover property in app/Config/Autoload.php must be enabled for the relevant PSR-4 namespaces.
Sources: source/dbmgmt/migration.rst:89-98

When running migrations, you can target a specific namespace or all namespaces:

• --all: The --all option runs migrations for all found namespaces.
• -n <namespace>: The -n option targets a single namespace. For example, php spark migrate -n App would only run migrations for the main application namespace.

Sources: source/cli/database_commands.rst:22-24

Troubleshooting

A common issue encountered is the "Cannot find the specified migration file" error. This typically occurs when the filename and the class name inside the file do not match according to PSR-4 autoloading rules. Ensure the class name is the CamelCase version of the filename segment that follows the timestamp.

For example, for a file named 2022-01-01-120000_create_users_table.php, the class name must be CreateUsersTable.
Sources: source/installation/troubleshooting.rst:104-110