Merge branch '4.3.x' into 5.0.x

Author: morozov

UPGRADE.md

@@ -230,6 +230,25 @@ all drivers and middleware.
 
 # Upgrade to 4.3
 
+## Deprecated features related to primary key constraints
+
+1. The `AbstractPlatform::getCreatePrimaryKeySQL()` method has been deprecated. Use the schema manager to create and
+   alter tables.
+2. Building the SQL for dropping a primary key constraint via `PostgreSQLPlatform::getDropIndexSQL()` has been
+   deprecated. Use `PostgreSQLPlatform::getDropConstraintSQL()` instead.
+3. Using the `Index` class to represent a primary key constraint has been deprecated, including:
+   - Passing `true` as the `$isPrimary` constructor argument.
+   - Using the `$_isPrimary` property and the `isPrimary()` method.
+
+   Use the `PrimaryKeyConstraint` class to represent a primary key constraint instead.
+
+4. The following features of the `Table` class have been deprecated:
+   - The `Table::getPrimaryKey()` method. Use `Table::getPrimaryKeyConstraint()` instead.
+   - The `Table::setPrimaryKey()` method. Instead, pass the `$primaryKeyConstraint` argument to the constructor or add
+      the constraint via `Table::addPrimaryKeyConstraint()`.
+   - Using `Table::renameIndex()` to rename the primary key constraint. Use `Table::dropPrimaryKey()` and
+      `Table::addPrimaryKeyConstraint()` instead.
+
 ## Deprecated invalid auto-increment column definitions on SQLite
 
 The following auto-increment column definitions are deprecated in SQLite:

src/Platforms/AbstractMySQLPlatform.php

@@ -249,7 +249,7 @@ protected function _getCreateTableSQL(OptionallyQualifiedName $tableName, array
 
         if (isset($parameters['primary_index'])) {
             $elements[] = sprintf(
-                'PRIMARY KEY(%s)',
+                'PRIMARY KEY (%s)',
                 implode(', ', $parameters['primary_index']->getQuotedColumns($this)),
             );
         }

src/Platforms/AbstractPlatform.php

@@ -42,6 +42,7 @@
 use Doctrine\DBAL\Types\Exception\TypeNotFound;
 use Doctrine\DBAL\Types\Exception\TypesException;
 use Doctrine\DBAL\Types\Type;
+use Doctrine\Deprecations\Deprecation;
 
 use function addcslashes;
 use function array_map;
@@ -996,7 +997,7 @@ protected function _getCreateTableSQL(OptionallyQualifiedName $tableName, array
 
         if (isset($parameters['primary_index'])) {
             $elements[] = sprintf(
-                'PRIMARY KEY(%s)',
+                'PRIMARY KEY (%s)',
                 implode(', ', $parameters['primary_index']->getQuotedColumns($this)),
             );
         }
@@ -1145,9 +1146,18 @@ protected function getCreateIndexSQLFlags(Index $index): string
 
     /**
      * Returns the SQL to create an unnamed primary key constraint.
+     *
+     * @deprecated
      */
     public function getCreatePrimaryKeySQL(Index $index, string $table): string
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6867',
+            '%s() is deprecated.',
+            __METHOD__,
+        );
+
         return 'ALTER TABLE ' . $table . ' ADD PRIMARY KEY (' . implode(', ', $index->getQuotedColumns($this)) . ')';
     }
 

src/Platforms/OraclePlatform.php

@@ -22,6 +22,7 @@
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types\BinaryType;
 use Doctrine\DBAL\Types\Types;
+use Doctrine\Deprecations\Deprecation;
 use InvalidArgumentException;
 
 use function array_merge;
@@ -131,8 +132,16 @@ public function getBitOrComparisonExpression(string $value1, string $value2): st
                 . '+' . $value2 . ')';
     }
 
+    /** @deprecated */
     public function getCreatePrimaryKeySQL(Index $index, string $table): string
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6867',
+            '%s() is deprecated.',
+            __METHOD__,
+        );
+
         return 'ALTER TABLE ' . $table . ' ADD CONSTRAINT ' . $index->getObjectName()->toSQL($this)
             . ' PRIMARY KEY (' . implode(', ', $index->getQuotedColumns($this)) . ')';
     }

src/Platforms/PostgreSQLPlatform.php

@@ -17,6 +17,7 @@
 use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types\Types;
+use Doctrine\Deprecations\Deprecation;
 use UnexpectedValueException;
 
 use function array_merge;
@@ -363,6 +364,14 @@ public function getDropIndexSQL(string $name, string $table): string
         }
 
         if ($name === '"primary"' || $name === $primaryKeyName) {
+            Deprecation::triggerIfCalledFromOutside(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/6867',
+                'Building the SQL for dropping primary key constraint via %s() is deprecated. Use'
+                    . ' getDropConstraintSQL() instead.',
+                __METHOD__,
+            );
+
             return $this->getDropConstraintSQL($primaryKeyName, $table);
         }
 
