Doctrine Migrations

https://github.com/doctrine/migrations
Admin
Doctrine Migrations is a powerful tool built on top of the Doctrine Database Abstraction Layer...
Tokens:70,021
Snippets:485
Trust Score:9.7
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/introduction.rst

Installs the Doctrine Migrations package via Composer, then runs the migrations console application from vendor/bin.

```sh
composer require "doctrine/migrations"
```

```sh
./vendor/bin/doctrine-migrations
```

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

### Installing doctrine/sql-formatter for --formatted option

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Command to install the doctrine/sql-formatter package required for the --formatted option.

```sh
$ composer require doctrine/sql-formatter
```

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

### Create project directory

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/introduction.rst

Creates and enters a new folder for the documentation example project.

```sh
$ mkdir /data/doctrine/migrations-docs-example
$ cd /data/doctrine/migrations-docs-example
```

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

### Create MySQL database with mysqladmin

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Creates the migrations_docs_example database required by the configuration examples. Run this command before using the configuration if the database does not already exist.

```sh
$ mysqladmin create migrations_docs_example
```

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

### Define a migration with up() and down() methods

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Example migration class that creates an example_table in the up() method and drops it in down(). The getDescription() method returns a human-readable description shown in status output.

```php
<?php

declare(strict_types=1);

namespace MyProject\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

/**
 * Auto-generated Migration: Please modify to your needs!
 */
final class Version20180601193057 extends AbstractMigration
{
    public function getDescription(): string
    {
        return 'This is my example migration.';
    }

    public function up(Schema $schema): void
    {
        $this->addSql('CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id))');
    }

    public function down(Schema $schema): void
    {
        $this->addSql('DROP TABLE example_table');
    }
}
```

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

### Install symfony/yaml for YAML configuration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Required to use the YAML configuration option. Install the symfony/yaml package with Composer.

```sh
composer require symfony/yaml
```

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

### Migrations Event Subscriber Example

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/events.rst

Example of an event subscriber that listens for all Doctrine Migrations events.

```APIDOC
## Event Subscriber Example

### Description
This example demonstrates how to create an event subscriber that listens for all Doctrine Migrations events. The subscriber implements the `Doctrine\Common\EventSubscriber` interface and registers itself with the DBAL connection's event manager.

### Method
N/A (Event Subscriber)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Code
```php
<?php

use Doctrine\Common\EventSubscriber;
use Doctrine\Migrations\Event\MigrationsEventArgs;
use Doctrine\Migrations\Event\MigrationsVersionEventArgs;
use Doctrine\Migrations\Events;

class MigrationsListener implements EventSubscriber
{
    public function getSubscribedEvents(): array
    {
        return [
            Events::onMigrationsMigrating,
            Events::onMigrationsMigrated,
            Events::onMigrationsVersionExecuting,
            Events::onMigrationsVersionExecuted,
            Events::onMigrationsVersionSkipped,
        ];
    }

