README

MongoDB Migrations

The MongoDB Migration library provides managed migration support for MongoDB. It was moved to the doesntmattr organisation from antimattr/mongodb-migrations to continue maintenance (See issue 16).

The original authors are @rcatlin and @matthewfitz

It follows the structure and features provided by Doctrine Migrations.

PHP Version Support

If you require php 5.6 support use version ^1.0. Version ^3.0 requires at least php 7.1. The 1.x releases will only receive bug fixes.

Symfony Bundle

There is a Symfony Bundle you can install to more easily integrate with Symfony. Use the installation instructions there:

https://github.com/doesntmattr/mongodb-migrations-bundle

Installation

To install with composer:

# For php 5.6
composer require "doesntmattr/mongodb-migrations=^1.0"

# For php 7.1
composer require "doesntmattr/mongodb-migrations=^3.0"

Features

Configuration

Similar to Doctrine Migrations, configuration is separated into 2 files:

Connection configuration (php)
Migration configuration (xml or yaml)

Example connection configuration "test_antimattr_mongodb.php":

/**
 * @link http://php.net/manual/en/mongoclient.construct.php
 */
return [
    'host' => 'localhost', // default is localhost
    'port' => '27017', // default is 27017
    'dbname' => null, // optional, if authentication DB is required
    'user' => null, // optional, if authentication is required
    'password' => null, // optional, if authentication is required
    'options' => [
        'connect' => true // recommended
    ]
];

XML or YAML migration configuration files are supported.

Example XML "test_antimattr_mongodb.xml":

<?xml version="1.0" encoding="UTF-8"?>
<antimattr-migrations xmlns="http://doctrine-project.org/schemas/migrations/configuration"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://doctrine-project.org/schemas/migrations/configuration
                    http://doctrine-project.org/schemas/migrations/configuration.xsd">

    <name>AntiMattr Sandbox Migrations</name>
    <migrations-namespace>AntiMattrMigrationsTest</migrations-namespace>
    <database name="test_antimattr_migrations" />
    <collection name="antimattr_migration_versions_test" />
    <migrations-directory>/path/to/migrations/classes/AntiMattrMigrations</migrations-directory>
    <!-- Script Directory Optional -->
    <migrations-script-directory>/path/to/migrations/script_directory</migrations-script-directory>

</antimattr-migrations>

Example YAML "test_antimattr_mongodb.yml":

---
name: AntiMattr Sandbox Migrations
migrations_namespace: AntiMattrMigrationsTest
database: test_antimattr_migrations
collection_name: antimattr_migration_versions_test
migrations_directory: /path/to/migrations/classes/AntiMattrMigrations
migrations_script_directory: /path/to/migrations/script_directory # optional

Console Command Support

There is an example Console Application in the /demo directory.

This is how you can register commands in your application:

require '../../vendor/autoload.php';

error_reporting(E_ALL & ~E_NOTICE);

use AntiMattr\MongoDB\Migrations\Tools\Console\Command as AntiMattr;
use Symfony\Component\Console\Application;

$application = new Application();
$application->addCommands([
    new AntiMattr\ExecuteCommand(),
    new AntiMattr\GenerateCommand(),
    new AntiMattr\MigrateCommand(),
    new AntiMattr\StatusCommand(),
    new AntiMattr\VersionCommand()
]);
$application->run();

Notice the console is executable:

> cd demo/ConsoleApplication/
> ./console
Console Tool

Usage:
  [options] command [arguments]

Options:
  --help           -h Display this help message.
  --quiet          -q Do not output any message.
  --verbose        -v|vv|vvv Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
  --version        -V Display this application version.
  --ansi              Force ANSI output.
  --no-ansi           Disable ANSI output.
  --no-interaction -n Do not ask any interactive question.

Available commands:
  help                          Displays help for a command
  list                          Lists commands
mongodb
  mongodb:migrations:execute    Execute a single migration version up or down manually.
  mongodb:migrations:generate   Generate a blank migration class.
  mongodb:migrations:migrate    Execute a migration to a specified version or the latest available version.
  mongodb:migrations:status     View the status of a set of migrations.
  mongodb:migrations:version    Manually add and delete migration versions from the version table.

Generate a New Migration

> ./console mongodb:migrations:generate --db-configuration=config/test_antimattr_mongodb.php --configuration=config/test_antimattr_mongodb.yml
Generated new migration class to "Example/Migrations/TestAntiMattr/MongoDB/Version20140822185742.php"

Migrations Status

