Merge pull request #3212 from morozov/bpo/2.8/3167

Deprecated usage of DB-generated UUIDs

UPGRADE.md

 # 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.

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();
         }
     }
 

lib/Doctrine/DBAL/Platforms/AbstractPlatform.php

@@ -686,6 +686,8 @@ abstract class AbstractPlatform
      * @return string
      *
      * @throws \Doctrine\DBAL\DBALException If not supported on this platform.
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {

lib/Doctrine/DBAL/Platforms/DrizzlePlatform.php

@@ -621,6 +621,8 @@ class DrizzlePlatform extends AbstractPlatform
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {

lib/Doctrine/DBAL/Platforms/MySqlPlatform.php

@@ -99,6 +99,8 @@ class MySqlPlatform extends AbstractPlatform
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {

lib/Doctrine/DBAL/Platforms/OraclePlatform.php

@@ -108,6 +108,8 @@ class OraclePlatform extends AbstractPlatform
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {

lib/Doctrine/DBAL/Platforms/PostgreSqlPlatform.php

@@ -1016,6 +1016,8 @@ class PostgreSqlPlatform extends AbstractPlatform
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {

lib/Doctrine/DBAL/Platforms/SQLAnywherePlatform.php

@@ -690,6 +690,8 @@ class SQLAnywherePlatform extends AbstractPlatform
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {

lib/Doctrine/DBAL/Platforms/SQLServerPlatform.php

@@ -39,7 +39,6 @@ use function func_get_args;
 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;
@@ -1026,6 +1025,8 @@ class SQLServerPlatform extends AbstractPlatform
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {

lib/Doctrine/DBAL/Platforms/SqlitePlatform.php

@@ -63,6 +63,8 @@ class SqlitePlatform extends AbstractPlatform
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated Use application-generated UUIDs instead
      */
     public function getGuidExpression()
     {