    public function onMigrationsMigrating(MigrationsEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsMigrated(MigrationsEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsVersionExecuting(MigrationsVersionEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsVersionExecuted(MigrationsVersionEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsVersionSkipped(MigrationsVersionEventArgs $args): void
    {
        // ...
    }
}
```
```

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

### Advanced configuration with cli-config.php

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Place this file in the project root or in a config folder to use an existing application connection setup. It requires the autoloader and returns a DBAL connection for the migrations CLI.

```php
<?php

require 'vendor/autoload.php';

use Doctrine\\DBAL\\DriverManager;
use Doctrine\Migrations\Configuration\Configuration;

$config = new Configuration($connection);
$config->setName('My Project Migrations');
$config->setMigrationsNamespace('MyProject\Migrations');
$config->setMigrationsColumnName('migration_version');

```

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

### Example of correct sorting with zero-padded version numbers

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/version-numbers.rst

Shows that zero-padding custom version numbers to 14 characters (same length as the date format) ensures correct ordering with sort($versions, SORT_STRING). Includes a generated version as an example.

```php
<?php

$versions = [
    'Version00000000000001',
    'Version00000000000002',
    // ...
    'Version00000000000010',
    'Version20180107070000', // generated version
];

sort($versions, SORT_STRING);

var_dump($versions);
/*
array(4) {
  [0] =>
  string(21) "Version00000000000001"
  [1] =>
  string(21) "Version00000000000002"
  [2] =>
  string(21) "Version00000000000010"
  [3] =>
  string(21) "Version20180107070000"
}
*/
```

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

### Custom Configuration Setup in PHP

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-configuration.rst

Use this PHP script to manually build the Doctrine Migrations Configuration instance instead of using YAML or XML. It requires a custom integration and sets up the database connection, migrations directory, and metadata storage configuration.

```php
#!/usr/bin/env php
<?php

require_once __DIR__.'/vendor/autoload.php';

use Doctrine\(...)
```

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

### Diff command SQL output

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Example output from the diff command showing SQL statements and execution statistics.

```sql
CREATE TABLE users (id INT AUTO_INCREMENT NOT NULL, username VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id)) DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci ENGINE = InnoDB
DROP TABLE example_table

++ migrated (took 75.9ms, used 8M memory)

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

++ finished in 84.3ms
++ used 8M memory
++ 1 migrations executed
++ 1 sql queries
```

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

### Execute custom migrations script

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-integration.rst

Run the custom migrations script to start the Doctrine Migrations console application.

```bash
$ ./migrations
```

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

### Override preUp() to run code before up()

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

This method gets called before the up() method is called.

```php
public function preUp(Schema $schema): void
{
}
```

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

### Registering an Event Subscriber

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/events.rst

Example of registering an event subscriber with the DBAL connection's event manager.

```APIDOC
## Registering an Event Subscriber

### Description
This example shows how to register an event subscriber with the DBAL connection's event manager using the `Connection::getEventManager()` and `EventManager::addEventSubscriber()` methods. This is typically done in the `cli-config.php` file or within a framework's container or dependency injection configuration.

### Method
N/A (Event Subscriber Registration)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Code
```php
<?php

use Doctrine\DBAL\DriverManager;

$connection = DriverManager::getConnection([
    // ...
]);

$connection->getEventManager()->addEventSubscriber(new MigrationsListener());

// rest of the cli set up...
```
```

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

### Use skipIf() to skip migration on condition

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Use the skipIf method to skip the migration if a condition is met. The example shows a condition of true, which will always skip.

```php
public function up(Schema $schema): void
{
    $this->skipIf(true, 'Skipping this migration.');

    // ...
}
```

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

### Override preDown() to run code before down()

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

This method gets called before the down() method is called.

```php
public function preDown(Schema $schema): void
{
}
```

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

### Override postUp() to run code after up()

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

This method gets called after the up() method is called.

```php
public function postUp(Schema $schema): void
{
}
```

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

### Use abortIf() to abort migration on condition

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Use the abortIf method to abort the migration if a condition is met. The example shows a condition of true, which will always abort.

```php
public function up(Schema $schema): void
{
    $this->abortIf(true, 'Something went wrong. Aborting.');

    // ...
}
```

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

### Use warnIf() to warn on a condition

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Use the warnIf method to issue a warning if a condition is met. The example shows a condition of true, which will always trigger the warning.

```php
public function up(Schema $schema): void
{
    $this->warnIf(true, 'Something might be going wrong');

    // ...
}
```

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

### Override postDown() to run code after down()

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

This method gets called after the down() method is called.

```php
public function postDown(Schema $schema): void
{
}
```

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

### Example of incorrect sorting with custom version numbers

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/version-numbers.rst

Shows how sort($versions, SORT_STRING) can order 'Version10' before 'Version2', causing potential database damage. This is the problematic scenario to avoid.

```php
<?php

$versions = [
    'Version1',
    'Version2',
    // ...
    'Version10',
];

sort($versions, SORT_STRING);

var_dump($versions);

/*
array(3) {
  [0] =>
  string(8) "Version1"
  [1] =>
  string(9) "Version10"
  [2] =>
  string(8) "Version2"
}
*/
```

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

### Simple connection configuration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

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.

```php
<?php

```

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

### Using StubSchemaProvider

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Demonstrates using the StubSchemaProvider by passing a Schema object to its constructor and verifying createSchema returns the same schema.

```php
<?php

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\Provider\StubSchemaProvider;

$schema = new Schema();

$table = $schema->createTable('users');

$table->addColumn('id', 'integer', [
    'autoincrement' => true,
]);

$table->addColumn('username', 'string', [
    'notnull' => false,
]);

$table->setPrimaryKey(array('id'));

$provider = new StubSchemaProvider($schema);
$provider->createSchema() === $schema; // true
```

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

### Preview migration with --dry-run

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Perform a dry run of the migrate command to preview the SQL that will be executed without applying changes. The output shows the migration steps and the SQL statements that would be run.

```sh
$ ./vendor/bin/doctrine-migrations migrate --dry-run

                    My Project Migrations


Executing dry run of migration up to MyProject\Migrations\Version20180601193057 from 0

  ++ migrating MyProject\Migrations\Version20180601193057

     -> CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id))

  ++ migrated (took 60.9ms, used 8M memory)

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

  ++ finished in 69.4ms
  ++ used 8M memory
  ++ 1 migrations executed
  ++ 1 sql queries
```

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

### Make migrations script executable

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-integration.rst

Run this command to make the custom migrations script executable.

```bash
$ chmod +x migrations
```

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

### Check migration status with versions

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Shows the current migration status with version details. Use --show-versions to list all available versions and their execution state.

```sh
$ ./vendor/bin/doctrine-migrations status --show-versions

     == Configuration

        >> Name:                                               My Project Migrations
        >> Database Driver:                                    pdo_mysql
        >> Database Host:                                      localhost
        >> Database Name:                                      migrations_docs_example
        >> Configuration Source:                               /data/doctrine/migrations-docs-example/migrations.php
        >> Version Table Name:                                 doctrine_migration_versions
        >> Version Column Name:                                version
        >> Migrations Namespace:                               MyProject\Migrations
        >> Migrations Directory:                               /data/doctrine/migrations-docs-example/lib/MyProject/Migrations
        >> Previous Version:                                   0
        >> Current Version:                                    2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)
        >> Next Version:                                       Already at latest version
        >> Latest Version:                                     2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)
        >> Executed Migrations:                                1
        >> Executed Unavailable Migrations:                    0
        >> Available Migrations:                               1
        >> New Migrations:                                     0

     == Available Migration Versions

        >> 2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)                migrated (executed at 2018-06-01 17:08:44)     This is my example migration.
```

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

### Create migrations directory

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Creates the directory where migration classes will be stored. Run this from the project root before configuring migrations.

```sh
$ mkdir -p lib/MyProject/Migrations
```

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

### migrations.php Before Upgrade

Source: https://github.com/doctrine/migrations/blob/3.9.x/UPGRADE.md

The old configuration format using flat keys like 'name', 'migrations_namespace', 'table_name', 'column_name', 'column_length', 'executed_at_column_name', 'migrations_directory', 'all_or_nothing', and 'check_database_platform'. The 'name' property has been removed in the new format.

```php
<?php

return [
    'name' => 'My Project Migrations',
    'migrations_namespace' => 'MyProject\Migrations',
    'table_name' => 'doctrine_migration_versions',
    'column_name' => 'version',
    'column_length' => 14,
    'executed_at_column_name' => 'executed_at',
    'migrations_directory' => '/data/doctrine/migrations-docs-example/lib/MyProject/Migrations',
    'all_or_nothing' => true,
    'check_database_platform' => true,
];
```

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

### Execute the PHAR

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/introduction.rst

Runs the downloaded Doctrine Migrations PHAR file.

```sh
php doctrine-migrations.phar
```

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

### Use write() to output debug info

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Use the write method to output debug information to the console during a migration.

```php
public function up(Schema $schema): void
{
    $this->write('Doing some cool migration!');

    // ...
}
```

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

### Check migration status with --show-versions

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Check the status of migrations with the --show-versions option to see registered and unexecuted migrations. The output lists configuration details, current and next versions, and available migration versions.

```sh
$ ./vendor/bin/doctrine-migrations status --show-versions

     == Configuration

        >> Name:                                               My Project Migrations
        >> Database Driver:                                    pdo_mysql
        >> Database Host:                                      localhost
        >> Database Name:                                      migrations_docs_example
        >> Configuration Source:                               /data/doctrine/migrations-docs-example/migrations.php
        >> Version Table Name:                                 doctrine_migration_versions
        >> Version Column Name:                                version
        >> Migrations Namespace:                               MyProject\Migrations
        >> Migrations Directory:                               /data/doctrine/migrations-docs-example/lib/MyProject/Migrations
        >> Previous Version:                                   Already at first version
        >> Current Version:                                    0
        >> Next Version:                                       2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)
        >> Latest Version:                                     2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)
        >> Executed Migrations:                                0
        >> Executed Unavailable Migrations:                    0
        >> Available Migrations:                               1
        >> New Migrations:                                     1

     == Available Migration Versions

        >> 2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)                not migrated     This is my example migration.
```

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

### Return database connection parameters array

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Returns an array of database connection parameters for the migrations configuration. The 'dbname' key must reference an existing database; create it if needed.

```php
return [
    'dbname' => 'migrations_docs_example',
    'user' => 'root',
    'password' => '',
    'host' => 'localhost',
    'driver' => 'pdo_mysql',
];
```

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

### Download PHAR with wget

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/introduction.rst

Downloads the Doctrine Migrations PHAR for version 2.0.0 from GitHub releases.

```sh
wget https://github.com/doctrine/migrations/releases/download/v2.0.0/doctrine-migrations.phar
```

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

### Manually provide migrations in PHP configuration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Specify an array of migration classes using the 'migrations' configuration setting in a PHP configuration file.

```php
<?php

return [
    // ..

    'migrations' => [
        'MyProject\Migrations\NewMigration',
    ],
];
```

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

### Configure custom template with setCustomTemplate()

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-configuration.rst

Configures the custom migration template by setting the path to the template file.

```php
$configuration->setCustomTemplate(__DIR__ . '/custom_template.tpl');
```

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

### Doctrine Migrations configuration in PHP, YAML, XML, and JSON

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Place one of these files (migrations.php, migrations.yml, migrations.xml, or migrations.json) in the project root to configure Doctrine Migrations. The four formats are equivalent and cover table storage, migration paths, all_or_nothing, transactional, check_database_platform, organize_migrations, connection, and em options.

```php
<?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,
];
```

```yaml
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
```

```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="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>
```

```json
{
    "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
}
```

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

### getDescription

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Override this method to provide a description for your migration. The returned value is displayed when running the status command with --show-versions.

```APIDOC
## getDescription

### Description
Override this method to provide a description for your migration. The value returned here will be output when running the `./vendor/bin/doctrine-migrations status --show-versions` command.

### Method
PHP method (override)

### Endpoint
N/A - This is a PHP method to override in a migration class.

### Parameters
None.

### Request Example
```php
public function getDescription(): string
{
    return 'The description of my awesome migration!';
}
```

### Response
#### Success Response (200)
- **string** - The migration description.
```

```APIDOC
## preUp

### Description
This method gets called before the `up()` method is invoked. Override it to perform actions before the migration's up method runs.

### Method
N/A (PHP method override)

### Endpoint
N/A

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **schema** (Schema) - Required - The schema object representing the database schema.

### Request Example
```php
public function preUp(Schema $schema): void
{
    // custom logic
}
```

### Response
#### Success Response (200)
No return value (void).

#### Response Example
N/A

### Notes
- This method is called before the up() method is executed.
```

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

### Execute migration with migrate command

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Execute the migration without the --dry-run option, applying the SQL changes to the database. The command prompts for confirmation before proceeding and will run multiple migrations if available.

```sh
$ ./vendor/bin/doctrine-migrations migrate

                    My Project Migrations


WARNING! You are about to execute a database migration that could result in schema changes and data loss. Are you sure you wish to continue? (y/n)y
Migrating up to MyProject\Migrations\Version20180601193057 from 0

  ++ migrating MyProject\Migrations\Version20180601193057

     -> CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id))

  ++ migrated (took 47.7ms, used 8M memory)

  ------------------------
```

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

### Enable all-or-nothing transaction from command line

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Override configuration to enable All or Nothing Transaction using the --all-or-nothing option. Note: Passing options to --all-or-nothing is deprecated from 3.7.x and will not be allowed in 4.x.

```sh
$ ./vendor/bin/doctrine-migrations migrate --all-or-nothing
```

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

### Manually provide migrations in XML configuration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Specify migration classes using the 'migrations' configuration setting in an XML configuration file.

```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>
```

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

### Manually provide migrations in JSON configuration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Specify migration classes using the 'migrations' configuration setting in a JSON configuration file.

```json
{
    // ...

    "migrations": [
        "DoctrineMigrations\NewMigration"
    ]
}
```

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

### Adding DiffCommand manually without ORM

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Shows how to manually add the DiffCommand to a console application and set a custom schema provider in the dependency factory.

```php
<?php

use Doctrine\Migrations\Tools\Console\Command\DiffCommand;

$schemaProvider = new CustomSchemaProvider();
$dependencyFactory->setDefinition(SchemaProvider::class, static fn () => $schemaProvider);

/** @var Symfony\Component\Console\Application */
$cli->add(new DiffCommand($dependencyFactory);

// ...

$cli->run();
```

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

### Check status after revert

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Shows the migration status after reverting, confirming the database is back to its original state.

```sh
$ ./vendor/bin/doctrine-migrations status --show-versions

     == Configuration
```

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

### Implementing SchemaProviderInterface for custom schema

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Shows how to create a custom schema provider by implementing SchemaProviderInterface's createSchema method to return a Doctrine DBAL Schema object.

```php
<?php

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\Provider\SchemaProviderInterface;

final class CustomSchemaProvider implements SchemaProviderInterface
{
    public function createSchema()
    {
        $schema = new Schema();

        $table = $schema->createTable('users');

        $table->addColumn('id', 'integer', [
            'autoincrement' => true,
        ]);

        $table->addColumn('username', 'string', [
            'notnull' => false,
        ]);

        $table->setPrimaryKey(array('id'));

        return $schema;
    }
}
```

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

### Generate a blank migration with doctrine-migrations generate

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Use the generate command to create a blank migration file that you can modify. Run from the project root where the doctrine-migrations binary is available.

```sh
$ ./vendor/bin/doctrine-migrations generate
```

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

### Custom migrations script (PHP)

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-integration.rst

This PHP script sets up the Doctrine Migrations console application with a database connection and all necessary commands. It requires a migrations.php configuration file and the vendor autoload.

```php
#!/usr/bin/env php
<?php

require_once __DIR__.'/vendor/autoload.php';

use Doctrine\DBAL\DriverManager;
use Doctrine\Migrations\DependencyFactory;
use Doctrine\Migrations\Configuration\Migration\PhpFile;
use Doctrine\Migrations\Configuration\Connection\ExistingConnection;
use Doctrine\Migrations\Tools\Console\Command;
use Symfony\Component\Console\Application;

$dbParams = [
    'dbname' => 'migrations_docs_example',
    'user' => 'root',
    'password' => '',
    'host' => 'localhost',
    'driver' => 'pdo_mysql',
];

$connection = DriverManager::getConnection($dbParams);

$config = new PhpFile('migrations.php'); // Or use one of the Doctrine\Migrations\Configuration\Configuration\* loaders

$dependencyFactory = DependencyFactory::fromConnection($config, new ExistingConnection($connection));

$cli = new Application('Doctrine Migrations');
$cli->setCatchExceptions(true);

$cli->addCommands(array(
    new Command\DumpSchemaCommand($dependencyFactory),
    new Command\ExecuteCommand($dependencyFactory),
    new Command\GenerateCommand($dependencyFactory),
    new Command\LatestCommand($dependencyFactory),
    new Command\ListCommand($dependencyFactory),
    new Command\MigrateCommand($dependencyFactory),
    new Command\RollupCommand($dependencyFactory),
    new Command\StatusCommand($dependencyFactory),
    new Command\SyncMetadataCommand($dependencyFactory),
    new Command\VersionCommand($dependencyFactory),
));

$cli->run();
```

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

### migrations.php After Upgrade

Source: https://github.com/doctrine/migrations/blob/3.9.x/UPGRADE.md

The new configuration format using 'table_storage' and 'migrations_paths' arrays. The 'name' property is removed. The 'table_storage' options should only be provided if you customized the metadata table settings with v2 options; otherwise, it is recommended to omit them.

```php
<?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,
    'check_database_platform' => true,
];
```

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

### Manually provide migrations in YAML configuration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Specify migration classes using the 'migrations' configuration setting in a YAML configuration file.

```yaml
// ...

migrations:
    - "MyProject\Migrations\NewMigration"
```

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

### Revert to first migration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Reverts all migrations down to the first version using the 'first' alias. Prompts for confirmation and shows the SQL executed.

```sh
$ ./vendor/bin/doctrine-migrations migrate first

                    My Project Migrations


    WARNING! You are about to execute a database migration that could result in schema changes and data loss. Are you sure you wish to continue? (y/n)y
    Migrating down to 0 from MyProject\Migrations\Version20180601193057

      -- reverting MyProject\Migrations\Version20180601193057

         -> DROP TABLE example_table

      -- reverted (took 38.4ms, used 8M memory)

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

      ++ finished in 39.5ms
      ++ used 8M memory
      ++ 1 migrations executed
      ++ 1 sql queries
```

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

### Override getDescription() to provide a migration description

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Override this method to provide a description for your migration. The returned value is output when running the './vendor/bin/doctrine-migrations status --show-versions' command.

```php
public function getDescription(): string
{
    return 'The description of my awesome migration!';
}
```

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

### Use addSql() with parameters in up()

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Use the addSql method within up and down methods to pass SQL statements with parameters. Internally, addSql calls are passed to the executeQuery method in the DBAL, allowing prepared statements and easy parameter passing.

```php
public function up(Schema $schema): void
{
    $users = [
        ['name' => 'mike', 'id' => 1],
        ['name' => 'jwage', 'id' => 2],
        ['name' => 'ocramius', 'id' => 3],
    ];

    foreach ($users as $user) {
        $this->addSql('UPDATE user SET happy = true WHERE name = :name AND id = :id', $user);
    }
}
```

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

### Execute a single migration down

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Executes a single migration in the down direction using the --down option. Prompts for confirmation before running and shows the SQL executed.

```sh
$ ./vendor/bin/doctrine-migrations execute MyProject\Migrations\Version20180601193057 --down
WARNING! You are about to execute a database migration that could result in schema changes and data lost. Are you sure you wish to continue? (y/n)y

  ++ migrating MyProject\Migrations\Version20180601193057

     -> DROP TABLE example_table

  ++ migrated (took 42.6ms, used 8M memory)
```

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

### Disable all-or-nothing transaction from command line

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Override configuration to explicitly disable All or Nothing Transaction using the --no-all-or-nothing option.

```sh
$ ./vendor/bin/doctrine-migrations migrate --no-all-or-nothing
```

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

### Return DBAL connection from migrations-db.php

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Returns a DBAL connection directly from migrations-db.php when a DBAL connection is already available in the application. Uses DriverManager::getConnection with the same database settings.

```php
<?php
use Doctrine\DBAL\DriverManager;

return DriverManager::getConnection([
    'dbname' => 'migrations_docs_example',
    'user' => 'root',
    'password' => '',
    'host' => 'localhost',
    'driver' => 'pdo_mysql',
]);
```

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

### Registering the event subscriber with the connection's event manager

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/events.rst

Shows how to add the MigrationsListener to the DBAL connection's event manager using Connection::getEventManager() and EventManager::addEventSubscriber(). This code is intended for cli-config.php or a framework container/dependency injection configuration.

```php
<?php

use Doctrine\DBAL\DriverManager;

$connection = DriverManager::getConnection([
    // ...
]);

$connection->getEventManager()->addEventSubscriber(new MigrationsListener());

// rest of the cli set up...
```

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

### Event subscriber class listening to all migrations events

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/events.rst

Defines a MigrationsListener class implementing EventSubscriber. It subscribes to all five migration events and provides handler methods for each, using the appropriate event argument types. The methods are empty placeholders for custom logic.

```php
<?php

use Doctrine\Common\EventSubscriber;
use Doctrine\Migrations\Event\MigrationsEventArgs;
use Doctrine\Migrations\Event\MigrationsVersionEventArgs;
use Doctrine\Migrations\Events;

class MigrationsListener implements EventSubscriber
{
    public function getSubscribedEvents(): array
    {
        return [
            Events::onMigrationsMigrating,
            Events::onMigrationsMigrated,
            Events::onMigrationsVersionExecuting,
            Events::onMigrationsVersionExecuted,
            Events::onMigrationsVersionSkipped,
        ];
    }

    public function onMigrationsMigrating(MigrationsEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsMigrated(MigrationsEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsVersionExecuting(MigrationsVersionEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsVersionExecuted(MigrationsVersionEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsVersionSkipped(MigrationsVersionEventArgs $args): void
    {
        // ...
    }
}
```

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

### Use throwIrreversibleMigrationException() in down()

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Use the throwIrreversibleMigrationException method in the down method to indicate that a migration cannot be reversed. It accepts an optional message to output.

```php
public function down(Schema $schema): void
{
    $this->throwIrreversibleMigrationException();

    // ...
}
```

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

### Status output for doctrine:migrations:status

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Shows the output of the migrations status command, listing database driver, configuration source, version table, and available migrations. Use it to verify the current and next migration versions before executing.

```text
>> Name:                                               My Project Migrations
>> Database Driver:                                    pdo_mysql
>> Database Host:                                      localhost
>> Database Name:                                      migrations_docs_example
>> Configuration Source:                               /data/doctrine/migrations-docs-example/migrations.php
>> Version Table Name:                                 doctrine_migration_versions
>> Version Column Name:                                version
>> Migrations Namespace:                               MyProject\Migrations
>> Migrations Directory:                               /data/doctrine/migrations-docs-example/lib/MyProject/Migrations
>> Previous Version:                                   Already at first version
>> Current Version:                                    0
>> Next Version:                                       2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)
>> Latest Version:                                     2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)
>> Executed Migrations:                                0
>> Executed Unavailable Migrations:                    0
>> Available Migrations:                               1
>> New Migrations:                                     1

     == Available Migration Versions

        >> 2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)                not migrated     This is my example migration.
```

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

### Run migrations without interaction

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Runs migrations in unattended mode with the --no-interaction option, skipping all prompts. Useful for automated deployments.

```sh
$ ./vendor/bin/doctrine-migrations migrate --no-interaction

                    My Project Migrations


    Migrating up to MyProject\Migrations\Version20180601193057 from 0

      ++ migrating MyProject\Migrations\Version20180601193057

         -> CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id))

      ++ migrated (took 46.5ms, used 8M memory)

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

      ++ finished in 47.3ms
      ++ used 8M memory
      ++ 1 migrations executed
      ++ 1 sql queries
```

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

### Generated blank migration class in PHP

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Shows the PHP class generated by the doctrine-migrations generate command. The class extends AbstractMigration and implements up() and down() methods with an empty getDescription().

```php
<?php

declare(strict_types=1);

namespace MyProject\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

/**
 * Auto-generated Migration: Please modify to your needs!
 */
final class Version20180601193057 extends AbstractMigration
{
    public function getDescription(): string
    {
        return '';
    }

    public function up(Schema $schema): void
    {
        // this up() migration is auto-generated, please modify it to your needs

    }

    public function down(Schema $schema): void
    {
        // this down() migration is auto-generated, please modify it to your needs

    }
}

```

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

### Custom migration template without down()

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-configuration.rst

Custom migration template that omits the down() method. Placeholders <namespace>, <className>, and <up> are replaced during generation.

```php
<?php

declare(strict_types=1);

namespace <namespace>;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

final class <className> extends AbstractMigration
{
    public function up(Schema $schema): void
    {
        <up>
    }
}
```

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

### Split migration into DML and non-transactional DDL parts

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/explanation/implicit-commits.rst

Recommended split of the problematic migration into two migrations: the first performs the DML updates inside a transaction, and the second creates the table with isTransactional() returning false to avoid the implicit commit issue. This keeps DML statements transactional while allowing DDL outside a transaction.

```php
final class Version20210401193057 extends AbstractMigration
{
    public function up(Schema $schema): void
    {
        $users = [
            ['name' => 'mike', 'id' => 1],
            ['name' => 'jwage', 'id' => 2],
            ['name' => 'ocramius', 'id' => 3],
        ];

        foreach ($users as $user) {
            $this->addSql('UPDATE user SET happy = true WHERE name = :name AND id = :id', $user);
        }
    }
}
```

```php
final class Version20210401193058 extends AbstractMigration
{
    public function up(Schema $schema): void
    {
        $this->addSql('CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id))');
    }

    public function isTransactional(): bool
    {
        return false;
    }
}
```

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

### Setting schema assets filter to ignore custom tables

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Configures a schema assets filter to ignore tables prefixed with 't_' so the diff command does not drop them.

```php
$connection->getConfiguration()->setSchemaAssetsFilter(static function (string|AbstractAsset $assetName): bool {
    if ($assetName instanceof AbstractAsset) {
        $assetName = $assetName->getName();
    }

    return (bool) preg_match("~^(?!t_)~", $assetName);
});
```

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

### User entity with ORM mapping attributes

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Defines a User entity using Doctrine ORM attributes for migration diffing. Create this file at lib/MyProject/Entities/User.php to let Doctrine compare your mapping information against the current database schema.

```php
<?php

namespace MyProjectundle	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est	est
```

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

### Delete a migration version with doctrine-migrations --delete

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Deletes the specified migration version from the version table using the `version` command with the `--delete` flag. This does not execute any migrations; it only removes the version entry from the tracking table.

```sh
$ ./vendor/bin/doctrine-migrations version 'MyProject\Migrations\Version20180601193057' --delete

```

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

### isTransactional

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Override this method to disable transactions in a migration. Defaults to true.

```APIDOC
## isTransactional

### Description
Override this method if you want to disable transactions in a migration. It defaults to true.

### Method
Override

### Signature
public function isTransactional(): bool

### Parameters
None

### Return Value
- **bool** - Return false to disable transactions.

### Example
```php
public function isTransactional(): bool
{
    return false;
}
```
```

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

### Override isTransactional() to disable transactions

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Override this method to disable transactions in a migration. It defaults to true. Note that some database platforms like MySQL or Oracle do not support DDL statements in transactions and may implicitly commit the transaction before running the statement.

```php
public function isTransactional(): bool
{
    return false;
}
```
Tokens:
Raw