README

SQL-first migrations for PHP. Write SQL. Not magic.

Migraw is a lightweight, framework-agnostic database migration tool for PHP.

Write migrations using raw SQL when you want full control, or use the fluent API for common schema operations.

Installation

composer require eril/migraw

Initialize Migraw:

php vendor/bin/migraw init

This creates the default migraw.php configuration and migrations directory.

Quick Start

Create a migration:

php vendor/bin/migraw make create_users_table

Run pending migrations:

php vendor/bin/migraw migrate

Check migration status:

php vendor/bin/migraw status

Roll back the latest batch:

php vendor/bin/migraw rollback

Raw SQL

Raw SQL is the default migration style.

<?php

use Eril\Migraw\Migration;
use Eril\Migraw\Sql\SqlStatement;

return new class extends Migration
{
public function up(): string|array|SqlStatement
    {
        return $this->raw(<<<'SQL'
        CREATE TABLE users (
            id INT NOT NULL AUTO_INCREMENT,
            name VARCHAR(255) NOT NULL,
            email VARCHAR(180) NOT NULL,
            PRIMARY KEY (id)
        );
        SQL);
    }

    public function down(): string|array|SqlStatement
    {
        return $this->raw(<<<'SQL'
        DROP TABLE IF EXISTS users;
        SQL);
    }
};

Fluent Migrations

Migraw also provides fluent helpers for common schema operations.

public function up(): SqlStatement
{
    return $this->create('users')
        ->id()
        ->column('name VARCHAR(255) NOT NULL')
        ->column('email VARCHAR(180) NOT NULL')
        ->unique('uq_users_email', 'email')
        ->timestamps();
}

public function down(): SqlStatement
{
    return $this->drop('users')->ifExists();
}

Set the generated template in migraw.php:

'template' => 'raw', // raw | fluent

Population Migrations

Create deterministic application data with:

php vendor/bin/migraw make populate_roles --populate

Migraw supports conflict-aware population for MySQL/MariaDB, PostgreSQL and SQLite.

Schema Squashing

Compact an old migration history into a new schema baseline:

php vendor/bin/migraw squash

Migraw creates a new baseline from the current database schema, archives the superseded schema migrations, preserves population migrations, and writes a recovery manifest.

Existing installations can safely receive a squashed migration history through the normal migration command:

Restore the previous migration history with:

php vendor/bin/migraw unsquash

Squashing changes the managed migration history without rebuilding the existing database.

Commands

init[:driver]             Initialize Migraw
make <name>               Create a migration
migrate / up              Run pending migrations
rollback / down           Roll back the latest batch
reset                     Roll back all migrations
refresh                   Roll back and migrate again
fresh                     Rebuild from a clean schema
status                    Show migration status
validate                  Validate migration files
doctor                    Check the environment
repair                    Repair migration records
squash [name]             Create a schema baseline
unsquash [archive]        Restore pre-squash history
help                      Show CLI help

Use:

php vendor/bin/migraw help

for the current CLI reference.

Database Support

Feature	MySQL / MariaDB	PostgreSQL	SQLite
Raw migrations	✓	✓	✓
Fluent migrations	✓	✓	✓
Population migrations	✓	✓	✓
Checksums / repair	✓	✓	✓
Schema squash	✓	✓	✓
Squash adoption	✓	✓	✓

Documentation

Full documentation:

https://erilshackle.github.io/php-migraw/

Useful references:

AI / LLM Reference

Migraw provides dedicated references for AI coding assistants:

llms.txt — concise guidance and documentation index
llms-full.txt — complete self-contained reference

License

Migraw is open-source software licensed under the MIT License.

eril / migraw

Maintainers

Package info

Statistics

Security