Tutorials: Migrations

├─ Setting Development Environment
├─ Setting Cache Solution
├─ Writing Migration Scripts
└─ Executing Migrations

Setting Development Environment

Migrations execution will be subject of differences depending on development environment (eg: using db connection settings). It will thus require environment variable ENVIRONMENT to be already set:

on UNIX systems, open console and run:
export ENVIRONMENT={VALUE}
on Windows systems, open command prompt and run:
setx ENVIRONMENT {VALUE}

If above is not set, framework automatically assumes {VALUE} will be local!

Setting Cache Solution

API requires a Lucinda\Migration\Cache implementation for keeping track of migrations that ran already as well as their outcome. Framework Skeleton API comes with:

Lucinda\Project\DAO\NoSQLMigrationCache: binds with NoSQL Data Access API to save progress into a key-value store DB
Lucinda\Project\DAO\SQLMigrationCache: binds with SQL Data Access API to save progress into a SQL DB (eg: MySQL)
Requires "migrations" table created beforehand. Structure @ MySQL:
CREATE TABLE migrations ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, class_name VARCHAR(255) NOT NULL, is_successful BOOLEAN NOT NULL DEFAULT TRUE, date TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY(id), UNIQUE(class_name) ) Engine=INNODB

Lucinda\Project\DAO\SQLMigrationCache is used by default in migrations.php:

define("CACHE_TYPE", "sql");

If you want to switch to the other, you only need to edit migrations.php and change line to:

define("CACHE_TYPE", "nosql");

Writing Migration Scripts

To generate a migration script, open console and run:

php migrations.php generate

This will create a VersionTIMESTAMP class (eg: Version20210205105634) in migrations folder, implementing Lucinda\Migration\Script and coming with two methods:

up: (mandatory) operation(s) to change database (eg: ALTER TABLE ADD columnName)
down: (optional) operation(s) to roll back changes to database (eg: ALTER TABLE DROP COLUMN columnName)

Example implementation:

class Version20210205105634 implements \Hlis\Migration\Script
{
    /**
     * Commits changes
     */
    public function up(): void
    {
        SQL("ALTER TABLE users ADD age TINYINT UNSIGNED NOT NULL DEFAULT 0");
    }
    
    /**
     * Rolls back changes
     */
    public function down(): void
    {
        SQL("ALTER TABLE users DROP COLUMN age");
    }
}

Executing Migrations

migrations.php allows you to execute migrations using multiple strategies through console arguments:

migrate: loops through all scripts in migrations folder and executes up command. Example:
php migrations.php migrate
For more info how it works, check API Documentation!
up CLASS: executes up command to target class. Example:
php migrations.php up Version20210205105634
For more info how it works, check API Documentation!
down CLASS: executes up command to target class. Example:
php migrations.php down Version20210205105634
For more info how it works, check API Documentation!

Depending on Lucinda\Migration\Cache solution chosen, migration progress will be saved to a permanent storage medium that makes sure:

a successful migration won't run again
a unsuccessful migration will be re-ran until it ends with a success

□ ×