griffin

Griffin is a Graph-Oriented Migration Framework for PHP

TL;DR

Griffin is a generic migration framework that uses graph theory to provision anything. It plans execution based on migration dependencies and runs them in the correct order.

use FooBar\Database\Driver;
use Griffin\Migration\Container;
use Griffin\Migration\Migration;
use Griffin\Planner\Planner;
use Griffin\Runner\Runner;

$driver = new Driver(); // Pseudo Database Driver

$orders = (new Migration())
    ->withName('orders')
    ->withAssert(fn() => $driver->table->has('orders'))
    ->withUp(fn() => $driver->table->create('orders'))
    ->withDown(fn() => $driver->table->drop('orders'));

$items = (new Migration())
    ->withName('items')
    ->withDependencies(['orders'])
    ->withAssert(fn() => $driver->table->has('items'))
    ->withUp(fn() => $driver->table->create('items'))
    ->withDown(fn() => $driver->table->drop('items'));

$container = (new Container())
    ->addMigration($orders)
    ->addMigration($items);

$planner = new Planner($container);
$runner  = new Runner($planner);

$runner->up(); // create everything
$runner->down(); // destroy everything

$runner->up('items'); // create orders and items
$runner->down('orders'); // destroy orders and items

// create orders and items
// regardless the order of elements informed
$runner->up('items', 'orders');

// Dry Run
$runner->setDryRun();
$runner->up(); // do nothing
$runner->down(); // do nothing
$runner->unsetDryRun();

You might want to check more examples to learn how to define migrations using Griffin.

Installation

This package uses Composer as default repository. You can install it adding the name of package in require section of composer.json, pointing to the latest stable version.

{
  "require": {
    "griffin/griffin": "^1.0"
  }
}

CLI

This package includes the Griffin framework. If you want a CLI to run your migrations, please check Griffin CLI.

Introduction

Migrations are tools to change system current state, adding (or removing) features based on previous state. Generally, they are used to create database structures from scratch, provisioning tables or columns using a step-by-step approach. There are standalone tools to run migrations, like Phinx. Also, there are other ones embedded into frameworks, like Laravel or Doctrine.

If we inspect them, they use a linear approach, where next state must migrate from current state. Migrations can be rolled back, so if we want to revert some changes, we must rollback from current state to previous state. Each migration knows how to create and destroy itself.

For example, we have three migrations A, B and C created sequentially. If our current state is A and we must migrate to C, we must execute migrations B and C, in that order, respectively. If we want to rollback from C to A, we must execute them backwards, B and A. But if you want to execute migrations A and C, because they are dependent, and ignore B for some reason, you can't. Even, if you want to rollback C and A ignoring B, you are locked.

Bringing to the world of database migrations, you can create migration Orders that creates table into schema. Right after that, other developer creates a migration called Messages without any dependency from Orders. Next, you create a migration named Items with a foreign key to Orders. Everything works fine and you deploy them to stage environment on friday.

./migrations/001_Orders.php
./migrations/002_Messages.php
./migrations/003_Items.php

On monday you find a problem with your migrations and you want to rollback. But you don't want to remove Messages table because other developer is showing the newest features to Product Owner.

And here comes Griffin.

Description

Griffin is a migration framework based on directed graphs, where each migration can be migrated and rolled back independently. Also, you can define dependencies for each migration and Griffin is responsible to plan the execution priority.

Based on provisioning tools like Puppet and Terraform, Griffin can plan execution and run it using graph theory, where each migration works like a vertice and dependencies define directed paths. Griffin searches for circular dependencies on planning and can automatically rollback changes if errors were found.

Griffin is a generic migration framework and it is not database focused. You are free to use Griffin to provisioning what needed, like directory structures, packages, crawlers and even database schemas.

Usage

Each migration must be defined using Griffin\Migration\MigrationInterface. Migrations must return its name with getName method and dependencies with getDependencies. Each migration must check if resource is created using assert method, returning a boolean as result. Also, they are responsible to create the resource using up method and to destroy using down. Griffin uses these methods to plan and run migrations.

namespace FooBar\Database\Migration;

use FooBar\Database\Driver;
use Griffin\Migration\MigrationInterface;

class Items implements MigrationInterface
{
    public function __construct(
        private Driver $driver,
    ) {}

    public function getName(): string
    {
        return self::class;
    }

    /**
     * @return string[]
     */
    public function getDependencies(): array
    {
        return [
            Order::class,
            Product::class,
        ];
    }

    public function assert(): bool
    {
        return $this->driver->table->has('items');
    }

    public function up(): void
    {
        $this->driver->table->create('items');
    }

    public function down(): void
    {
        $this->driver->table->drop('items');
    }
}

You can create objects from class Griffin\Migration\Migration, that implements Griffin\Migration\MigrationInterface and behaviors can be defined using immutable methods.

use FooBar\Database\Driver;
use Griffin\Migration\Migration;

$driver = new Driver();

$migration = (new Migration())
    ->withName('items')
    ->withDependencies(['orders', 'products'])
    ->withAssert(fn() => $driver->table->has('items'))
    ->withUp(fn() => $driver->table->create('items'))
    ->withDown(fn() => $driver->table->drop('items'));

Planning

