123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357 |
- 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:
- .. code-block:: sh
- $ 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:
- .. configuration-block::
- .. code-block:: php
- <?php
- return [
- 'table_storage' => [
- 'table_name' => 'doctrine_migration_versions',
- 'version_column_name' => 'version',
- 'version_column_length' => 1024,
- '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,
- 'check_database_platform' => true,
- 'organize_migrations' => 'none',
- 'connection' => null,
- 'em' => null,
- ];
- .. code-block:: yaml
- table_storage:
- table_name: doctrine_migration_versions
- version_column_name: version
- version_column_length: 1024
- 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
- check_database_platform: true
- organize_migrations: none
- connection: null
- em: null
- .. code-block:: xml
- <?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="1024"
- 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>
- <check-database-platform>true</check-database-platform>
- <organize_migrations>none</organize_migrations>
- </doctrine-migrations>
- .. code-block:: json
- {
- "table_storage": {
- "table_name": "doctrine_migration_versions",
- "version_column_name": "version",
- "version_column_length": 1024,
- "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,
- "check_database_platform": true,
- "organize_migrations": "none"
- "connection": null,
- "em": null
- }
- Please note that if you want to use the YAML configuration option, you will need to install the ``symfony/yaml`` package with composer:
- .. code-block:: sh
- composer require symfony/yaml
- Here are details about what each configuration option does:
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | Name | Required | Default | Description |
- +============================+============+==============================+==================================================================================+
- | migrations_paths<string, string> | yes | null | The PHP namespace your migration classes are located under and the path to a directory where to look for migration classes. |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | 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. |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | 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 (``year_and_month``) subdirectories. |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | connection | no | null | The named connection to use (available only when ConnectionRegistryConnection is used). |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | em | no | null | The named entity manager to use (available only when ManagerRegistryEntityManager is used). |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- Here the possible options for ``table_storage``:
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | Name | Required | Default | Description |
- +============================+============+==============================+==================================================================================+
- | table_name | no | doctrine_migration_versions | The name of the table to track executed migrations in. |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | version_column_name | no | version | The name of the column which stores the version name. |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | version_column_length | no | 1024 | The length of the column which stores the version name. |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | executed_at_column_name | no | executed_at | The name of the column which stores the date that a migration was executed. |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- | execution_time_column_name | no | execution_time | The name of the column which stores how long a migration took (milliseconds). |
- +----------------------------+------------+------------------------------+----------------------------------------------------------------------------------+
- 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:
- .. configuration-block::
- .. code-block:: php
- <?php
- return [
- // ..
- 'migrations' => [
- 'MyProject\Migrations\NewMigration',
- ],
- ];
- .. code-block:: yaml
- // ...
- migrations:
- - "MyProject\Migrations\NewMigration"
- .. code-block:: xml
- <?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>
- .. code-block:: json
- {
- // ...
- "migrations": [
- "DoctrineMigrations\NewMigration"
- ]
- }
- All or Nothing Transaction
- --------------------------
- .. note::
- 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
- From the Command Line
- ~~~~~~~~~~~~~~~~~~~~~
- You can also set this option from the command line with the ``migrate`` command and the ``--all-or-nothing`` option:
- .. code-block:: sh
- $ ./vendor/bin/doctrine-migrations migrate --all-or-nothing
- If you have it enabled at the configuration level and want to change it for an individual migration you can
- pass a value of ``0`` or ``1`` to ``--all-or-nothing``.
- .. code-block:: sh
- $ ./vendor/bin/doctrine-migrations migrate --all-or-nothing=0
- 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:
- .. code-block:: php
- <?php
- return [
- 'dbname' => 'migrations_docs_example',
- 'user' => 'root',
- 'password' => '',
- 'host' => 'localhost',
- 'driver' => 'pdo_mysql',
- ];
- 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:
- .. code-block:: sh
- $ mysqladmin create migrations_docs_example
- If you have already a DBAL connection available in your application, ``migrations-db.php`` can return it directly:
- .. code-block:: php
- <?php
- use Doctrine\DBAL\DriverManager;
- return DriverManager::getConnection([
- 'dbname' => 'migrations_docs_example',
- 'user' => 'root',
- 'password' => '',
- 'host' => 'localhost',
- 'driver' => 'pdo_mysql',
- ]);
- 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.
- .. code-block:: php
- <?php
- require 'vendor/autoload.php';
- use Doctrine\DBAL\DriverManager;
- use Doctrine\Migrations\Configuration\Configuration\PhpFile;
- use Doctrine\Migrations\Configuration\Connection\ExistingConnection;
- 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));
- 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:
- .. code-block:: sh
- composer require doctrine/orm
- Now update your ``cli-config.php`` in the root of your project to look like the following:
- .. code-block:: php
- <?php
- require 'vendor/autoload.php';
- use Doctrine\ORM\EntityManager;
- use Doctrine\ORM\Tools\Setup;
- use Doctrine\Migrations\Configuration\EntityManager\ExistingEntityManager;
- use Doctrine\Migrations\DependencyFactory;
- $config = new PhpFile('migrations.php'); // Or use one of the Doctrine\Migrations\Configuration\Configuration\* loaders
- $paths = [__DIR__.'/lib/MyProject/Entities'];
- $isDevMode = true;
- $ORMconfig = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode);
- $entityManager = EntityManager::create(['driver' => 'pdo_sqlite', 'memory' => true], $ORMconfig);
- return DependencyFactory::fromEntityManager($config, new ExistingEntityManager($entityManager));
- Make sure to create the directory where your ORM entities will be located:
- .. code-block:: sh
- $ mkdir lib/MyProject/Entities
- :ref:`Next Chapter: Migration Classes <migration-classes>`
|