Download the PHP package dakujem/migrun without Composer

Migrun

A lightweight, flexible migration runner for your PHP stack.

Database migrations on your terms.
No framework lock-in. No config files. Any database.

💿 composer require dakujem/migrun

What is Migrun?

Migrun looks for migration files and makes sure each one has run exactly once. It is a lightweight, hackable tool to help you manage database changes consistently. It is intended to be incorporated into your existing project setup.

Migrun does not:

• provide a migration framework
• provide a query builder
• provide a database abstraction layer or any sort of ORM
• enforce usage of a particular database connection type or library

Migration file format

Migrun imposes no restrictions on filenames. By default, any .php file placed in the configured directory is picked up as a migration.

Execution order

The built-in DirectoryFinder sorts migrations lexicographically by their ID, which is the filename stem (the path relative to the migrations directory, without the .php extension). The order in which migrations run is therefore determined entirely by the filename.

Recommended naming convention

For execution order to match creation order, prefix each filename with a timestamp:

Examples:

With this convention, lexicographic and chronological order coincide. Any other stable, monotonically increasing prefix (a sequential number, a date-only stamp, etc.) works just as well — pick whatever your team finds clearest.

The timestamp in the filename is purely for ordering. The history storage records the time the migration ran, not the time encoded in the filename.

Format A — callable (up only)

The file returns a callable. Its typed parameters are autowired from the PSR-11 container by class name (when using ContainerInvoker).

Format B — anonymous class (up + down)

The file returns a ReversibleMigration instance to support rollback.

up() and down() may declare typed parameters beyond the parameter-less interface signature. PHP's LSP rules require these to have default values, and the invoker will override the defaults with container-resolved instances automatically.

Quick setup

Recommended — PDO storage with a container

The most practical setup: store the migration history in the same database you are migrating. This keeps everything in one place, avoids a separate file to manage or gitignore, and lets the history participate in database backups and restores naturally.

PdoStorage creates the history table automatically on first use. Works with MySQL, PostgreSQL, SQLite, and any other PDO-compatible database.

Minimal — no options

The absolute minimum: only the migrations directory is required. Everything else uses built-in defaults.

Storage defaults to {migrations-dir}/.migrun/migrun.json — no extra configuration needed. Migration files must accept no arguments (or have all defaults).

Important: The default JSON storage file tracks which migrations have already run. If it is committed to version control and then overwritten (e.g. reset to an earlier state or deleted), Migrun will re-run migrations that have already been applied. Add the file to .gitignore to prevent this:

This covers both the default JSON file and the default SQLite file, since both live under .migrun/. If you configure a custom storage path, gitignore that path instead. Using PDO storage in the same database avoids this concern entirely.

All builder options

Storage backend (mutually exclusive — build() throws if more than one is set):

Full manual composition

The builder is a convenience layer. Every collaborator can be constructed and wired by hand for complete control.

Running from the CLI

Migrun ships no CLI command of its own — keeping it decoupled from any console framework. The recommended pattern is a small standalone PHP script you invoke directly.

Standalone script

Create bin/migrate.php (or wherever suits your project):

Make it executable and run:

Via Composer scripts

Add the commands to the scripts section of your composer.json:

Then run:

Pass extra arguments with --:

Symfony Console command

If your project already uses Symfony Console:

Wire it the same way as any other command in your framework:

Extending

Concepts

Every part is replaceable. Wire the built-ins for quick setup; swap them out as your project grows.

Custom storage

For the common case of a SQL database, use the built-in PdoStorage (or SqliteStorage):

Wire it via the builder:

For anything else — Redis, S3, a remote API — implement TracksMigrations directly:

Custom finder

Implement DiscoversMigrations to customize the way migrations are discovered (filtering, multiple directories, etc.).

Custom invoker

Implement InvokesCallable to integrate any DI framework's invoker. Below are ready-to-copy adapters for two common packages.

php-di/invoker

Usage:

dakujem/wire-genie

Usage:

Custom executor

Implement ExecutesMigrations to wrap each migration in a transaction, add logging, emit events, etc:

Seeders

Because an Orchestrator is just a directory + storage + invoker, you can run a second one for database seeders with no extra infrastructure:

Seeds are tracked independently of migrations — running one never affects the other's history.

Migrating between storage backends

If you need to switch storage backends (e.g. from the default JsonFileStorage to PdoStorage), use the storage API to transfer the history. Read all applied migrations from the old backend in reverse order (oldest first), then mark them applied in the new one:

This works for any combination of backends.

Switching between PdoStorage and MysqliStorage requires no data migration — both adapters use the same table schema (id, applied_at). Point the new adapter at the existing table and it works immediately.