kinetis / migrations

v1.2.1 2026-09-13 11:01 UTC

Requires

• php: ^8.4
• kinetis/framework: ^1.8.1
• kinetis/persistence: ^1.2.2

Requires (Dev)

• infection/infection: ^0.35.0
• phpstan/phpstan: ^2.2.8
• phpunit/phpunit: ^13.3.3
• vimeo/psalm: ^6.17

MIT

• Alon Noy

Published on Packagist.org on 2026-09-13 11:14 UTC

README

kinetis/migrations
A thin database migration runner for Kinetis

Part of Kinetis, a non-blocking PHP framework for API-first applications, developed in the kinetis-dev/kinetis monorepo.

Raw SQL up()/down() migrations, tracked in a kinetis_migrations table, run through migrate* commands registered on vendor/bin/kinetis. No fluent DDL builder, no schema-diffing — the same "thin, not an ORM" shape as kinetis/query-builder.

// migrations/20260810143000_create_orders_table.php
use Kinetis\Persistence\Contract\MysqlLink;
use Kinetis\Persistence\Contract\PostgresLink;
use Kinetis\Migrations\Migration;

return new class implements Migration
{
    public function up(MysqlLink|PostgresLink $db): void
    {
        $db->execute(<<<'SQL'
            CREATE TABLE orders (
                id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
                customer_id BIGINT UNSIGNED NOT NULL,
                status VARCHAR(20) NOT NULL DEFAULT 'pending',
                created_at DATETIME NOT NULL
            )
            SQL);
    }

    public function down(MysqlLink|PostgresLink $db): void
    {
        $db->execute('DROP TABLE orders');
    }
};

vendor/bin/kinetis migrate                       # runs every pending migration
vendor/bin/kinetis migrate:rollback              # rolls back the migration applied most recently
vendor/bin/kinetis migrate:status                # lists applied/pending migrations
vendor/bin/kinetis migrate:make "create orders"  # scaffolds a migration file

The ledger holds one row per applied migration: its name, the SHA-256 of the file that ran, and the order this database applied it in. Every command verifies that against the migrations/ directory first — an applied migration whose file is gone, or whose contents no longer hash to what was recorded, throws Exception\MigrationIntegrityException before any up(), down() or ledger write, and restoring the deployed file is what clears it.

Provides

Installing this package is what opts it in — it registers the following automatically, through the extra.kinetis declaration in its composer.json (see kinetis.dev/docs/cli.html):

• Commands: migrate, migrate:rollback, migrate:status, and migrate:make on vendor/bin/kinetis. All four run without the application's bootstrap (bootstrap: false) — they read DB_* directly, so they work in bare contexts (CI, an init container) with nothing but environment variables.
• Events: Kinetis\Migrations\Events\MigrationApplied and MigrationRolledBack, dispatched once per migration migrate/ migrate:rollback actually runs. See kinetis.dev/docs/events.html for the full list across every package.

That's the entire extra.kinetis surface — no service bindings, routes, middleware, event listeners it registers itself, or MCP tools.

Configuration

The migrate* commands read the same DB_* keys kinetis/persistence documents (DB_CONNECTION/DB_HOST/DB_NAME/DB_USER/DB_PASSWORD/ DB_PORT, ...) from the environment or .env, plus one key of this package's own:

Key	Default	Purpose
MIGRATE_CONNECTION_NAME	default	Which named DB_* block to migrate; the --connection=<name> flag wins over it.

Full reference across every package: kinetis.dev/docs/config.html.

Installation

composer require kinetis/migrations

Requires PHP 8.4+, kinetis/framework, and kinetis/persistence. Full documentation: kinetis.dev/docs/migrations.html.

License

MIT — see LICENSE.