Deprecated usage of DB-generated UUIDs

morozov · morozov · commit f4b4ad9bba1f · 2018-07-10T23:51:35.000-07:00
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,6 +686,8 @@ public function getRegexpExpression()
      * @return string
      *
      * @throws \Doctrine\DBAL\DBALException If not supported on this platform.
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
diff --git a/lib/Doctrine/DBAL/Platforms/DrizzlePlatform.php b/lib/Doctrine/DBAL/Platforms/DrizzlePlatform.php
@@ -621,6 +621,8 @@ public function getLocateExpression($str, $substr, $startPos = false)
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
diff --git a/lib/Doctrine/DBAL/Platforms/MySqlPlatform.php b/lib/Doctrine/DBAL/Platforms/MySqlPlatform.php
@@ -99,6 +99,8 @@ public function getRegexpExpression()
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
diff --git a/lib/Doctrine/DBAL/Platforms/OraclePlatform.php b/lib/Doctrine/DBAL/Platforms/OraclePlatform.php
@@ -108,6 +108,8 @@ public function getLocateExpression($str, $substr, $startPos = false)
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
diff --git a/lib/Doctrine/DBAL/Platforms/PostgreSqlPlatform.php b/lib/Doctrine/DBAL/Platforms/PostgreSqlPlatform.php
@@ -1016,6 +1016,8 @@ public function getTimeTypeDeclarationSQL(array $fieldDeclaration)
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
diff --git a/lib/Doctrine/DBAL/Platforms/SQLAnywherePlatform.php b/lib/Doctrine/DBAL/Platforms/SQLAnywherePlatform.php
@@ -690,6 +690,8 @@ public function getForUpdateSQL()
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
diff --git a/lib/Doctrine/DBAL/Platforms/SQLServerPlatform.php b/lib/Doctrine/DBAL/Platforms/SQLServerPlatform.php
@@ -1026,6 +1026,8 @@ public function getDropViewSQL($name)
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
diff --git a/lib/Doctrine/DBAL/Platforms/SqlitePlatform.php b/lib/Doctrine/DBAL/Platforms/SqlitePlatform.php
@@ -63,6 +63,8 @@ public function getRegexpExpression()
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {
diff --git a/tests/Doctrine/Tests/DBAL/Functional/Ticket/DBAL421Test.php b/tests/Doctrine/Tests/DBAL/Functional/Ticket/DBAL421Test.php
@@ -19,6 +19,9 @@ protected function setUp()
         }
     }
 
+    /**
+     * @group legacy
+     */
     public function testGuidShouldMatchPattern()
     {
         $guid = $this->_conn->query($this->getSelectGuidSql())->fetchColumn();
@@ -29,6 +32,8 @@ 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
      */
     public function testGuidShouldBeRandom()
     {

Original file line number	Diff line number	Diff line change
`@@ -686,6 +686,8 @@ public function getRegexpExpression()`
`686`	`686`	`* @return string`
`687`	`687`	`*`
`688`	`688`	`* @throws \Doctrine\DBAL\DBALException If not supported on this platform.`
	`689`	`+ *`
	`690`	`+ * @deprecated Use application-generated UUIDs instead`
`689`	`691`	`*/`
`690`	`692`	`public function getGuidExpression()`
`691`	`693`	`{`
Original file line number	Diff line number	Diff line change
`@@ -621,6 +621,8 @@ public function getLocateExpression($str, $substr, $startPos = false)`
`621`	`621`
`622`	`622`	`/**`
`623`	`623`	`* {@inheritDoc}`
	`624`	`+ *`
	`625`	`+ * @deprecated Use application-generated UUIDs instead`
`624`	`626`	`*/`
`625`	`627`	`public function getGuidExpression()`
`626`	`628`	`{`
Original file line number	Diff line number	Diff line change
`@@ -99,6 +99,8 @@ public function getRegexpExpression()`
`99`	`99`
`100`	`100`	`/**`
`101`	`101`	`* {@inheritDoc}`
	`102`	`+ *`
	`103`	`+ * @deprecated Use application-generated UUIDs instead`
`102`	`104`	`*/`
`103`	`105`	`public function getGuidExpression()`
`104`	`106`	`{`
Original file line number	Diff line number	Diff line change
`@@ -108,6 +108,8 @@ public function getLocateExpression($str, $substr, $startPos = false)`
`108`	`108`
`109`	`109`	`/**`
`110`	`110`	`* {@inheritDoc}`
	`111`	`+ *`
	`112`	`+ * @deprecated Use application-generated UUIDs instead`
`111`	`113`	`*/`
`112`	`114`	`public function getGuidExpression()`
`113`	`115`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1016,6 +1016,8 @@ public function getTimeTypeDeclarationSQL(array $fieldDeclaration)`
`1016`	`1016`
`1017`	`1017`	`/**`
`1018`	`1018`	`* {@inheritDoc}`
	`1019`	`+ *`
	`1020`	`+ * @deprecated Use application-generated UUIDs instead`
`1019`	`1021`	`*/`
`1020`	`1022`	`public function getGuidExpression()`
`1021`	`1023`	`{`
Original file line number	Diff line number	Diff line change
`@@ -690,6 +690,8 @@ public function getForUpdateSQL()`
`690`	`690`
`691`	`691`	`/**`
`692`	`692`	`* {@inheritdoc}`
	`693`	`+ *`
	`694`	`+ * @deprecated Use application-generated UUIDs instead`
`693`	`695`	`*/`
`694`	`696`	`public function getGuidExpression()`
`695`	`697`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1026,6 +1026,8 @@ public function getDropViewSQL($name)`
`1026`	`1026`
`1027`	`1027`	`/**`
`1028`	`1028`	`* {@inheritDoc}`
	`1029`	`+ *`
	`1030`	`+ * @deprecated Use application-generated UUIDs instead`
`1029`	`1031`	`*/`
`1030`	`1032`	`public function getGuidExpression()`
`1031`	`1033`	`{`
Original file line number	Diff line number	Diff line change
`@@ -63,6 +63,8 @@ public function getRegexpExpression()`
`63`	`63`
`64`	`64`	`/**`
`65`	`65`	`* {@inheritDoc}`
	`66`	`+ *`
	`67`	`+ * @deprecated Use application-generated UUIDs instead`
`66`	`68`	`*/`
`67`	`69`	`public function getGuidExpression()`
`68`	`70`	`{`