Migration Framework - Maid

Declarative, executable, and language-agnostic migrations—for databases, infrastructure, queues, and beyond.

Unlike traditional frameworks that only migrate databases, Sugoi’s migration system is general-purpose by design. Whether you’re managing database schemas, Kafka topics, feature flags, or cloud infrastructure—migrations are the way to declaratively manage versioned changes across environments.

The migration ledger itself is persistence agnostic and more persistence methods outside SQL will be supported in the future. The migration runner also acquires a lock in the database automatically to ensure single execution.

Inspired by Flyway (Java) and designed to feel native to PHP and Sugoi’s developer ergonomics, this framework offers:

• Rich versioning
• Flexible scripting (PHP, SQL, future: scripts, cloud infrastructure APIs, Kafka, etc.)
• Full framework bootstrapping during execution
• Transactional block execution
• Git-friendly timestamped filenames

Creating a Migration

To scaffold a new migration:

sugoi make:migration

You'll be prompted for a description, and the system will generate a filename like:

./resources/migrations/V_2025_05_28_153012__create_users_table.php

Timestamp Format

• Y_m_d_His → 2025_05_28_153012

Migration Types

Prefix	Type	Behaviour
V_	Versioned	Executes once per environment, in order
R_	Repeatable	Re-runs on every startup if the file hash changes
T_	Task-based	Future

You can mix and match. Sugoi will track migration state per type and driver.

Writing a migration

Sugoi migrations are just PHP scripts. The full framework is bootstrapped during execution, giving you access to anything you need from service container injections to direct DB or Redis connections.

But, what makes it stand apart from pure PHP script is the transactional echo blocks.

<?php

// Each echo blocks is executed in a separate transaction
echo <<<SQL
CREATE TABLE users (
  id UUID PRIMARY KEY,
  name VARCHAR(255)
);
SQL;

// You can have multiple blocks in the same file
echo <<<SQL
INSERT INTO users (id, name) VALUES (gen_random_uuid(), 'Alice');
SQL;

Sugoi uses the HEREDOC tag (<<<SQL, <<<KAFKA, etc.) to auto-detect the language/driver to use.

• <<<SQL → SQL executed by your configured DB driver.
• Future: <<<KAFKA, <<<REDIS, <<<SHELL, <<<JSON, etc.

This makes migrations expressive and modular without requiring special DSLs.

Tips

• Keep versioned migrations (V_) deterministic—avoid runtime decisions.
• Use repeatable (R_) when you want declarative re-runs like seeders, views, or Kafka topic declarations.
• Avoid dynamic timestamps inside SQL blocks to preserve idempotency in versioned migrations.

Hybrid Migration

<?php

use SugoiCloud\Support\Str;
use App\Services\KafkaConfigurator;

echo <<<SQL
CREATE TABLE audit_log (
    id UUID PRIMARY KEY,
    event TEXT,
    occurred_at TIMESTAMP DEFAULT NOW()
);
SQL;

KafkaConfigurator::ensureTopicExists('audit-log');

This mixes transactional DB migration with dynamic Kafka setup—clean and powerful.

Cleanup and Rollbacks?

Sugoi does not support rollbacks by design. The philosophy aligns with Flyway:

• Forward-only migrations.
• If you need to "undo", create a new migration to reverse the change.
• This avoids brittle down-migration logic and keeps deployment logs linear and predictable.

Running migrations

Sugoi runs all migrations automatically before your application starts by design.

Why? Because starting new code against outdated schemas or infrastructure is usually a recipe for disaster.

By running migrations first, Sugoi ensures:

• Database schemas are up-to-date
• Kafka topics, infrastructure, and config are validated
• Message queues can be drained of old schemas before starting to ensure they are safe to consume
• Your app only starts if everything is ready

This integrates perfectly with containerized environments that use readiness checks, your service won’t go live until migrations are successful.

Before your app boots:

• All migrations are discovered
• Executed in order (versioned, repeatable)
• Validated and recorded
• Only then does the application start

Roadmap

• [x] SQL
• [x] PHP
• [ ] Shell scripts
• [ ] Kafka
• [ ] Redis

Summary

Sugoi’s migration framework gives you:

• One tool to rule all environments
• Transactions and scripting without ceremony
• Native PHP flexibility + multi-language hooks
• Developer-first DX with real migrations as code