Deprecated usage of DB-generated UUIDs

doctrine · Jul 11, 2018 · 8396913 · 8396913
1 parent 29f1799
commit 8396913
Show file tree

Hide file tree

Showing 12 changed files with 75 additions and 9 deletions.
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,5 +1,13 @@
 # Upgrade to 2.8
 
+## Deprecated usage of DB-generated UUIDs
+
+The format of DB-generated UUIDs is inconsistent across supported platforms and therefore is not portable. Some of the platforms produce UUIDv1, some produce UUIDv4, some produce the values which are not even UUID.
+
+Unless UUIDs are used in stored procedures which DBAL doesn't support, there's no real benefit of DB-generated UUIDs comparing to the application-generated ones.
+
+Use a PHP library (e.g. [ramsey/uuid](https://packagist.org/packages/ramsey/uuid)) to generate UUIDs on the application side.
+
 ## Deprecated usage of binary fields whose length exceeds the platform maximum
 
 - The usage of binary fields whose length exceeds the maximum field size on a given platform is deprecated.

diff --git a/docs/en/reference/sharding.rst b/docs/en/reference/sharding.rst
@@ -100,11 +100,15 @@ platforms:
 
     <?php
     use Doctrine\DBAL\DriverManager;
+    use Ramsey\Uuid\Uuid;
 
     $conn = DriverManager::getConnection(/**..**/);
-    $guid = $conn->fetchColumn('SELECT ' . $conn->getDatabasePlatform()->getGuidExpression());
+    $guid = Uuid::uuid1();
 
-    $conn->insert("my_table", array("id" => $guid, "foo" => "bar"));
+    $conn->insert('my_table', [
+        'id'  => $guid->toString(),
+        'foo' => 'bar',
+    ]);
 
 In your application you should hide this details in Id-Generation services:
 
@@ -113,15 +117,13 @@ In your application you should hide this details in Id-Generation services:
     <?php
     namespace MyApplication;
 
+    use Ramsey\Uuid\Uuid;
+
     class IdGenerationService
     {
-        private $conn;
-
-        public function generateCustomerId()
+        public function generateCustomerId() : Uuid
         {
-            return $this->conn->fetchColumn('SELECT ' .
-                $this->conn->getDatabasePlatform()->getGuidExpression()
-            );
+            return Uuid::uuid1();
         }
     }
 

diff --git a/lib/Doctrine/DBAL/Platforms/AbstractPlatform.php b/lib/Doctrine/DBAL/Platforms/AbstractPlatform.php
@@ -686,9 +686,13 @@ public function getRegexpExpression()
      * @return string
      *
      * @throws \Doctrine\DBAL\DBALException If not supported on this platform.
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
+        @trigger_error(__METHOD__ . '() is deprecated, use application-generated UUIDs instead.', E_USER_DEPRECATED);
+
         throw DBALException::notSupported(__METHOD__);
     }
 

diff --git a/lib/Doctrine/DBAL/Platforms/DrizzlePlatform.php b/lib/Doctrine/DBAL/Platforms/DrizzlePlatform.php
@@ -24,6 +24,7 @@
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\Types\BinaryType;
+use const E_USER_DEPRECATED;
 use function array_merge;
 use function array_unique;
 use function array_values;
@@ -36,6 +37,7 @@
 use function is_string;
 use function join;
 use function sprintf;
+use function trigger_error;
 use function trim;
 
 /**
@@ -621,9 +623,13 @@ public function getLocateExpression($str, $substr, $startPos = false)
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
+        @trigger_error(__METHOD__ . '() is deprecated, use application-generated UUIDs instead.', E_USER_DEPRECATED);
+
         return 'UUID()';
     }
 

diff --git a/lib/Doctrine/DBAL/Platforms/MySqlPlatform.php b/lib/Doctrine/DBAL/Platforms/MySqlPlatform.php
@@ -26,6 +26,7 @@
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types\BlobType;
 use Doctrine\DBAL\Types\TextType;
+use const E_USER_DEPRECATED;
 use function array_diff_key;
 use function array_merge;
 use function array_unique;
@@ -40,6 +41,7 @@
 use function sprintf;
 use function str_replace;
 use function strtoupper;
+use function trigger_error;
 use function trim;
 
 /**
@@ -99,9 +101,13 @@ public function getRegexpExpression()
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
+        @trigger_error(__METHOD__ . '() is deprecated, use application-generated UUIDs instead.', E_USER_DEPRECATED);
+
         return 'UUID()';
     }
 

diff --git a/lib/Doctrine/DBAL/Platforms/OraclePlatform.php b/lib/Doctrine/DBAL/Platforms/OraclePlatform.php
@@ -28,6 +28,7 @@
 use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types\BinaryType;
+use const E_USER_DEPRECATED;
 use function array_merge;
 use function count;
 use function explode;
@@ -41,6 +42,7 @@
 use function strpos;
 use function strtoupper;
 use function substr;
+use function trigger_error;
 
 /**
  * OraclePlatform.
@@ -108,9 +110,13 @@ public function getLocateExpression($str, $substr, $startPos = false)
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
+        @trigger_error(__METHOD__ . '() is deprecated, use application-generated UUIDs instead.', E_USER_DEPRECATED);
+
         return 'SYS_GUID()';
     }
 

diff --git a/lib/Doctrine/DBAL/Platforms/PostgreSqlPlatform.php b/lib/Doctrine/DBAL/Platforms/PostgreSqlPlatform.php
@@ -30,6 +30,7 @@
 use Doctrine\DBAL\Types\BlobType;
 use Doctrine\DBAL\Types\IntegerType;
 use Doctrine\DBAL\Types\Type;
+use const E_USER_DEPRECATED;
 use function array_diff;
 use function array_merge;
 use function array_unique;
@@ -45,6 +46,7 @@
 use function str_replace;
 use function strpos;
 use function strtolower;
+use function trigger_error;
 use function trim;
 
 /**
@@ -1016,9 +1018,13 @@ public function getTimeTypeDeclarationSQL(array $fieldDeclaration)
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
+        @trigger_error(__METHOD__ . '() is deprecated, use application-generated UUIDs instead.', E_USER_DEPRECATED);
+
         return 'UUID_GENERATE_V4()';
     }
 

diff --git a/lib/Doctrine/DBAL/Platforms/SQLAnywherePlatform.php b/lib/Doctrine/DBAL/Platforms/SQLAnywherePlatform.php
@@ -30,6 +30,7 @@
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\TransactionIsolationLevel;
+use const E_USER_DEPRECATED;
 use function array_merge;
 use function array_unique;
 use function array_values;
@@ -44,6 +45,7 @@
 use function strpos;
 use function strtoupper;
 use function substr;
+use function trigger_error;
 
 /**
  * The SQLAnywherePlatform provides the behavior, features and SQL dialect of the
@@ -690,9 +692,13 @@ public function getForUpdateSQL()
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
+        @trigger_error(__METHOD__ . '() is deprecated, use application-generated UUIDs instead.', E_USER_DEPRECATED);
+
         return 'NEWID()';
     }
 

diff --git a/lib/Doctrine/DBAL/Platforms/SQLServerPlatform.php b/lib/Doctrine/DBAL/Platforms/SQLServerPlatform.php
@@ -28,6 +28,7 @@
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\Types;
+use const E_USER_DEPRECATED;
 use function array_merge;
 use function array_unique;
 use function array_values;
@@ -39,7 +40,6 @@
 use function implode;
 use function is_array;
 use function is_bool;
-use function is_null;
 use function is_numeric;
 use function is_string;
 use function preg_match;
@@ -53,6 +53,7 @@
 use function strtoupper;
 use function substr;
 use function substr_count;
+use function trigger_error;
 
 /**
  * The SQLServerPlatform provides the behavior, features and SQL dialect of the
@@ -1026,9 +1027,13 @@ public function getDropViewSQL($name)
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
+        @trigger_error(__METHOD__ . '() is deprecated, use application-generated UUIDs instead.', E_USER_DEPRECATED);
+
         return 'NEWID()';
     }
 

diff --git a/lib/Doctrine/DBAL/Platforms/SqlitePlatform.php b/lib/Doctrine/DBAL/Platforms/SqlitePlatform.php
@@ -29,6 +29,7 @@
 use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types;
+use const E_USER_DEPRECATED;
 use function array_merge;
 use function array_unique;
 use function array_values;
@@ -40,6 +41,7 @@
 use function strlen;
 use function strpos;
 use function strtolower;
+use function trigger_error;
 
 /**
  * The SqlitePlatform class describes the specifics and dialects of the SQLite
@@ -63,9 +65,13 @@ public function getRegexpExpression()
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
+        @trigger_error(__METHOD__ . '() is deprecated, use application-generated UUIDs instead.', E_USER_DEPRECATED);
+
         return "HEX(RANDOMBLOB(4)) || '-' || HEX(RANDOMBLOB(2)) || '-4' || "
             . "SUBSTR(HEX(RANDOMBLOB(2)), 2) || '-' || "
             . "SUBSTR('89AB', 1 + (ABS(RANDOM()) % 4), 1) || "

diff --git a/tests/Doctrine/Tests/DBAL/Functional/Ticket/DBAL421Test.php b/tests/Doctrine/Tests/DBAL/Functional/Ticket/DBAL421Test.php
@@ -19,6 +19,10 @@ protected function setUp()
         }
     }
 
+    /**
+     * @group legacy
+     * @expectedDeprecation %s::getGuidExpression() is deprecated, use application-generated UUIDs instead.
+     */
     public function testGuidShouldMatchPattern()
     {
         $guid = $this->_conn->query($this->getSelectGuidSql())->fetchColumn();
@@ -29,6 +33,9 @@ public function testGuidShouldMatchPattern()
     /**
      * This test does (of course) not proof that all generated GUIDs are
      * random, it should however provide some basic confidence.
+     *
+     * @group legacy
+     * @expectedDeprecation %s::getGuidExpression() is deprecated, use application-generated UUIDs instead.
      */
     public function testGuidShouldBeRandom()
     {

diff --git a/tests/Doctrine/Tests/DBAL/Platforms/SQLAnywherePlatformTest.php b/tests/Doctrine/Tests/DBAL/Platforms/SQLAnywherePlatformTest.php
@@ -514,6 +514,10 @@ public function testCannotGenerateDropIndexSQLWithInvalidTableParameter()
         $this->_platform->getDropIndexSQL('index', array('table'));
     }
 
+    /**
+     * @group legacy
+     * @expectedDeprecation Doctrine\DBAL\Platforms\SQLAnywherePlatform::getGuidExpression() is deprecated, use application-generated UUIDs instead.
+     */
     public function testGeneratesSQLSnippets()
     {
         self::assertEquals('STRING(column1, "string1", column2, "string2")', $this->_platform->getConcatExpression(