Add transaction mode to migration generation

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 2.1.2 under development
 
+- New #367: Add configurable transaction mode and `--transactional` / `--no-transactional` options for migration
+  generation (@samdark)
 - New #363, #373: Add `migrate:mark` to move migration history to a version without executing migrations (@samdark,
   @vjik)
 - New #360, #366, #371: Add support for additional named databases with separate migration history and `--db`

README.md

@@ -53,6 +53,9 @@ migrate:up       Applies new migrations.
 
 The create command allows defining fields for the table being created.
 
+Use `--transactional` or `--no-transactional` to choose the transaction mode when creating a migration.
+See [Transactional migrations](docs/guide/en/transactional-migrations.md) to configure the default mode.
+
 Use `--db=name` to select one of [multiple databases](docs/guide/en/multiple-databases.md).
 
 ## Documentation

bin/yii-db-migration

@@ -52,6 +52,7 @@ if (!file_exists($configFile)) {
  *     maxSqlOutputLength: int|null,
  *     newMigrationNamespace: string,
  *     newMigrationPath: string,
+ *     newMigrationTransactional?: bool|null,
  *     sourceNamespaces: list<string>,
  *     sourcePaths: list<string>,
  * } $params
@@ -69,7 +70,7 @@ $migrator = new Migrator(
     $params['migrationNameLimit'],
     $params['maxSqlOutputLength']
 );
-$createService = new CreateService($db, $params['useTablePrefix']);
+$createService = new CreateService($db, $params['useTablePrefix'], $params['newMigrationTransactional'] ?? null);
 $downRunner = new DownRunner($migrator);
 $updateRunner = new UpdateRunner($migrator);
 

bin/yii-db-migration.php

@@ -40,6 +40,11 @@
      */
     'newMigrationPath' => '',
 
