From 6c21ebc211ff684a2c8bd9ee5ebefb201cc01a65 Mon Sep 17 00:00:00 2001
From: Sergei Predvoditelev <sergei@predvoditelev.ru>
Date: Wed, 29 Apr 2026 14:04:50 +0300
Subject: [PATCH 1/2] Add `MigrationBuilder::insertBatch()` method, deprecate
 `batchInsert()`

---
 CHANGELOG.md                                  |  1 +
 src/MigrationBuilder.php                      | 26 ++++++++++++++++-
 tests/Common/AbstractMigrationBuilderTest.php | 28 +++++++++++++++++++
 3 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e329e89..ae6032ea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## 2.0.2 under development
 
+- New #332: Add `MigrationBuilder::insertBatch()` method, deprecate `batchInsert()` (@vjik)
 - Enh #317: Explicitly import classes, functions, and constants in "use" section (@mspirkov)
 - Enh #318: Remove unnecessary files from Composer package (@mspirkov)
 - Enh #319: Remove confirmation prompt from `migrate:create` command as creating a migration is non-destructive (@samdark)
diff --git a/src/MigrationBuilder.php b/src/MigrationBuilder.php
index 24e5abc3..f21dc4c6 100644
--- a/src/MigrationBuilder.php
+++ b/src/MigrationBuilder.php
@@ -101,6 +101,28 @@ public function insert(string $table, array $columns): void
         $this->endCommand($time);
     }
 
+    /**
+     * Creates and executes a batch INSERT SQL statement.
+     *
+     * The method will properly escape the column names and bind the values to be inserted.
+     *
+     * @param string $table The table that new rows will be inserted into.
+     * @param iterable $rows The rows to be batch inserted into the table.
+     * @param array $columns The column names.
+     *
+     * @psalm-param iterable<iterable<array-key, mixed>> $rows
+     *
+     * @throws Exception
+     * @throws InvalidConfigException
+     * @throws NotSupportedException
+     */
+    public function insertBatch(string $table, iterable $rows, array $columns = []): void
+    {
+        $time = $this->beginCommand("Insert into $table");
+        $this->db->createCommand()->insertBatch($table, $rows, $columns)->execute();
+        $this->endCommand($time);
+    }
+
     /**
      * Creates and executes a batch INSERT SQL statement.
      *
@@ -108,13 +130,15 @@ public function insert(string $table, array $columns): void
      *
      * @param string $table The table that new rows will be inserted into.
      * @param string[] $columns The column names.
-     * @param iterable $rows The rows to be batch inserted into the table
+     * @param iterable $rows The rows to be batch inserted into the table.
      *
      * @psalm-param iterable<iterable<array-key, mixed>> $rows
      *
      * @throws Exception
      * @throws InvalidConfigException
      * @throws NotSupportedException
+     *
+     * @deprecated Use {@see insertBatch()} instead.
      */
     public function batchInsert(string $table, array $columns, iterable $rows): void
     {
diff --git a/tests/Common/AbstractMigrationBuilderTest.php b/tests/Common/AbstractMigrationBuilderTest.php
index 1c83168d..214cc892 100644
--- a/tests/Common/AbstractMigrationBuilderTest.php
+++ b/tests/Common/AbstractMigrationBuilderTest.php
@@ -59,6 +59,34 @@ public function testInsert(): void
         $this->builder->dropTable('test');
     }
 
+    public function testInsertBatch(): void
+    {
+        $this->builder->createTable('test', ['id' => ColumnBuilder::integer()]);
+        $this->builder->insertBatch('test', [['id' => 1], ['id' => 2]]);
+
+        $this->assertEquals(
+            '2',
+            $this->db->createCommand('SELECT count(*) FROM {{test}} WHERE [[id]] IN (1, 2)')->queryScalar(),
+        );
+        $this->assertInformerOutputContains('    > Insert into test ... Done in ');
+
+        $this->builder->dropTable('test');
+    }
+
+    public function testInsertBatchWithColumns(): void
+    {
+        $this->builder->createTable('test', ['id' => ColumnBuilder::integer()]);
+        $this->builder->insertBatch('test', [[1], [2]], ['id']);
+
+        $this->assertEquals(
+            '2',
+            $this->db->createCommand('SELECT count(*) FROM {{test}} WHERE [[id]] IN (1, 2)')->queryScalar(),
+        );
+        $this->assertInformerOutputContains('    > Insert into test ... Done in ');
+
+        $this->builder->dropTable('test');
+    }
+
     public function testBatchInsert(): void
     {
         $this->builder->createTable('test', ['id' => ColumnBuilder::integer()]);

From 0ce05e4606f1f894135d21fe80b8e90e9c4977b6 Mon Sep 17 00:00:00 2001
From: Sergei Predvoditelev <sergei@predvoditelev.ru>
Date: Wed, 29 Apr 2026 14:07:59 +0300
Subject: [PATCH 2/2] fix psalm

---
 src/MigrationBuilder.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/MigrationBuilder.php b/src/MigrationBuilder.php
index f21dc4c6..a1764b89 100644
--- a/src/MigrationBuilder.php
+++ b/src/MigrationBuilder.php
@@ -108,7 +108,7 @@ public function insert(string $table, array $columns): void
      *
      * @param string $table The table that new rows will be inserted into.
      * @param iterable $rows The rows to be batch inserted into the table.
-     * @param array $columns The column names.
+     * @param string[] $columns The column names.
      *
      * @psalm-param iterable<iterable<array-key, mixed>> $rows
      *