Resolve merge conflict with 5.x branch

Accepted the 5.x branch's documentation for insertOrUpdate() and insertOrSkip()
which has the correct three-argument API signature.

Author: dereuromark

README.md

@@ -1,7 +1,7 @@
 # Migrations plugin for CakePHP
 
 [![CI](https://github.com/cakephp/migrations/actions/workflows/ci.yml/badge.svg)](https://github.com/cakephp/migrations/actions/workflows/ci.yml)
-[![Coverage Status](https://img.shields.io/codecov/c/github/cakephp/migrations/3.x.svg?style=flat-square)](https://app.codecov.io/github/cakephp/migrations/tree/3.x)
+[![Coverage Status](https://img.shields.io/codecov/c/github/cakephp/migrations/5.x.svg?style=flat-square)](https://app.codecov.io/github/cakephp/migrations/tree/5.x)
 [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.txt)
 [![Total Downloads](https://img.shields.io/packagist/dt/cakephp/migrations.svg?style=flat-square)](https://packagist.org/packages/cakephp/migrations)
 

composer.json

@@ -46,8 +46,10 @@
     },
     "autoload-dev": {
         "psr-4": {
+            "Blog\\": "tests/test_app/Plugin/Blog/src/",
             "Cake\\Test\\": "./vendor/cakephp/cakephp/tests/",
             "Migrations\\Test\\": "tests/",
+            "Migrator\\": "tests/test_app/Plugin/Migrator/src/",
             "SimpleSnapshot\\": "tests/test_app/Plugin/SimpleSnapshot/src/",
             "TestApp\\": "tests/test_app/App/",
             "TestBlog\\": "tests/test_app/Plugin/TestBlog/src/",

docs/en/seeding.rst

@@ -450,87 +450,88 @@ within your seed class and then use the ``insert()`` method to insert data:
     You must call the ``saveData()`` method to commit your data to the table.
     Migrations will buffer data until you do so.
 
-Upserting Data
---------------
+Insert Modes
+============
+
+In addition to the standard ``insert()`` method, Migrations provides specialized
+insert methods for handling conflicts with existing data.
 
-.. versionadded:: 5.0.0
-    ``insertOrUpdate()`` and ``insertOrSkip()`` were added in 5.0.0.
+Insert or Skip
+--------------
 
-For seeds that may be run multiple times, you can use ``insertOrUpdate()`` to insert
-new records or update existing ones based on conflict columns. This is particularly
-useful for configuration or reference data that should always reflect certain values:
+The ``insertOrSkip()`` method inserts rows but silently skips any that would
+violate a unique constraint:
 
 .. code-block:: php
 
     <?php
 
     use Migrations\BaseSeed;
 
-    class ConfigSeed extends BaseSeed
+    class CurrencySeed extends BaseSeed
     {
         public function run(): void
         {
             $data = [
-                [
-                    'key' => 'site_name',
-                    'value' => 'My Application',
-                ],
-                [
-                    'key' => 'maintenance_mode',
-                    'value' => 'false',
-                ],
+                ['code' => 'USD', 'name' => 'US Dollar'],
+                ['code' => 'EUR', 'name' => 'Euro'],
             ];
 
-            $settings = $this->table('settings');
-            // For PostgreSQL and SQLite, you must specify the conflict column(s)
-            $settings->insertOrUpdate($data, ['key'])
-                     ->saveData();
-
-            // For MySQL, conflict columns are optional (uses all unique constraints)
-            // $settings->insertOrUpdate($data)->saveData();
+            $this->table('currencies')
+                ->insertOrSkip($data)
+                ->saveData();
         }
     }
 
-.. note::
-
-    The ``$conflictColumns`` parameter behavior differs by database:
+Insert or Update (Upsert)
+-------------------------
 
-    - **MySQL**: The parameter is ignored because MySQL's ``ON DUPLICATE KEY UPDATE``
-      automatically applies to all unique constraints.
-    - **PostgreSQL/SQLite**: The parameter is required and specifies which column(s)
-      to use for conflict detection.
-
-Insert or Skip
-~~~~~~~~~~~~~~
-
-If you want to insert records only when they don't already exist (without updating),
-use the ``insertOrSkip()`` method:
+The ``insertOrUpdate()`` method performs an "upsert" operation - inserting new
+rows and updating existing rows that conflict on unique columns:
 
 .. code-block:: php
 
     <?php
 
     use Migrations\BaseSeed;
 
-    class DefaultRolesSeed extends BaseSeed
+    class ExchangeRateSeed extends BaseSeed
     {
         public function run(): void
         {
             $data = [
-                ['name' => 'admin', 'description' => 'Administrator'],
-                ['name' => 'user', 'description' => 'Regular User'],
-                ['name' => 'guest', 'description' => 'Guest User'],
+                ['code' => 'USD', 'rate' => 1.0000],
+                ['code' => 'EUR', 'rate' => 0.9234],
             ];
 
-            $roles = $this->table('roles');
-            // Skip inserting if a role with the same name already exists
-            $roles->insertOrSkip($data, ['name'])
-                  ->saveData();
+            $this->table('exchange_rates')
+                ->insertOrUpdate($data, ['rate'], ['code'])
+                ->saveData();
         }
     }
 
-This is useful for seeding default data that should not overwrite any customizations
-made by users.
+The method takes three arguments:
+
+- ``$data``: The rows to insert (same format as ``insert()``)
+- ``$updateColumns``: Which columns to update when a conflict occurs
+- ``$conflictColumns``: Which columns define uniqueness (must have a unique index)
+
+.. warning::
+
+    Database-specific behavior differences:
+
+    **MySQL**: Uses ``ON DUPLICATE KEY UPDATE``. The ``$conflictColumns`` parameter
+    is ignored because MySQL automatically applies the update to *all* unique
+    constraint violations on the table. Passing ``$conflictColumns`` will trigger
+    a warning. If your table has multiple unique constraints, be aware that a
+    conflict on *any* of them will trigger the update.
+
+    **PostgreSQL/SQLite**: Uses ``ON CONFLICT (...) DO UPDATE SET``. The
+    ``$conflictColumns`` parameter is required and specifies exactly which unique
+    constraint should trigger the update. A ``RuntimeException`` will be thrown
+    if this parameter is empty.
+
+    **SQL Server**: Not currently supported. Use separate insert/update logic.
 
 Truncating Tables
 =================

docs/en/writing-migrations.rst

@@ -2381,3 +2381,76 @@ Changing templates
 
 See :ref:`custom-seed-migration-templates` for how to customize the templates
 used to generate migrations.
+
+Database-Specific Limitations
+=============================
+
+While Migrations aims to provide a database-agnostic API, some features have
+database-specific limitations or are not available on all platforms.
+
+SQL Server
+----------
+
+The following features are not supported on SQL Server:
+
+**Check Constraints**
+
+Check constraints are not currently implemented for SQL Server. Attempting to
+use ``addCheckConstraint()`` or ``dropCheckConstraint()`` will throw a
+``BadMethodCallException``.
+
+**Table Comments**
+
+SQL Server does not support table comments. Attempting to use ``changeComment()``
+will throw a ``BadMethodCallException``.
+
+**INSERT IGNORE / insertOrSkip()**
+
+SQL Server does not support the ``INSERT IGNORE`` syntax used by ``insertOrSkip()``.
+This method will throw a ``RuntimeException`` on SQL Server. Use ``insertOrUpdate()``
+instead for upsert operations, which uses ``MERGE`` statements on SQL Server.
+
+SQLite
+------
+
+**Foreign Key Names**
+
+SQLite does not support named foreign keys. The foreign key constraint name option
+is ignored when creating foreign keys on SQLite.
+
+**Table Comments**
+
+SQLite does not support table comments directly. Comments are stored as metadata
+but not in the database itself.
+
+**Check Constraint Modifications**
+
+SQLite does not support ``ALTER TABLE`` operations for check constraints. Adding or
+dropping check constraints requires recreating the entire table, which is handled
+automatically by the adapter.
+
+**Table Partitioning**
+
+SQLite does not support table partitioning.
+
+PostgreSQL
+----------
+
+**KEY Partitioning**
+
+PostgreSQL does not support MySQL's ``KEY`` partitioning type. Use ``HASH``
+partitioning instead for similar distribution behavior.
+
+MySQL/MariaDB
+-------------
+
+**insertOrUpdate() Conflict Columns**
+
+For MySQL, the ``$conflictColumns`` parameter in ``insertOrUpdate()`` is ignored
+because MySQL's ``ON DUPLICATE KEY UPDATE`` automatically applies to all unique
+constraints. PostgreSQL and SQLite require this parameter to be specified.
+
+**MariaDB GIS/Geometry**
+
+Some geometry column features may not work correctly on MariaDB due to differences
+in GIS implementation compared to MySQL.

phpstan-baseline.neon

@@ -1,23 +1,5 @@
 parameters:
 	ignoreErrors:
-		-
-			message: '#^Call to an undefined method object\:\:loadHelper\(\)\.$#'
-			identifier: method.notFound
-			count: 1
-			path: src/Command/BakeMigrationCommand.php
-
-		-
-			message: '#^Call to an undefined method object\:\:loadHelper\(\)\.$#'
-			identifier: method.notFound
-			count: 1
-			path: src/Command/BakeMigrationDiffCommand.php
-
-		-
-			message: '#^Call to an undefined method object\:\:loadHelper\(\)\.$#'
-			identifier: method.notFound
-			count: 1
-			path: src/Command/BakeMigrationSnapshotCommand.php
-
 		-
 			message: '#^PHPDoc tag @var with type string is not subtype of native type non\-falsy\-string\|true\.$#'
 			identifier: varTag.nativeType

src/Command/BakeMigrationCommand.php

@@ -48,7 +48,9 @@ public static function defaultName(): string
     public function bake(string $name, Arguments $args, ConsoleIo $io): void
     {
         EventManager::instance()->on('Bake.initialize', function (Event $event): void {
-            $event->getSubject()->loadHelper('Migrations.Migration');
+            /** @var \Bake\View\BakeView $view */
+            $view = $event->getSubject();
+            $view->loadHelper('Migrations.Migration');
         });
         $this->_name = $name;
 

src/Command/BakeMigrationDiffCommand.php

@@ -128,7 +128,9 @@ public function bake(string $name, Arguments $args, ConsoleIo $io): void
         assert($connection instanceof Connection);
 
         EventManager::instance()->on('Bake.initialize', function (Event $event) use ($collection, $connection): void {
-            $event->getSubject()->loadHelper('Migrations.Migration', [
+            /** @var \Bake\View\BakeView $view */
+            $view = $event->getSubject();
+            $view->loadHelper('Migrations.Migration', [
                 'collection' => $collection,
                 'connection' => $connection,
             ]);

src/Command/BakeMigrationSnapshotCommand.php

@@ -59,7 +59,9 @@ public function bake(string $name, Arguments $args, ConsoleIo $io): void
         assert($connection instanceof Connection);
 
         EventManager::instance()->on('Bake.initialize', function (Event $event) use ($collection, $connection): void {
-            $event->getSubject()->loadHelper('Migrations.Migration', [
+            /** @var \Bake\View\BakeView $view */
+            $view = $event->getSubject();
+            $view->loadHelper('Migrations.Migration', [
                 'collection' => $collection,
                 'connection' => $connection,
             ]);

src/Db/Adapter/AbstractAdapter.php

@@ -730,6 +730,10 @@ protected function getInsertPrefix(?InsertMode $mode = null): string
     /**
      * Get the upsert clause for MySQL (ON DUPLICATE KEY UPDATE).
      *
+     * MySQL's ON DUPLICATE KEY UPDATE applies to all unique key constraints on the table,
+     * so the $conflictColumns parameter is not used. If you pass conflictColumns when using
+     * MySQL, a warning will be triggered.
+     *
      * @param \Migrations\Db\InsertMode|null $mode Insert mode
      * @param array<string>|null $updateColumns Columns to update on conflict
      * @param array<string>|null $conflictColumns Columns that define uniqueness (unused in MySQL)
@@ -741,6 +745,14 @@ protected function getUpsertClause(?InsertMode $mode, ?array $updateColumns, ?ar
             return '';
         }
 
+        if ($conflictColumns !== null) {
+            trigger_error(
+                'The $conflictColumns parameter is ignored by MySQL. ' .
+                'MySQL\'s ON DUPLICATE KEY UPDATE applies to all unique constraints on the table.',
+                E_USER_WARNING,
+            );
+        }
+
         $updates = [];
         foreach ($updateColumns as $column) {
             $quotedColumn = $this->quoteColumnName($column);

src/Db/Adapter/PostgresAdapter.php

@@ -1288,10 +1288,15 @@ public function bulkinsert(
     /**
      * Get the ON CONFLICT clause based on insert mode.
      *
+     * PostgreSQL requires explicit conflict columns to determine which unique constraint
+     * should trigger the update. Unlike MySQL's ON DUPLICATE KEY UPDATE which applies
+     * to all unique constraints, PostgreSQL's ON CONFLICT clause must specify the columns.
+     *
      * @param \Migrations\Db\InsertMode|null $mode Insert mode
      * @param array<string>|null $updateColumns Columns to update on upsert conflict
-     * @param array<string>|null $conflictColumns Columns that define uniqueness for upsert
+     * @param array<string>|null $conflictColumns Columns that define uniqueness for upsert (required for PostgreSQL)
      * @return string
+     * @throws \RuntimeException When using UPSERT mode without conflictColumns
      */
     protected function getConflictClause(
         ?InsertMode $mode = null,
@@ -1302,7 +1307,13 @@ protected function getConflictClause(
             return ' ON CONFLICT DO NOTHING';
         }
 
-        if ($mode === InsertMode::UPSERT && $updateColumns !== null && $conflictColumns !== null) {
+        if ($mode === InsertMode::UPSERT) {
+            if ($conflictColumns === null || $conflictColumns === []) {
+                throw new RuntimeException(
+                    'PostgreSQL requires the $conflictColumns parameter for insertOrUpdate(). ' .
+                    'Specify the columns that have a unique constraint to determine conflict resolution.',
+                );
+            }
             $quotedConflictColumns = array_map($this->quoteColumnName(...), $conflictColumns);
             $updates = [];
             foreach ($updateColumns as $column) {