+    /**
+     * Whether generated migrations use transactions. Set to `null` to keep template defaults.
+     */
+    'newMigrationTransactional' => null,
+
     /**
      * List of directories containing the migration classes.
      * Migration classes located at these paths should be declared without a namespace.

composer.json

@@ -37,6 +37,7 @@
         "yiisoft/injector": "^1.2"
     },
     "require-dev": {
+        "ext-tokenizer": "*",
         "bamarni/composer-bin-plugin": "^1.9.1",
         "friendsofphp/php-cs-fixer": "^3.95.1",
         "phpunit/phpunit": "^10.5.63",

config/di-console.php

@@ -6,13 +6,21 @@
 use Yiisoft\Db\Migration\DatabaseRegistry;
 use Yiisoft\Db\Migration\Informer\ConsoleMigrationInformer;
 use Yiisoft\Db\Migration\Informer\MigrationInformerInterface;
+use Yiisoft\Db\Migration\Service\Generate\CreateService;
 use Yiisoft\Db\Migration\Service\MigrationService;
 use Yiisoft\Definitions\DynamicReference;
 use Yiisoft\Definitions\Reference;
 
 /** @var array $params */
 
 return [
+    CreateService::class => [
+        'class' => CreateService::class,
+        '__construct()' => [
+            'transactional' => $params['yiisoft/db-migration']['newMigrationTransactional'] ?? null,
+        ],
+    ],
+
     DatabaseRegistry::class => [
         '__construct()' => [
             'databases' => array_map(

config/params.php

@@ -26,6 +26,7 @@
     'yiisoft/db-migration' => [
         'newMigrationNamespace' => '',
         'newMigrationPath' => '',
+        'newMigrationTransactional' => null,
         'sourceNamespaces' => [],
         'sourcePaths' => [],
         'databases' => [],

docs/guide/en/README.md

@@ -4,4 +4,5 @@
 - [Symfony application](usage-with-symfony.md)
 - [Standalone](usage-standalone.md)
 - [Multiple databases](multiple-databases.md)
+- [Transactional migrations](transactional-migrations.md)
 - [Modifying migration history](migration-history.md)

docs/guide/en/transactional-migrations.md

@@ -0,0 +1,103 @@
+# Transactional migrations
+
+A migration that implements `Yiisoft\Db\Migration\TransactionalMigrationInterface` runs in a transaction.
+The migrator uses a separate transaction for each migration's `up()` or `down()` method, including the history update.
+
+Some database operations commit automatically or cannot run in a transaction.
+The interface does not change these limits.
+
+## Create a migration
+
+To generate a transactional migration, use `--transactional`:
+
+```shell
+./yii migrate:create update_posts --transactional
+```
+
+To generate a migration without a transaction, use `--no-transactional`:
+
+```shell
+./yii migrate:create post --command=table --no-transactional
+```
+
+Both options work with all generator commands:
+`create`, `table`, `dropTable`, `addColumn`, `dropColumn`, and `junction`.
+For Symfony, replace `./yii` with `php bin/console`. For the standalone tool, use `./vendor/bin/yii-db-migration`.
+
+## Default transaction mode
+
+Set `newMigrationTransactional` to choose the default mode for new migrations:
+
+| Value | Behavior |
+| --- | --- |
+| `true` | Generate transactional migrations. |
+| `false` | Generate migrations without transactions. |
+| `null` | Use the template's default. |
+
+By default, the built-in `table` and `junction` templates generate transactional migrations.
+The other built-in templates generate migrations without transactions.
+
+CLI options override `newMigrationTransactional`.
+If no option is set and the setting is `null`, the generator uses the template's default.
+
+For Yii Console, set the mode for the default database in `config/console/params.php`:
+
+```php
+'yiisoft/db-migration' => [
+    // ...
+    'newMigrationTransactional' => true,
+],
+```
+
+For the standalone tool, set `'newMigrationTransactional' => true` in the project's root `yii-db-migration.php` file.
+
+For Symfony, configure the `CreateService` constructor argument in `config/services.yml`:
+
+```yaml
+services:
+    Yiisoft\Db\Migration\Service\Generate\CreateService:
+        arguments:
+            $transactional: true
+```
+
+For direct PHP use, pass `transactional: true` to the `CreateService` constructor.
+Pass the `transactional` argument to `CreateService::run()` to override the mode for one call.
+
+## Named databases
+
+Each named database has its own `newMigrationTransactional` setting. It does not inherit the default database's setting.
+
+For Yii Console, add the setting to the database's entry in `databases`.
+For standalone or Symfony usage, pass it to the `DatabaseConfig` constructor:
+
+```php
+new DatabaseConfig(
+    $mapsConnection,
+    newMigrationPath: __DIR__ . '/migrations/maps',
+    newMigrationTransactional: true,
+);
+```
+
+The CLI option overrides the setting for the selected database:
+
+```shell
+./yii migrate:create update_places --db=maps --no-transactional
+```
+
+See [Multiple databases](multiple-databases.md) to configure the connections.
+
+## Change an existing migration
+
+Generation settings do not change existing migrations.
+
+To enable transactions, add `TransactionalMigrationInterface` to the migration's `implements` list.
+To disable transactions, remove it. Keep `RevertibleMigrationInterface` if the migration supports `down()`.
+
+## Custom templates
+
+Templates set with `CreateService::setTemplate()` or `CreateService::setTemplates()` receive `$transactional`.
+This variable contains the mode for the current call, or the configured mode if no override is set.
+If the value is `null`, choose a template default, for example with `$transactional ??= false`.
+
+Include the import and implementation of `TransactionalMigrationInterface` only when `$transactional` is `true`.
+Templates that ignore this variable keep their existing behavior.

resources/views/addColumnMigration.php

@@ -15,11 +15,14 @@
  * @var PhpRenderer $this
  * @var string $className The new migration class name without namespace.
  * @var string $namespace The new migration class namespace.
+ * @var bool|null $transactional Whether the migration uses transactions. `null` keeps the template default.
  * @var string $table The table name.
  * @var Column[] $columns Fields.
  * @var ForeignKey[] $foreignKeys Foreign keys.
  */
 
+$transactional ??= false;
+
 echo "<?php\n";
 
 echo "\ndeclare(strict_types=1);\n";
@@ -31,14 +34,19 @@
 
 use Yiisoft\Db\Migration\MigrationBuilder;
 use Yiisoft\Db\Migration\RevertibleMigrationInterface;
+<?php if ($transactional): ?>
+use Yiisoft\Db\Migration\TransactionalMigrationInterface;
+<?php endif; ?>
 
 /**
  * Handles adding columns to table `<?= $table ?>`.
 <?= $this->render(__DIR__ . '/_foreignTables.php', [
     'foreignKeys' => $foreignKeys,
 ]) ?>
  */
-final class <?= $className ?> implements RevertibleMigrationInterface
+final class <?= $className ?> implements RevertibleMigrationInterface<?=
+    $transactional ? ", TransactionalMigrationInterface\n" : "\n"
+?>
 {
     public function up(MigrationBuilder $b): void
     {

resources/views/createTableMigration.php

@@ -15,12 +15,15 @@
  * @var PhpRenderer $this
  * @var string $className The new migration class name without namespace.
  * @var string $namespace The new migration class namespace.
+ * @var bool|null $transactional Whether the migration uses transactions. `null` keeps the template default.
  * @var string $table The table name.
  * @var string $tableComment The table comment.
  * @var Column[] $columns Fields.
  * @var ForeignKey[] $foreignKeys Foreign keys.
  */
 
+$transactional ??= true;
+
 echo "<?php\n";
 
 echo "\ndeclare(strict_types=1);\n";
@@ -32,15 +35,19 @@
 
 use Yiisoft\Db\Migration\MigrationBuilder;
 use Yiisoft\Db\Migration\RevertibleMigrationInterface;
+<?php if ($transactional): ?>
 use Yiisoft\Db\Migration\TransactionalMigrationInterface;
+<?php endif; ?>
 
 /**
  * Handles the creation of table `<?= $table ?>`.
 <?= $this->render(__DIR__ . '/_foreignTables.php', [
     'foreignKeys' => $foreignKeys,
 ]) ?>
  */
-final class <?= $className ?> implements RevertibleMigrationInterface, TransactionalMigrationInterface
+final class <?= $className ?> implements RevertibleMigrationInterface<?=
+    $transactional ? ", TransactionalMigrationInterface\n" : "\n"
+?>
 {
     public function up(MigrationBuilder $b): void
     {

resources/views/dropColumnMigration.php

@@ -15,11 +15,14 @@
  * @var PhpRenderer $this
  * @var string $className The new migration class name without namespace.
  * @var string $namespace The new migration class namespace.
+ * @var bool|null $transactional Whether the migration uses transactions. `null` keeps the template default.
  * @var string $table The table name.
  * @var Column[] $columns Fields.
  * @var ForeignKey[] $foreignKeys Foreign keys.
  */
 
+$transactional ??= false;
+
 echo "<?php\n";
 
 echo "\ndeclare(strict_types=1);\n";
@@ -31,14 +34,19 @@
 
 use Yiisoft\Db\Migration\MigrationBuilder;
 use Yiisoft\Db\Migration\RevertibleMigrationInterface;
+<?php if ($transactional): ?>
+use Yiisoft\Db\Migration\TransactionalMigrationInterface;
+<?php endif; ?>
 
 /**
  * Handles dropping columns from table `<?= $table ?>`.
 <?= $this->render(__DIR__ . '/_foreignTables.php', [
     'foreignKeys' => $foreignKeys,
 ]) ?>
  */
-final class <?= $className ?> implements RevertibleMigrationInterface
+final class <?= $className ?> implements RevertibleMigrationInterface<?=
+    $transactional ? ", TransactionalMigrationInterface\n" : "\n"
+?>
 {
     public function up(MigrationBuilder $b): void
     {

resources/views/dropTableMigration.php

@@ -15,11 +15,14 @@
  * @var PhpRenderer $this
  * @var string $className The new migration class name without namespace.
  * @var string $namespace The new migration class namespace.
+ * @var bool|null $transactional Whether the migration uses transactions. `null` keeps the template default.
  * @var string $table The table name.
  * @var Column[] $columns Fields.
  * @var ForeignKey[] $foreignKeys Foreign keys.
  */
 
+$transactional ??= false;
+
 echo "<?php\n";
 
 echo "\ndeclare(strict_types=1);\n";
@@ -31,14 +34,19 @@
 
 use Yiisoft\Db\Migration\MigrationBuilder;
 use Yiisoft\Db\Migration\RevertibleMigrationInterface;
+<?php if ($transactional): ?>
+use Yiisoft\Db\Migration\TransactionalMigrationInterface;
+<?php endif; ?>
 
 /**
  * Handles the dropping of table `<?= $table ?>`.
 <?= $this->render(__DIR__ . '/_foreignTables.php', [
     'foreignKeys' => $foreignKeys,
 ]) ?>
  */
-final class <?= $className ?> implements RevertibleMigrationInterface
+final class <?= $className ?> implements RevertibleMigrationInterface<?=
+    $transactional ? ", TransactionalMigrationInterface\n" : "\n"
+?>
 {
     public function up(MigrationBuilder $b): void
     {

resources/views/migration.php

@@ -13,8 +13,11 @@
  * @var PhpRenderer $this
  * @var string $className The new migration class name without namespace.
  * @var string $namespace The new migration class namespace.
+ * @var bool|null $transactional Whether the migration uses transactions. `null` keeps the template default.
  */
 
+$transactional ??= false;
+
 echo "<?php\n";
 
 echo "\ndeclare(strict_types=1);\n";
@@ -26,8 +29,13 @@
 
 use Yiisoft\Db\Migration\MigrationBuilder;
 use Yiisoft\Db\Migration\RevertibleMigrationInterface;
+<?php if ($transactional): ?>
+use Yiisoft\Db\Migration\TransactionalMigrationInterface;
+<?php endif; ?>
 
-final class <?= $className ?> implements RevertibleMigrationInterface
+final class <?= $className ?> implements RevertibleMigrationInterface<?=
+    $transactional ? ", TransactionalMigrationInterface\n" : "\n"
+?>
 {
     public function up(MigrationBuilder $b): void
     {