vendor/doctrine/dbal/UPGRADE

   1 # Upgrade to 2.3
   2
   3 ## Oracle Session Init now sets Numeric Character
   4
   5 Before 2.3 the Oracle Session Init did not care about the numeric character of the Session.
   6 This could lead to problems on non english locale systems that required a comma as a floating
   7 point seperator in Oracle. Since 2.3, using the Oracle Session Init on connection start the
   8 client session will be altered to set the numeric character to ".,":
   9
  10     ALTER SESSION SET NLS_NUMERIC_CHARACTERS = '.,'
  11
  12 See [DBAL-345](http://www.doctrine-project.org/jira/browse/DBAL-345) for more details.
  13
  14 ## Doctrine\DBAL\Connection and Doctrine\DBAL\Statement
  15
  16 The query related methods including but not limited to executeQuery, exec, query, and executeUpdate
  17 now wrap the driver exceptions such as PDOException with DBALException to add more debugging
  18 information such as the executed SQL statement, and any bound parameters.
  19
  20 If you want to retrieve the driver specific exception, you can retrieve it by calling the
  21 ``getPrevious()`` method on DBALException.
  22
  23 Before:
  24
  25     catch(\PDOException $ex) {
  26         // ...
  27     }
  28
  29 After:
  30
  31     catch(\Doctrine\DBAL\DBALException $ex) {
  32         $pdoException = $ex->getPrevious();
  33         // ...
  34     }
  35
  36 ## Doctrine\DBAL\Connection#setCharsetSQL() removed
  37
  38 This method only worked on MySQL and it is considered unsafe on MySQL to use SET NAMES UTF-8 instead
  39 of setting the charset directly on connection already. Replace this behavior with the
  40 connection charset option:
  41
  42 Before:
  43
  44     $conn = DriverManager::getConnection(array(..));
  45     $conn->setCharset('UTF8');
  46
  47 After:
  48
  49     $conn = DriverManager::getConnection(array('charset' => 'UTF8', ..));
  50
  51 ## Doctrine\DBAL\Schema\Table#renameColumn() removed
  52
  53 Doctrine\DBAL\Schema\Table#renameColumn() was removed, because it drops and recreates
  54 the column instead. There is no fix available, because a schema diff
  55 cannot reliably detect if a column was renamed or one column was created
  56 and another one dropped.
  57
  58 You should use explicit SQL ALTER TABLE statements to change columns names.
  59
  60 ## Schema Filter paths
  61
  62 The Filter Schema assets expression is not wrapped in () anymore for the regexp automatically.
  63
  64 Before:
  65
  66     $config->setFilterSchemaAssetsExpression('foo');
  67
  68 After:
  69
  70     $config->setFilterSchemaAssetsExpression('(foo)');
  71
  72 ## Creating MySQL Tables now defaults to UTF-8
  73
  74 If you are creating a new MySQL Table through the Doctrine API, charset/collate are
  75 now set to 'utf8'/'utf8_unicode_ci' by default. Previously the MySQL server defaults were used.
  76
  77 # Upgrade to 2.2
  78
  79 ## Doctrine\DBAL\Connection#insert and Doctrine\DBAL\Connnection#update
  80
  81 Both methods now accept an optional last parameter $types with binding types of the values passed.
  82 This can potentially break child classes that have overwritten one of these methods.
  83
  84 ## Doctrine\DBAL\Connection#executeQuery
  85
  86 Doctrine\DBAL\Connection#executeQuery() got a new last parameter "QueryCacheProfile $qcp"
  87
  88 ## Doctrine\DBAL\Driver\Statement split
  89
  90 The Driver statement was split into a ResultStatement and the normal statement extending from it.
  91 This seperates the configuration and the retrieval API from a statement.
  92
  93 ## MsSql Platform/SchemaManager renamed
  94
  95 The MsSqlPlatform was renamed to SQLServerPlatform, the MsSqlSchemaManager was renamed
  96 to SQLServerSchemaManager.
  97
  98 ## Cleanup SQLServer Platform version mess
  99
 100 DBAL 2.1 and before were actually only compatible to SQL Server 2008, not earlier versions.
 101 Still other parts of the platform did use old features instead of newly introduced datatypes
 102 in SQL Server 2005. Starting with DBAL 2.2 you can pick the Doctrine abstraction exactly
 103 matching your SQL Server version.
 104
 105 The PDO SqlSrv driver now uses the new `SQLServer2008Platform` as default platform.
 106 This platform uses new features of SQL Server as of version 2008. This also includes a switch
 107 in the used fields for "text" and "blob" field types to:
 108
 109     "text" => "VARCHAR(MAX)"
 110     "blob" => "VARBINARY(MAX)"
 111
 112 Additionally `SQLServerPlatform` in DBAL 2.1 and before used "DATE", "TIME" and "DATETIME2" for dates.
 113 This types are only available since version 2008 and the introduction of an explicit
 114 SQLServer 2008 platform makes this dependency explicit.
 115
 116 An `SQLServer2005Platform` was also introduced to differentiate the features between
 117 versions 2003, earlier and 2005.
 118
 119 With this change the `SQLServerPlatform` now throws an exception for using limit queries
 120 with an offset, since SQLServer 2003 and lower do not support this feature.
 121
 122 To use the old SQL Server Platform, because you are using SQL Server 2003 and below use
 123 the following configuration code:
 124
 125     use Doctrine\DBAL\DriverManager;
 126     use Doctrine\DBAL\Platforms\SQLServerPlatform;
 127     use Doctrine\DBAL\Platforms\SQLServer2005Platform;
 128
 129     // You are using SQL Server 2003 or earlier
 130     $conn = DriverManager::getConnection(array(
 131         'driver' => 'pdo_sqlsrv',
 132         'platform' => new SQLServerPlatform()
 133         // .. additional parameters
 134     ));
 135
 136     // You are using SQL Server 2005
 137     $conn = DriverManager::getConnection(array(
 138         'driver' => 'pdo_sqlsrv',
 139         'platform' => new SQLServer2005Platform()
 140         // .. additional parameters
 141     ));
 142
 143     // You are using SQL Server 2008
 144     $conn = DriverManager::getConnection(array(
 145         'driver' => 'pdo_sqlsrv',
 146         // 2008 is default platform
 147         // .. additional parameters
 148     ));