> ./console mongodb:migrations:status --db-configuration=config/test_antimattr_mongodb.php --configuration=config/test_antimattr_mongodb.yml

 == Configuration

    >> Name:                                AntiMattr Example Migrations
    >> Database Driver:                     MongoDB
    >> Database Name:                       test_antimattr_migrations
    >> Configuration Source:                demo/ConsoleApplication/config/test_antimattr_mongodb.yml
    >> Version Collection Name:             migration_versions
    >> Migrations Namespace:                Example\Migrations\TestAntiMattr\MongoDB
    >> Migrations Directory:                Example/Migrations/TestAntiMattr/MongoDB
    >> Current Version:                     0
    >> Latest Version:                      2014-08-22 18:57:44 (20140822185744)
    >> Executed Migrations:                 0
    >> Executed Unavailable Migrations:     0
    >> Available Migrations:                3
    >> New Migrations:                      3

Migrate all

This is what you will execute during your deployment process.

./console mongodb:migrations:migrate --db-configuration=config/test_antimattr_mongodb.php --configuration=config/test_antimattr_mongodb.yml 
                                                                    
                    AntiMattr Example Migrations                    
                                                                    

WARNING! You are about to execute a database migration that could result in data lost. Are you sure you wish to continue? (y/n)y
Migrating up to 20140822185744 from 0

  ++ migrating 20140822185742


     Collection test_a

     metric           before               after                difference           
     ================================================================================
     count            100                  100                  0                   
     size             20452                20452                0                   
     avgObjSize       204.52               204.52               0                   
     storageSize      61440                61440                0                   
     numExtents       2                    2                    0                   
     nindexes         1                    2                    1                   
     lastExtentSize   49152                49152                0                   
     paddingFactor    1                    1                    0                   
     totalIndexSize   8176                 16352                8176                

  ++ migrated (0.03s)

  ++ migrating 20140822185743


  ++ migrated (0s)

  ++ migrating 20140822185744


  ++ migrated (0s)

  ------------------------

  ++ finished in 0.03
  ++ 3 migrations executed

Execute a Single Migration

./console mongodb:migrations:execute --db-configuration=config/test_antimattr_mongodb.php --configuration=config/test_antimattr_mongodb.yml 20140822185742
WARNING! You are about to execute a database migration that could result in data lost. Are you sure you wish to continue? (y/n)y

  ++ migrating 20140822185742


     Collection test_a

     metric           before               after                difference           
     ================================================================================
     count            100                  100                  0                   
     size             20620                20620                0                   
     avgObjSize       206.2                206.2                0                   
     storageSize      61440                61440                0                   
     numExtents       2                    2                    0                   
     nindexes         1                    2                    1                   
     lastExtentSize   49152                49152                0                   
     paddingFactor    1                    1                    0                   
     totalIndexSize   8176                 16352                8176                

  ++ migrated (0.02s)

If you need to run a migration again, you can use the --replay argument.

Version Up or Down

Is your migration history out of sync for some reason? You can manually add or remove a record from the history without running the underlying migration.

You can delete:

./console mongodb:migrations:version --db-configuration=config/test_antimattr_mongodb.php --configuration=config/test_antimattr_mongodb.yml --delete 20140822185744

You can add:

./console mongodb:migrations:version --db-configuration=config/test_antimattr_mongodb.php --configuration=config/test_antimattr_mongodb.yml --add 20140822185744

Analyze Migrations

Identify the collections you want to analyze. Statistics will be captured before and after the migration is run.

class Version20140822185742 extends AbstractMigration
{
    public function up(Database $db)
    {
        $testA = $db->selectCollection('test_a');
        $this->analyze($testA);

        // Do the migration
    }

Execute JS Scripts

First identify the directory for scripts in your Migration Configuration:

---
name: AntiMattr Sandbox Migrations
migrations_namespace: AntiMattrMigrationsTest
database: test_antimattr_migrations
collection_name: antimattr_migration_versions_test
migrations_directory: /path/to/migrations/classes/AntiMattrMigrations
migrations_script_directory: /path/to/migrations/script_directory # optional

Then execute the scripts via AbstractMigration::executeScript():

class Version20140822185743 extends AbstractMigration
{
    public function up(Database $db)
    {
        $result = $this->executeScript($db, 'test_script.js');
    }

Contributing

PSR Standards

There is a git pre-commit hook that will fix all your contributed code to PSR standards.

You can install it with:

./bin/install.sh 
Copying /antimattr-mongodb-migrations/bin/pre-commit.sh -> /antimattr-mongodb-migrations/bin/../.git/hooks/pre-commit

Testing

Tests should pass:

$ ./vendor/bin/phpunit

Code Sniffer and Fixer

If you didn't install the git pre-commit hook then ensure you run the fixer/sniffer manually:

$ vendor/bin/php-cs-fixer fix src/
$ vendor/bin/php-cs-fixer fix tests/

doesntmattr / mongodb-migrations

Maintainers

Details