Migrator is a simple database migration tool for PHP
The goal of this project is to create a simple yet modular database schema migration tool which would be easy to integrate with your project or to use standalone.
Installation
Use composer: composer require lazypdo/migrator
Migrations
Migrations is a set of SQL files residing in a dedicated directory.
Naming
Every migration is a SQL file. The naming convention is the following:
<version>.<direction>.<memo>.sql
- version: a natural (positive integer) number
- direction: either "up" or "down"
- memo: optional text
Examples:
0004.up.create_foo_table.sql
042.down.sql
It is recommended to put a few leading zeros to make the migrations appear nicely sorted in file managers.
Versions
- File
<N>.up.sql
defines the migration from N-1 to N. - File
<N>.down.sql
defines the migration from N back to N-1.
Versioning starts with 1. Every consequential upward migration must take the next natural number. When it is not possible to create a corresponding downward migration, the entire file must be omitted. E.g. if "42.up.sql" exists, but "42.down.sql" does not, Migrator will only be able to go from 41 to 42 but never back.
Using Migrator standalone
Configuration is pretty straightforward. Create a configuration file "migrator.php":
<?php
return [
'my_database' => [
'dsn' => 'pgsql:host=localhost;port=5432;dbname=testdb',
'user' => 'my-database_user',
'password' => 'my_database_password',
'options' => [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION
],
'migrations' => '/path/to/migrations'
]
];
Parameters user, password, and options are optional.
You can add as many databases as you want. The configuration file must
either be in the current directory or specified using --config
option:
./migrator --config=/path/to/migrator.php status
It is also possible to use json and yaml configs.
Migrator has just two commands: status and migrate.
Status
Shows the current status of the given database. The default database name is "default". It shows the current versions and possible migration range: the minimal and maximum version possible to migrate to.
./migrator my_database status
Migrate
Migrates the database to the given target version.
./migrator my_database migrate [version]
- version: target version. If omitted, the highest possible version will be used.
Using Migrator in your project
Your project might already have its configuration infrastructure. You can tailor Migrator to your needs in just two steps.
1. Implement \Migrator\Factory\FactoryInterface
This is what gives the console application an instance of Migrator for a given database name.
class MyMigratorFactory implements \Migrator\Factory\FactoryInterface
{
/**
* Get an instance of Migrator for the given config
* @param string $name
* @return \Migrator\Migrator
*/
public function getMigrator($name)
{
// Here you will need 3 components
/* @var PDO */
$pdo = ...;// Get it from your config according to the $name
/* @var \Migrator\MigrationReaderInterface */
$migrationReader = ...; // Use \Migrator\MigrationReader\SingleFolderCallbackMigrationReader or create your own
/* @var \Migrator\VersionLogInterface */
$log = ...; // Use \Migrator\VersionLog\DatabaseLog or create your own
return new \Migrator\Migrator($pdo, $migrationReader, $log);
}
}
2. Create your executable
Create a file called my_migrator
in your project's bin directory.
#!/usr/bin/env php
<?php
require_once __DIR__ . '/vendor/autoload.php';
$app = new \Migrator\Console\Application(
new MyMigratorFactory()
);
$app->run();
Make it executable: chmod +x my_migrator
.
Done.