diff --git a/README.md b/README.md index e7977860..7d4bacbf 100644 --- a/README.md +++ b/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) diff --git a/docs/en/writing-migrations.rst b/docs/en/writing-migrations.rst index 81c7df08..002a1705 100644 --- a/docs/en/writing-migrations.rst +++ b/docs/en/writing-migrations.rst @@ -2315,3 +2315,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. diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index 36133770..2cda39ed 100644 --- a/phpstan-baseline.neon +++ b/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 diff --git a/src/Command/BakeMigrationCommand.php b/src/Command/BakeMigrationCommand.php index dd0e7683..c727b03e 100644 --- a/src/Command/BakeMigrationCommand.php +++ b/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; diff --git a/src/Command/BakeMigrationDiffCommand.php b/src/Command/BakeMigrationDiffCommand.php index 06a3c72c..cb3ad01e 100644 --- a/src/Command/BakeMigrationDiffCommand.php +++ b/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, ]); diff --git a/src/Command/BakeMigrationSnapshotCommand.php b/src/Command/BakeMigrationSnapshotCommand.php index aec3ef04..259b62bf 100644 --- a/src/Command/BakeMigrationSnapshotCommand.php +++ b/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, ]); diff --git a/src/View/Helper/MigrationHelper.php b/src/View/Helper/MigrationHelper.php index 114de108..cb171ed4 100644 --- a/src/View/Helper/MigrationHelper.php +++ b/src/View/Helper/MigrationHelper.php @@ -418,13 +418,14 @@ public function getColumnOption(array $options): array unset($columnOptions['collate']); } - // TODO deprecate precision/scale and align with cakephp/database in 5.x - // TODO this can be cleaned up when we stop using phinx data structures for column definitions + // Handle precision/scale conversion between CakePHP's TableSchema format and SQL standard format. + // TableSchema uses: length=total digits, precision=decimal places + // Migrations uses SQL standard: precision=total digits, scale=decimal places if (!isset($columnOptions['precision']) || $columnOptions['precision'] == null) { unset($columnOptions['precision']); } else { - // due to Phinx using different naming for the precision and scale to CakePHP - // Only convert precision to scale if scale is not already set (for decimal columns from diff) + // Convert CakePHP's precision (decimal places) to Migrations' scale + // Only convert if scale is not already set (for decimal columns from diff) if (!isset($columnOptions['scale'])) { $columnOptions['scale'] = $columnOptions['precision']; }