You are browsing a version that has not yet been released. |
Configuration
So you are ready to start configuring your migrations? We just need to provide a few bits of information for the console application in order to get started.
Migrations Configuration
First we need to configure information about your migrations. In /data/doctrine/migrations-docs-example
go ahead and create a folder to store your migrations in:
$ mkdir -p lib/MyProject/Migrations
Now, in the root of your project place a file named migrations.php
, migrations.yml
,
migrations.xml
or migrations.json
and place the following contents:
- PHP
1 <?php return [ 'table_storage' => [ 'table_name' => 'doctrine_migration_versions', 'version_column_name' => 'version', 'version_column_length' => 191, 'executed_at_column_name' => 'executed_at', 'execution_time_column_name' => 'execution_time', ], 'migrations_paths' => [ 'MyProject\Migrations' => '/data/doctrine/migrations/lib/MyProject/Migrations', 'MyProject\Component\Migrations' => './Component/MyProject/Migrations', ], 'all_or_nothing' => true, 'transactional' => true, 'check_database_platform' => true, 'organize_migrations' => 'none', 'connection' => null, 'em' => null, ]; 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 - YAML
1 table_storage: table_name: doctrine_migration_versions version_column_name: version version_column_length: 191 executed_at_column_name: executed_at execution_time_column_name: execution_time migrations_paths: 'MyProject\Migrations': /data/doctrine/migrations/lib/MyProject/Migrations 'MyProject\Component\Migrations': ./Component/MyProject/Migrations all_or_nothing: true transactional: true check_database_platform: true organize_migrations: none connection: null em: null 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 - XML
1 <?xml version="1.0" encoding="UTF-8"?> <doctrine-migrations xmlns="http://doctrine-project.org/schemas/migrations/configuration/3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://doctrine-project.org/schemas/migrations/configuration/3.0 http://doctrine-project.org/schemas/migrations/configuration-3.0.xsd"> <connection>default</connection> <em>default</em> <storage> <table-storage table-name="doctrine_migration_versions" version-column-name="version" version-column-length="191" executed-at-column-name="executed_at" execution-time-column-name="execution_time" /> </storage> <migrations-paths> <path namespace="MyProject\Migrations">/data/doctrine/migrations/lib/MyProject/Migrations</path> <path namespace="MyProject\Component\Migrations">./Component/MyProject/Migrations</path> </migrations-paths> <all-or-nothing>true</all-or-nothing> <transactional>true</transactional> <check-database-platform>true</check-database-platform> <organize_migrations>none</organize_migrations> </doctrine-migrations> 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 - JSON
1 { "table_storage": { "table_name": "doctrine_migration_versions", "version_column_name": "version", "version_column_length": 191, "executed_at_column_name": "executed_at", "execution_time_column_name": "execution_time" }, "migrations_paths": { "MyProject\\Migrations": "/data/doctrine/migrations/lib/MyProject/Migrations", "MyProject\\Component\\Migrations": "./Component/MyProject/Migrations" }, "all_or_nothing": true, "transactional": true, "check_database_platform": true, "organize_migrations": "none", "connection": null, "em": null } 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
Please note that if you want to use the YAML configuration option, you will need to install the symfony/yaml
package with composer:
$ composer require symfony/yaml
Here are details about what each configuration option does:
Name | Required | Default | Description |
---|---|---|---|
migrations_paths<string, string> null | The PHP namespace your migration classes are located under and the path to a dire | ||
table_storage | no | Used by doctrine migrations to track the currently executed migrations | |
all_or_nothing | no | false | Whether or not to wrap multiple migrations in a single transaction. |
transactional | no | true | Whether or not to wrap migrations in a single transaction. |
migrations | no | [] | Manually specify the array of migration versions instead of finding migrations. |
check_database_platform | no | true | Whether to add a database platform check at the beginning of the generated code. |
organize_migrations | no | none |
Whether to organize migration classes under year (year ) or year and month (`` |
connection | no | null | The named connection to use (available only when ConnectionRegistryConnection is |
em | no | null | The named entity manager to use (available only when ManagerRegistryEntityManager |
Here the possible options for table_storage
:
Manually Providing Migrations
If you don't want to rely on Doctrine finding your migrations, you can explicitly specify the array of migration
classes using the migrations
configuration setting:
- PHP
- YAML
- XML
1 <?xml version="1.0" encoding="UTF-8"?> <doctrine-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"> // ... <migrations> <migration class="MyProject\Migrations\NewMigration" /> </migrations> </doctrine-migrations> 2 3 4 5 6 7 8 9 10 11 12 - JSON
All or Nothing Transaction
This only works if your database supports transactions for DDL statements. |
When using the all_or_nothing
option, multiple migrations ran at the same time will be wrapped in a single
transaction. If one migration fails, all migrations will be rolled back
Using or not using transactions
By default, migrations are transactional, meaning code in a migration
is wrapped in a transaction.
Setting transactional
to false
will disable that.
From the Command Line
To override the configuration and explicitly enable All or Nothing Transaction from the command line,
use the --all-or-nothing
option:
$ ./vendor/bin/doctrine-migrations migrate --all-or-nothing
Passing options to --all-or-nothing is deprecated from 3.7.x, and will not be allowed in 4.x |
To override the configuration and explicitly disable All or Nothing Transaction from the command line,
use the --no-all-or-nothing
option:
$ ./vendor/bin/doctrine-migrations migrate --no-all-or-nothing
Connection Configuration
Now that we've configured our migrations, the next thing we need to configure is how the migrations console application knows how to get the connection to use for the migrations:
Simple
The simplest configuration is to put a migrations-db.php
file in the root of your
project and return an array of connection information that can be passed to the DBAL:
You will need to make sure the migrations_docs_example
database exists. If you are using MySQL you can create it with
the following command:
$ mysqladmin create migrations_docs_example
If you have already a DBAL connection available in your application, migrations-db.php
can return it directly:
Advanced
If you require a more advanced configuration and you want to get the connection to use from your existing application setup then you can use this method of configuration.
In the root of your project, place a file named cli-config.php
with the following
contents. It can also be placed in a folder named config
if you prefer to keep it
out of the root of your project.
1 <?php
require 'vendor/autoload.php';
use Doctrine\DBAL\DriverManager;
use Doctrine\Migrations\Configuration\Connection\ExistingConnection;
use Doctrine\Migrations\Configuration\Migration\PhpFile;
use Doctrine\Migrations\DependencyFactory;
$config = new PhpFile('migrations.php'); // Or use one of the Doctrine\Migrations\Configuration\Configuration\* loaders
$conn = DriverManager::getConnection(['driver' => 'pdo_sqlite', 'memory' => true]);
return DependencyFactory::fromConnection($config, new ExistingConnection($conn));
2
3
4
5
6
7
8
9
10
11
12
13
14
The above setup assumes you are not using the ORM. If you want to use the ORM, first require it in your project with composer:
$ composer require doctrine/orm
Now update your cli-config.php
in the root of your project to look like the following:
1 <?php
require 'vendor/autoload.php';
use Doctrine\ORM\EntityManager;
use Doctrine\ORM\ORMSetup;
use Doctrine\Migrations\Configuration\EntityManager\ExistingEntityManager;
use Doctrine\Migrations\DependencyFactory;
use Doctrine\Migrations\Configuration\Migration\PhpFile;
use Doctrine\DBAL\DriverManager;
$config = new PhpFile('migrations.php'); // Or use one of the Doctrine\Migrations\Configuration\Configuration\* loaders
$paths = [__DIR__.'/lib/MyProject/Entities'];
$isDevMode = true;
$ORMConfig = ORMSetup::createAttributeMetadataConfiguration($paths, $isDevMode);
$connection = DriverManager::getConnection(['driver' => 'pdo_sqlite', 'memory' => true]);
$entityManager = new EntityManager($connection, $ORMConfig);
return DependencyFactory::fromEntityManager($config, new ExistingEntityManager($entityManager));
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Make sure to create the directory where your ORM entities will be located:
$ mkdir lib/MyProject/Entities