@@ -387,7 +396,7 @@ protected function _getCreateTableSQL(OptionallyQualifiedName $tableName, array
 
         if (isset($parameters['primary_index'])) {
             $elements[] = sprintf(
-                'PRIMARY KEY(%s)',
+                'PRIMARY KEY (%s)',
                 implode(', ', $parameters['primary_index']->getQuotedColumns($this)),
             );
         }

src/Platforms/SQLServerPlatform.php

@@ -22,6 +22,7 @@
 use Doctrine\DBAL\SQL\Builder\SelectSQLBuilder;
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types\Types;
+use Doctrine\Deprecations\Deprecation;
 use InvalidArgumentException;
 
 use function array_map;
@@ -249,8 +250,16 @@ protected function _getCreateTableSQL(OptionallyQualifiedName $tableName, array
         return array_merge($sql, $commentsSql, $defaultConstraintsSql);
     }
 
+    /** @deprecated */
     public function getCreatePrimaryKeySQL(Index $index, string $table): string
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6867',
+            '%s() is deprecated.',
+            __METHOD__,
+        );
+
         $sql = 'ALTER TABLE ' . $table . ' ADD PRIMARY KEY';
 
         if ($index->hasFlag('nonclustered')) {

src/Platforms/SQLitePlatform.php

@@ -285,7 +285,7 @@ protected function _getCreateTableSQL(OptionallyQualifiedName $tableName, array
             $primaryKeyColumns = $parameters['primary_index']->getQuotedColumns($this);
 
             $elements[] = sprintf(
-                'PRIMARY KEY(%s)',
+                'PRIMARY KEY (%s)',
                 implode(', ', $primaryKeyColumns),
             );
         }
@@ -588,6 +588,7 @@ public function getDropTablesSQL(array $tables): array
         return $sql;
     }
 
+    /** @deprecated */
     public function getCreatePrimaryKeySQL(Index $index, string $table): string
     {
         throw NotSupported::new(__METHOD__);

src/Schema/Exception/InvalidPrimaryKeyConstraintDefinition.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Schema\Exception;
+
+use Doctrine\DBAL\Schema\SchemaException;
+use LogicException;
+
+final class InvalidPrimaryKeyConstraintDefinition extends LogicException implements SchemaException
+{
+    public static function columnNamesNotSet(): self
+    {
+        return new self('Primary key constraint column names are not set.');
+    }
+}

src/Schema/Exception/InvalidState.php

@@ -7,6 +7,12 @@
 use Doctrine\DBAL\Schema\SchemaException;
 use LogicException;
 
+use function sprintf;
+
 final class InvalidState extends LogicException implements SchemaException
 {
+    public static function tableHasInvalidPrimaryKeyConstraint(string $tableName): self
+    {
+        return new self(sprintf('Table "%s" has invalid primary key constraint.', $tableName));
+    }
 }

src/Schema/Index.php

@@ -12,6 +12,7 @@
 use Doctrine\DBAL\Schema\Name\Parser\UnqualifiedNameParser;
 use Doctrine\DBAL\Schema\Name\Parsers;
 use Doctrine\DBAL\Schema\Name\UnqualifiedName;
+use Doctrine\Deprecations\Deprecation;
 
 use function array_filter;
 use function array_keys;
@@ -34,6 +35,7 @@ final class Index extends AbstractNamedObject
 
     private readonly bool $_isUnique;
 
+    /** @deprecated Use {@see PrimaryKeyConstraint()} instead. */
     private readonly bool $_isPrimary;
 
     /**
@@ -69,6 +71,14 @@ public function __construct(
             throw InvalidIndexDefinition::columnNamesNotSet();
         }
 
+        if ($isPrimary) {
+            Deprecation::triggerIfCalledFromOutside(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/6867',
+                'Declaring an index as primary is deprecated. Use PrimaryKeyConstraint instead.',
+            );
+        }
+
         $this->_isUnique  = $isUnique || $isPrimary;
         $this->_isPrimary = $isPrimary;
 
@@ -144,7 +154,7 @@ public function getQuotedColumns(AbstractPlatform $platform): array
         return $columns;
     }
 
-    /** @return array<int, string> */
+    /** @return non-empty-list<string> */
     public function getUnquotedColumns(): array
     {
         return array_map($this->trimQuotes(...), $this->getColumns());
@@ -163,8 +173,15 @@ public function isUnique(): bool
         return $this->_isUnique;
     }
 
+    /** @deprecated Use {@see PrimaryKeyConstraint()} instead. */
     public function isPrimary(): bool
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6867',
+            'Checking whether an index is primary is deprecated. Use PrimaryKeyConstraint instead.',
+        );
+
         return $this->_isPrimary;
     }