Griffin plans your migrations execution before running them using Griffin\Planner\Planner. Every migration must be added to Griffin\Migration\Container instances and attached to planner on construction.

use FooBar\Database\Migration;
use Griffin\Migration\Exception as MigrationException;
use Griffin\Planner\Exception as PlannerException;
use Griffin\Planner\Planner;

$planner = new Planner();

$planner->getContainer()
    ->addMigration(new Migration\Orders())
    ->addMigration(new Migration\Items())
    ->addMigration(new Migration\Products());

/** @var Griffin\Migration\Container $migrations **/

try {
    // plan up execution for every migration
    $migrations = $planner->up();
    // plan up execution for Orders and Items
    $migrations = $planner->up(Migration\Items::class)
    // plan down execution
    $migrations = $planner->down();
} catch (PlannerException $e) {
    // PlannerException::DEPENDENCY_CIRCULAR (Circular Dependency Found)
    // PlannerException::DEPENDENCY_INVALID (Invalid Dependency Data Type)
} catch (MigrationException $e) {
    // MigrationException::NAME_UNKNOWN (Unknown Migration Name)
    // MigrationException::NAME_DUPLICATED (Duplicated Migration Name)
    // MigrationException::CALLABLE_UNKNOWN (Unknown Callable Function)
}

You can add migrations to container in any order, because dependencies are checked on planning stage. Migration names are unique and must not be duplicated. Using objects from Griffin\Migration\Migration immutable class can throw errors if callables were not defined.

This stage also searches for circular dependencies, where A depends of B and B depends of A. This type of requirement is not allowed and will rise an exception describing the problem.

Running

After planning, Griffin runs migrations using Griffin\Runner\Runner class. Internally, Griffin plans migrations execution first and after that it will execute running on second stage.

use FooBar\Database\Migration;
use Griffin\Migration\Exception as MigrationException;
use Griffin\Planner\Exception as PlannerException;
use Griffin\Runner\Exception as RunnerException;
use Griffin\Runner\Runner;

$runner = new Runner();

$runner->getPlanner()->getContainer()
    ->addMigration(new Migration\Orders())
    ->addMigration(new Migration\Items())
    ->addMigration(new Migration\Products());

try {
    // run up for everything
    $runner->up();
    // run up for Orders and Items
    $runner->up(Migration\Items::class)
    // run complete down
    $runner->down();
} catch (RunnerException $e) {
    // RunnerException::ROLLBACK_CIRCULAR (Circular Rollback Found)
} catch (PlannerException $e) {
    // PlannerException::DEPENDENCY_CIRCULAR (Circular Dependency Found)
    // PlannerException::DEPENDENCY_INVALID (Invalid Dependency Data Type)
} catch (MigrationException $e) {
    // MigrationException::NAME_UNKNOWN (Unknown Migration Name)
    // MigrationException::NAME_DUPLICATED (Duplicated Migration Name)
    // MigrationException::CALLABLE_UNKNOWN (Unknown Callable Function)
}

For every planned migration Griffin\Runner\Runner will execute migration up method if assert returns false. During a migration execution, errors can be raised and Griffin will try to automatically rollback executed migrations. If during rollback from this migration Griffin finds another error, an exeception will be throw.

If you want to rollback migrations manually, Griffin will use migration assert method to check if resource was created and if this method returns true, migration method down will be called. As before, if Griffin finds an error it will try to recreate resources.

Event Dispatcher

Lastly, Griffin use PSR-14 Event Dispatcher to trigger events after and before migrations up and down. You can use it to create a logger, as example, using league/event package or any PSR-14 implementation.

use FooBar\Database\Migration;
use Griffin\Event;
use Griffin\Migration\Container;
use Griffin\Planner\Planner;
use Griffin\Runner\Runner;
use League\Event\EventDispatcher;

$container = new Container();
$planner   = new Planner($container);
$runner    = new Runner($planner);

$logger = fn($event)
    => printf("%s::%s\n", get_class($event), get_class($event->getMigration()));

$dispatcher = new EventDispatcher(); // PSR-14

$dispatcher->subscribeTo(Event\Migration\UpBefore::class, $logger);
$dispatcher->subscribeTo(Event\Migration\UpAfter::class, $logger);

$dispatcher->subscribeTo(Event\Migration\DownBefore::class, $logger);
$dispatcher->subscribeTo(Event\Migration\DownAfter::class, $logger);

$runner
    ->setEventDispatcher($dispatcher)
    ->addMigration(new Migration\Orders());

$runner->up();
$runner->down();

// Griffin\Event\Migration\UpBefore::Database\Migration\Table\Item
// Griffin\Event\Migration\UpAfter::Database\Migration\Table\Item
// Griffin\Event\Migration\DownBefore::Database\Migration\Table\Item
// Griffin\Event\Migration\DownAfter::Database\Migration\Table\Item

Development

You can use Docker Compose to build an image and run a container to develop and test this package.

docker-compose build
docker-compose run --rm php composer install
docker-compose run --rm php composer test

References

• Wikipedia: Graph Theory
• Wikipedia: Path on Graph Theory
• Wikipedia: Schema Migration

License

This package is opensource and available under MIT license described in LICENSE.

Icons made by Freepik from Flaticon.