Note about upgrading: Doctrine uses static and runtime mechanisms to raise awareness about deprecated code.
- Use of
@deprecateddocblock that is detected by IDEs (like PHPStorm) or Static Analysis tools (like Psalm, phpstan) - Use of our low-overhead runtime deprecation API, details: https://github.com/doctrine/deprecations/
The SQLLogger interface and its implementations DebugStack and LoggerChain have been removed.
The corresponding Configuration methods, getSQLLogger() and setSQLLogger(), have been removed as well.
The SqliteSchemaManager::createDatabase() and dropDatabase() methods have been removed.
The following AbstractSchemaManager methods have been removed:
AbstractSchemaManager::dropAndCreateConstraint(),AbstractSchemaManager::dropAndCreateDatabase(),AbstractSchemaManager::dropAndCreateForeignKey(),AbstractSchemaManager::dropAndCreateIndex(),AbstractSchemaManager::dropAndCreateSequence(),AbstractSchemaManager::dropAndCreateTable(),AbstractSchemaManager::dropAndCreateView(),AbstractSchemaManager::tryMethod().
DBAL is now tested only with SQL Server 2017 and newer.
The Statement::execute() method has been marked private.
The QueryBuilder::execute() method has been removed.
The Constraint interface has been removed. The ForeignKeyConstraint, Index and UniqueConstraint classes
no longer implement this interface.
The following methods that used to accept an instance of Constraint have been removed:
AbstractPlatform::getCreateConstraintSQL(),AbstractSchemaManager::createConstraint(),::dropConstraint()and::dropAndCreateConstraint(),ForeignKeyConstraint::getColumns()and::getQuotedColumns().
The AbstractSchemaManager::getSchemaSearchPaths() method has been removed.
The schema configuration returned by AbstractSchemaManager::createSchemaConfig() will contain a non-empty schema name
only for those database platforms that support schemas (currently, PostgreSQL).
The schema returned by AbstractSchemaManager::createSchema() will have a non-empty name only for those
database platforms that support schemas.
The AbstractAsset::getFullQualifiedName() method has been removed.
The following methods have been removed:
Schema::hasExplicitForeignKeyIndexes(),SchemaConfig::hasExplicitForeignKeyIndexes(),SchemaConfig::setExplicitForeignKeyIndexes().
The Schema::getTableNames() method has been removed.
The Schema::getNamespaces(), Schema::getTables() and Schema::getSequences() methods will return numeric arrays
of namespaces, tables and sequences respectively instead of associative arrays.
The following SqlitePlatform methods have been removed:
udfSqrt(),udfMod(),udfLocate().
The following SQLServerPlatform methods have been marked protected:
getDefaultConstraintDeclarationSQL(),getAddExtendedPropertySQL(),getDropExtendedPropertySQL(),getUpdateExtendedPropertySQL().
The OraclePlatform::getCreateAutoincrementSql() method has been marked protected.
The OraclePlatform::assertValidIdentifier() method has been removed.
BC BREAK: Changed signatures of AbstractPlatform::getIndexDeclarationSQL() and ::getUniqueConstraintDeclarationSQL()
The AbstractPlatform::getIndexDeclarationSQL() and ::getUniqueConstraintDeclarationSQL() methods no longer accept
the name of the object as a separate parameter. The name of the passed index or constraint is used instead.
The AbstractPlatform::canEmulateSchemas() method and the schema emulation implemented in the SQLite platform
have been removed.
- The columns are returned as a list, not as an associative array.
- The columns are no longer sorted based on whether they belong to the primary key or a foreign key.
BC BREAK: Removed schema comparison APIs that don't account for the current database connection and the database platform
The Schema::getMigrateFromSql() and ::getMigrateToSql() methods have been removed.
The ServerInfoAwareConnection interface has been removed. The getServerVersion() method has been made
part of the driver-level Connection interface.
The VersionAwarePlatformDriver interface has been removed. The Driver::getDatabasePlatform() method now accepts
a ServerVersionProvider argument that will provide the server version, if the driver relies on the server version
to instantiate a database platform.
The AbstractPlatform::getName() method has been removed.
The following platform-related classes have been removed:
PostgreSQL94PlatformandPostgreSQL94Keywords.SQLServer2012PlatformandSQLServer2012Keywords.
The AbstractPlatform::getNowExpression() method has been removed.
Reference from ForeignKeyConstraint to its local (referencing) Table is removed as well as the following methods:
setLocalTable(),getLocalTable(),getLocalTableName().
The type of SchemaDiff::$orphanedForeignKeys has changed from list of foreign keys (list)
to map of referencing tables to their list of foreign keys (array<string,list>).
The following redundant AbstractPlatform methods have been removed:
getSqlCommentStartString(),getSqlCommentEndString(),getWildcards(),getAvgExpression(),getCountExpression(),getMaxExpression(),getMinExpression(),getSumExpression(),getMd5Expression(),getSqrtExpression(),getRoundExpression(),getRtrimExpression(),getLtrimExpression(),getUpperExpression(),getLowerExpression(),getNotExpression(),getIsNullExpression(),getIsNotNullExpression(),getBetweenExpression(),getAcosExpression(),getSinExpression(),getPiExpression(),getCosExpression(),getTemporaryTableSQL(),getUniqueFieldDeclarationSQL(),getListUsersSQL(),supportsIndexes(),supportsAlterTable(),supportsTransactions(),supportsPrimaryConstraints(),supportsViews(),supportsLimitOffset().supportsGettingAffectedRows().
The following abstract methods in the AbstractPlatform class have been declared as abstract:
getListTablesSQL(),getAlterTableSQL(),getListTableColumnsSQL(),getListTableIndexesSQL(),getListTableForeignKeysSQL(),getCreateViewSQL(),getListViewsSQL(),getDropViewSQL(),getDateArithmeticIntervalExpression(),getDateDiffExpression(),getTimeTypeDeclarationSQL(),getDateTimeTypeDeclarationSQL(),getLocateExpression(),getSetTransactionIsolationSQL().
Every non-abstract platform class must implement them in order to satisfy the API.
Instead of returning an empty value, Connection::lastInsertId() throws an exception when there's no identity value.
The method Comparator::compareSchemas() cannot be called statically anymore.
The method Comparator::compare() has been removed, use Comparator::compareSchemas() instead.
The TableGenerator component has been removed.
The Connection::lastInsertId() method no longer accepts a sequence name.
The library no longer provides the default values for MySQL table charset, collation and engine. If omitted in the table definition, MySQL will derive the values from the database options.
To add or replace a keyword list, use ReservedWordsCommand::setKeywordList().
Instead of implementing AbstractPlatform::getReservedKeywordsClass(), platforms must implement AbstractPlatform::createReservedKeywordsList(). The latter has been made abstract.
PostgreSQLSchemaManager::getExistingSchemaSearchPaths() and ::determineExistingSchemaSearchPaths() have been made protected.
The former has also been made final.
The following schema- and namespace-related methods have been removed:
AbstractPlatform::getListNamespacesSQL(),AbstractSchemaManager::listNamespaceNames(),AbstractSchemaManager::getPortableNamespacesList(),AbstractSchemaManager::getPortableNamespaceDefinition(),PostgreSQLSchemaManager::getSchemaNames().
Removed the $driverOptions argument of PDO\Statement::bindParam() and PDO\SQLSrv\Statement::bindParam()
The $driverOptions argument of PDO\Statement::bindParam() and PDO\SQLSrv\Statement::bindParam() has been removed. The specifics of binding a parameter to the statement should be specified using the $type argument.
The Connection and AbstractSchemaManager classes used to have a reference on each other effectively making a circular reference. Use createSchemaManager() to instantiate a schema manager.
The Connection and ExpressionBuilder classes used to have a reference on each other effectively making a circular reference. Use createExpressionBuilder() to instantiate an expression builder.
The andX() and orX() methods of the ExpressionBuilder class have been removed. Use and() and or() instead.
The add() and addMultiple() methods of the CompositeExpression class have been removed. Use with() instead, which returns a new instance.
The CompositeExpression class is now immutable.
- The
select(),addSelect(),groupBy()andaddGroupBy()methods no longer accept an array of arguments. Pass each expression as an individual argument or expand an array of expressions using the...operator. - The
select(),addSelect(),groupBy()andaddGroupBy()methods no longer ignore the first argument if it's empty. - The
addSelect()method can be no longer called without arguments. - The
insert(),update()anddelete()methods now require the$tableparameter, and do not support aliases anymore. - The
add(),getQueryPart(),getQueryParts(),resetQueryPart()andresetQueryParts()methods are removed. - For a
select()query, thegetSQL()method now throws an expression if noSELECTexpressions have been provided.
The OCI8Statement::convertPositionalToNamedPlaceholders() method has been extracted to an internal utility class.
The ServerInfoAwareConnection::requiresQueryForServerVersion() method has been removed as an implementation detail which is the same for almost all supported drivers.
- The
Doctrine\DBAL\Driver::getDatabase()method has been removed. Please useDoctrine\DBAL\Connection::getDatabase()instead. Doctrine\DBAL\Connection::getDatabase()will always return the name of the database currently connected to, regardless of the configuration parameters and will initialize a database connection if it's not yet established.- A call to
Doctrine\DBAL\Connection::getDatabase(), when connected to an SQLite database, will no longer return the database file path.
- When generating schema DDL, DBAL no longer provides the default length for string and binary columns. The application may need to provide the column length if required by the target platform.
- The
\DBAL\Platforms\AbstractPlatform::getVarcharTypeDeclarationSQL()method has been renamed to::getStringTypeDeclarationSQL(). - The following
AbstractPlatformmethods have been removed as no longer relevant:::getCharMaxLength(),::getVarcharMaxLength(),::getVarcharDefaultLength(),::getBinaryMaxLength(),::getBinaryDefaultLength().
Table columns are no longer indexed by column name. Use the name attribute of the column instead.
- Class constant
SQLSrvStatement::LAST_INSERT_ID_SQLwas changed from public to private. - Class
Doctrine\DBAL\Sharding\ShardChoser\MultiTenantShardChoserwas made final. - Class
Doctrine\DBAL\Sharding\SQLAzure\Schema\MultiTenantVisitorwas made final. - Class
Doctrine\DBAL\Sharding\SQLAzure\SQLAzureFederationsSynchronizerwas made final. - Class
Doctrine\DBAL\Sharding\PoolingShardManagerwas made final. - Class
Doctrine\DBAL\Id\TableGeneratorSchemaVisitorwas made final. - Class
Doctrine\DBAL\Driver\Mysqli\Driverwas made final. - Class
Doctrine\DBAL\Driver\Mysqli\MysqliStatementwas made final. - Class
Doctrine\DBAL\Driver\OCI8\Driverwas made final. - Class
Doctrine\DBAL\Driver\OCI8\OCI8Connectionwas made final. - Class
Doctrine\DBAL\Driver\OCI8\OCI8Statementwas made final. - Class
Doctrine\DBAL\Driver\PDOSqlsrv\Driverwas made final. - Class
Doctrine\DBAL\Driver\PDOSqlsrv\Statementwas made final. - Class
Doctrine\DBAL\Driver\PDOMySql\Driverwas made final. - Class
Doctrine\DBAL\Driver\IBMDB2\DB2Connectionwas made final. - Class
Doctrine\DBAL\Driver\IBMDB2\DB2Statementwas made final. - Class
Doctrine\DBAL\Driver\IBMDB2\DB2Driverwas made final. - Class
Doctrine\DBAL\Driver\SQLSrv\SQLSrvStatementwas made final. - Class
Doctrine\DBAL\Driver\SQLSrv\Driverwas made final. - Class
Doctrine\DBAL\Driver\SQLSrv\SQLSrvConnectionwas made final. - Class
Doctrine\DBAL\Driver\SQLAnywhere\SQLAnywhereConnectionwas made final. - Class
Doctrine\DBAL\Driver\SQLAnywhere\Driverwas made final. - Class
Doctrine\DBAL\Driver\SQLAnywhere\SQLAnywhereStatementwas made final. - Class
Doctrine\DBAL\Driver\PDOPgSql\Driverwas made final. - Class
Doctrine\DBAL\Driver\PDOOracle\Driverwas made final. - Class
Doctrine\DBAL\Driver\PDOSqlite\Driverwas made final. - Class
Doctrine\DBAL\Driver\StatementIteratorwas made final. - Class
Doctrine\DBAL\Cache\ResultCacheStatementwas made final. - Class
Doctrine\DBAL\Cache\ArrayStatementwas made final. - Class
Doctrine\DBAL\Schema\Synchronizer\SingleDatabaseSynchronizerwas made final. - Class
Doctrine\DBAL\Schema\Visitor\RemoveNamespacedAssetswas made final. - Class
Doctrine\DBAL\Portability\Statementwas made final.
- Column precision no longer defaults to 10. The default value is NULL.
- Asset names are no longer nullable. An empty asset name should be represented as an empty string.
Doctrine\DBAL\Schema\AbstractSchemaManager::_getPortableTriggersList()and::_getPortableTriggerDefinition()have been removed.
SchemaAlterTableAddColumnEventArgs::addSql()and the same method in otherSchemaEventArgs-based classes no longer accept an array of SQL statements. They accept a variadic string.ConnectionEventArgs::getDriver(),::getDatabasePlatform()and::getSchemaManager()methods have been removed. The connection information can be obtained from the connection which is available via::getConnection().SchemaColumnDefinitionEventArgs::getDatabasePlatform()andSchemaIndexDefinitionEventArgs::getDatabasePlatform()have been removed for the same reason as above.
- The following methods have been removed as leaking internal implementation details:
::getHost(),::getPort(),::getUsername(),::getPassword(). - The
::getDatabase()method can now return null which means that no database is currently selected.
- The class stores the last inserted ID as a nullable string, not an integer, which is reflected in the method signatures.
- Method
Doctrine\DBAL\Schema\AbstractSchemaManager::_getPortableViewDefinition()no longer optionally returns false. It will always return aDoctrine\DBAL\Schema\Viewinstance. - Method
Doctrine\DBAL\Schema\Comparator::diffTable()now optionally returns null instead of false. - Property
Doctrine\DBAL\Schema\Table::$_primaryKeyNameis now optionally null instead of false. - Property
Doctrine\DBAL\Schema\TableDiff::$newNameis now optionally null instead of false. - Method
Doctrine\DBAL\Schema\AbstractSchemaManager::tablesExist()no longer accepts a string. UseDoctrine\DBAL\Schema\AbstractSchemaManager::tableExists()instead. - Method
Doctrine\DBAL\Schema\OracleSchemaManager::createDatabase()no longer acceptsnullfor$databaseargument. - Removed unused method
Doctrine\DBAL\Schema\AbstractSchemaManager::_getPortableFunctionsList() - Removed unused method
Doctrine\DBAL\Schema\AbstractSchemaManager::_getPortableFunctionDefinition() - Removed unused method
Doctrine\DBAL\Schema\OracleSchemaManager::_getPortableFunctionDefinition() - Removed unused method
Doctrine\DBAL\Schema\SqliteSchemaManager::_getPortableTableIndexDefinition()
- The
$usernameand$passwordarguments of::connect()are no longer nullable. Use an empty string to indicate empty username or password. - The return value of
::getDatabase()has been documented as nullable since some of the drivers allow establishing a connection without selecting a database.
The Doctrine\DBAL\Driver::getName() has been removed.
- Removed
json_arraytype and all associated hacks. - Removed
Connection::TRANSACTION_*constants. - Removed
AbstractPlatform::DATE_INTERVAL_UNIT_*andAbstractPlatform::TRIM_*constants. - Removed
MysqlSessionInitlistener. - Removed
MysqlPlatform::getCollationFieldDeclaration(). - Removed
AbstractPlatform::getIdentityColumnNullInsertSQL(). - Removed
Table::addUnnamedForeignKeyConstraint()andTable::addNamedForeignKeyConstraint(). - Removed
Table::renameColumn(). - Removed
SQLParserUtils::getPlaceholderPositions(). - Removed
AbstractSchemaManager::getFilterSchemaAssetsExpression(),Configuration::getFilterSchemaAssetsExpression()andConfiguration::getFilterSchemaAssetsExpression(). SQLParserUtils::*_TOKENconstants made private.
Connection::ping() and PingableConnection::ping() no longer return a boolean value. They will throw an exception in case of failure.
PostgreSqlPlatform::getAdvancedForeignKeyOptionsSQL() had a typo in it in 2.x. Both the option name
feferred and deferred were supported in 2.x but the misspelling was removed in 3.x.
BC BREAK AbstractSchemaManager::extractDoctrineTypeFromComment() changed, ::removeDoctrineTypeFromComment() removed
AbstractSchemaManager::extractDoctrineTypeFromComment() made protected. It takes the comment by reference, removes the type annotation from it and returns the extracted Doctrine type.
The method was used internally and is no longer needed.
The method was used internally and is no longer needed.
The following methods' arguments do not longer accept integer value:
- the
$expressionargument in::getCountExpression(), - the
$decimalsargument in::getRoundExpression(), - the
$secondsargument in::getDateAddSecondsExpression(), - the
$secondsargument in::getDateSubSecondsExpression(), - the
$minutesargument in::getDateAddMinutesExpression(), - the
$minutesargument in::getDateSubMinutesExpression(), - the
$hoursargument in::getDateAddHourExpression(), - the
$hoursargument in::getDateAddHourExpression(), - the
$daysargument in::getDateAddDaysExpression(), - the
$daysargument in::getDateSubDaysExpression(), - the
$weeksargument in::getDateAddWeeksExpression(), - the
$weeksargument in::getDateSubWeeksExpression(), - the
$monthsargument in::getDateAddMonthExpression(), - the
$monthsargument in::getDateSubMonthExpression(), - the
$quartersargument in::getDateAddQuartersExpression(), - the
$quartersargument in::getDateSubQuartersExpression(), - the
$yearsargument in::getDateAddYearsExpression(), - the
$yearsargument in::getDateSubYearsExpression().
Please use the strings representing numeric SQL literals instead (e.g. '1' instead of 1).
The signature of AbstractPlatform::getConcatExpression() changed to ::getConcatExpression(string ...$string).
BC BREAK The type of $start in AbstractPlatform::getLocateExpression() changed from string|false to ?string
The default value of $start is now null, not false.
BC BREAK The types of $start and $length in AbstractPlatform::getSubstringExpression() changed from int and ?int to string and ?string respectively
The platform abstraction allows building arbitrary SQL expressions, so even if the arguments represent numeric literals, they should be passed as a string.
BC BREAK The type of $char in AbstractPlatform::getTrimExpression() changed from string|false to ?string
The default value of $char is now null, not false. Additionally, the method will throw an InvalidArgumentException in an invalid value of $mode is passed.
Statement::quote() and ExpressionBuilder::literal() no longer accept arguments of an arbitrary type and and don't implement type-specific handling. Only strings can be quoted.
Connection::connect(), Statement::bindParam(), ::bindValue(), ::execute(), ResultStatement::setFetchMode() and ::closeCursor() no longer return a boolean value. They will throw an exception in case of failure.
Statement::rowCount() has been moved to the ResultStatement interface where it belongs by definition.
Statement::beginTransaction(), ::commit() and ::rollBack() no longer return a boolean value. They will throw a DriverException in case of failure.
Similarly to PDOStatement::fetchColumn(), DBAL statements throw an exception in case of an invalid column index.
Similarly to the drivers based on pdo_pgsql and pdo_sqlsrv, OCI8Statement::execute() and MySQLiStatement::execute() do not longer ignore redundant parameters.
The Doctrine\DBAL\Types\Type::getDefaultLength() method has been removed as it served no purpose.
Relying on string representation was discouraged and has been removed.
The NULL value of the $offset argument in AbstractPlatform::(do)?ModifyLimitQuery() methods is no longer allowed. The absence of the offset should be indicated with a 0 which is now the default value.
The support for DB-generated UUIDs was removed as non-portable. Please generate UUIDs on the application side (e.g. using ramsey/uuid).
The Doctrine\DBAL\Version class is no longer available: please refrain from checking the DBAL version at runtime.
- Binary fields whose length exceeds the maximum field size on a given platform are no longer represented as
BLOBs. Use binary fields of a size which fits all target platforms, or use blob explicitly instead. - Binary fields are no longer represented as streams in PHP. They are represented as strings.
The following methods have been removed.
| class | method | replacement |
|---|---|---|
Configuration |
setResultCacheImpl() |
setResultCache() |
Configuration |
getResultCacheImpl() |
getResultCache() |
QueryCacheProfile |
setResultCacheDriver() |
setResultCache() |
QueryCacheProfile |
getResultCacheDriver() |
getResultCache() |
The wrapper-level Connection::getWrappedConnection() method has been deprecated.
Use Connection::getNativeConnection() to access the native connection.
The Connection::connect() method has been marked internal. It will be marked protected in DBAL 4.0.
Driver and middleware connections need to implement a new method getNativeConnection() that gives access to the
native database connection. Not doing so is deprecated.
The following methods have been deprecated:
Doctrine\DBAL\Driver\PDO\Connection::getWrappedConnection()Doctrine\DBAL\Driver\PDO\SQLSrv\Connection::getWrappedConnection()Doctrine\DBAL\Driver\Mysqli\Connection::getWrappedResourceHandle()
Call getNativeConnection() to access the underlying PDO or MySQLi connection.
The SQLLogger and its implementations DebugStack and LoggerChain have been deprecated.
For logging purposes, use Doctrine\DBAL\Logging\Middleware instead. No replacement for DebugStack is provided.
The SqliteSchemaManager::createDatabase() and dropDatabase() methods have been deprecated. The SQLite engine
will create the database file automatically. In order to delete the database file, use the filesystem.
The following AbstractSchemaManager::dropAndCreate*() methods have been deprecated:
AbstractSchemaManager::dropAndCreateConstraint(). UseAbstractSchemaManager::dropIndex()andAbstractSchemaManager::createIndex(),AbstractSchemaManager::dropForeignKey()andAbstractSchemaManager::createForeignKey()orAbstractSchemaManager::dropUniqueConstraint()andAbstractSchemaManager::createUniqueConstraint()instead.AbstractSchemaManager::dropAndCreateIndex(). UseAbstractSchemaManager::dropIndex()andAbstractSchemaManager::createIndex()instead.AbstractSchemaManager::dropAndCreateForeignKey(). Use AbstractSchemaManager::dropForeignKey() and AbstractSchemaManager::createForeignKey() instead.AbstractSchemaManager::dropAndCreateSequence(). UseAbstractSchemaManager::dropSequence()andAbstractSchemaManager::createSequence()instead.AbstractSchemaManager::dropAndCreateTable(). UseAbstractSchemaManager::dropTable()andAbstractSchemaManager::createTable()instead.AbstractSchemaManager::dropAndCreateDatabase(). UseAbstractSchemaManager::dropDatabase()andAbstractSchemaManager::createDatabase()instead.AbstractSchemaManager::dropAndCreateView(). UseAbstractSchemaManager::dropView()andAbstractSchemaManager::createView()instead.
The AbstractSchemaManager::tryMethod() method has been also deprecated.
- The
AbstractSchemaManager::getSchemaSearchPaths()method has been deprecated. - Relying on
AbstractSchemaManager::createSchemaConfig()populating the schema name for those database platforms that don't support schemas (currently, all except for PostgreSQL) is deprecated. - Relying on
Schemausing "public" as the default name is deprecated.
The AbstractAsset::getFullQualifiedName() method has been deprecated. Use ::getNamespaceName()
and ::getName() instead.
The following methods have been deprecated:
Schema::hasExplicitForeignKeyIndexes(),SchemaConfig::hasExplicitForeignKeyIndexes(),SchemaConfig::setExplicitForeignKeyIndexes().
The Schema::getTableNames() method has been deprecated. In order to obtain schema table names,
use Schema::getTables() and call Table::getName() on the elements of the returned array.
Using the returned array keys as table names is deprecated. Retrieve the name from the table
via Table::getName() instead. In order to retrieve a table by name, use Schema::getTable().
The AbstractPlatform::canEmulateSchemas() method and the schema emulation implemented in the SQLite platform
have been deprecated.
The following SQLServerPlatform methods have been deprecated in favor of their implementations
in the UserDefinedFunctions class:
udfSqrt(),udfMod(),udfLocate().
The following SQLServerPlatform methods have been marked internal:
getDefaultConstraintDeclarationSQL(),getAddExtendedPropertySQL(),getDropExtendedPropertySQL(),getUpdateExtendedPropertySQL().
The OraclePlatform::getCreateAutoincrementSql() and ::getDropAutoincrementSql() have been marked internal.
The OraclePlatform::assertValidIdentifier() method has been deprecated.
- Using the returned array keys as column names is deprecated. Retrieve the name from the column
via
Column::getName()instead. In order to retrieve a column by name, useTable::getColumn(). - Relying on the columns being sorted based on whether they belong to the primary key or a foreign key is deprecated. If necessary, maintain the column order explicitly.
Not passing the $fromColumn argument to the ColumnDiff constructor is deprecated.
Relying on the name of the platform is discouraged. To identify the platform, use its class name.
PostgreSQL94PlatformandPostgreSQL94Keywords. UsePostgreSQLPlatformandPostgreSQLKeywordsinstead.SQLServer2012PlatformandSQLServer2012Keywords. UseSQLServerPlatformandSQLServerKeywordsinstead.
Deprecated schema comparison APIs that don't account for the current database connection and the database platform
- Instantiation of the
Comparatorclass outside the DBAL is deprecated. UseSchemaManager::createComparator()to create the comparator specific to the current database connection and the database platform. - The
Schema::getMigrateFromSql()and::getMigrateToSql()methods are deprecated. Compare the schemas using the connection-aware comparator and produce the SQL by passing the resulting diff to the target platform.
The ServerInfoAwareConnection and VersionAwarePlatformDriver interfaces are deprecated. In the next major version,
all drivers and driver connections will be required to implement the APIs aware of the server version.
Relying on dates generated by the database is deprecated. Generate dates within the application.
Reference from ForeignKeyConstraint to its local (referencing) Table is deprecated as well as the following methods:
setLocalTable(),getLocalTable(),getLocalTableName().
When a foreign key is used as part of the Table definition, the table should be used directly. When a foreign key is
used as part of another collection (e.g. SchemaDiff), the collection should store the reference to the key's
referencing table separately.
The following methods implement simple SQL fragments that don't vary across supported platforms. The SQL fragments implemented by these methods should be used as is:
getSqlCommentStartString(),getSqlCommentEndString(),getWildcards(),getAvgExpression(),getCountExpression(),getMaxExpression(),getMinExpression(),getSumExpression(),getMd5Expression(),getSqrtExpression(),getRoundExpression(),getRtrimExpression(),getLtrimExpression(),getUpperExpression(),getLowerExpression(),getNotExpression(),getIsNullExpression(),getIsNotNullExpression(),getBetweenExpression(),getAcosExpression(),getSinExpression(),getPiExpression(),getCosExpression(),getTemporaryTableSQL(),getUniqueFieldDeclarationSQL().
The getListUsersSQL() method is not implemented by any of the supported platforms.
The following methods describe the features consistently implemented across all the supported platforms:
supportsIndexes(),supportsAlterTable(),supportsTransactions(),supportsPrimaryConstraints(),supportsViews(),supportsLimitOffset().
All 3rd-party platform implementations must implement the support for these features as well.
The supportsGettingAffectedRows() method describes a driver-level feature and does not belong to the Platform API.
Relying on the default and the maximum column lengths provided by the DBAL is deprecated.
The following AbstractPlatform methods and their implementations in specific platforms have been deprecated:
getCharMaxLength(),getVarcharDefaultLength(),getVarcharMaxLength(),getBinaryDefaultLength(),getBinaryMaxLength().
If required by the target platform(s), the column length should be specified based on the application logic.
The usage of Comparator::compareSchemas($fromSchema, $toSchema) statically is
deprecated in order to provide a more consistent API.
The usage of Comparator::compare($fromSchema, $toSchema) is deprecated and
replaced by Comparator::compareSchemas($fromSchema, $toSchema) in order to
clarify the purpose of the method.
The usage of Connection::lastInsertId() with a sequence name is deprecated as unsafe in scenarios with multiple
concurrent connections. If a newly inserted row needs to be referenced, it is recommended to generate its identifier
explicitly prior to insertion.
Instead of relying on the deprecated doctrine/cache library, a PSR-6 cache
can now be used for result caching. The usage of Doctrine Cache is deprecated
in favor of PSR-6. The following methods related to Doctrine Cache have been
replaced with PSR-6 counterparts:
| class | old method | new method |
|---|---|---|
Configuration |
setResultCacheImpl() |
setResultCache() |
Configuration |
getResultCacheImpl() |
getResultCache() |
QueryCacheProfile |
setResultCacheDriver() |
setResultCache() |
QueryCacheProfile |
getResultCacheDriver() |
getResultCache() |
The usage of the following schema- and namespace-related methods is deprecated:
AbstractPlatform::getListNamespacesSQL(),AbstractSchemaManager::listNamespaceNames(),AbstractSchemaManager::getPortableNamespacesList(),AbstractSchemaManager::getPortableNamespaceDefinition(),PostgreSQLSchemaManager::getSchemaNames().
Use AbstractSchemaManager::listSchemaNames() instead.
PostgreSQLSchemaManager::getExistingSchemaSearchPaths() and ::determineExistingSchemaSearchPaths() have been marked internal.
OracleSchemaManager::dropAutoincrement() has been marked internal.
Instead of implementing getReservedKeywordsClass(), AbstractPlatform subclasses should implement
createReservedKeywordsList().
The usage of ReservedWordsCommand::setKeywordListClass() has been deprecated. To add or replace a keyword list,
use setKeywordList() instead.
Deprecated $driverOptions argument of PDO\Statement::bindParam() and PDO\SQLSrv\Statement::bindParam()
The usage of the $driverOptions argument of PDO\Statement::bindParam() and PDO\SQLSrv\Statement::bindParam() is deprecated.
To define parameter binding type as ASCII, BINARY or BLOB, use the corresponding ParameterType::* constant.
The usage of Connection::$_schemaManager and Connection::getSchemaManager() is deprecated.
Use Connection::createSchemaManager() instead.
The usage of Connection::$_expr and Connection::getExpressionBuilder() is deprecated.
Use Connection::createExpressionBuilder() instead.
The usage of QueryBuilder::execute() is deprecated. Use either QueryBuilder::executeQuery() or
QueryBuilder::executeStatement(), depending on whether the queryBuilder is a query (SELECT) or a statement (INSERT,
UPDATE, DELETE).
You might also consider the use of the new shortcut methods, such as:
fetchAllAssociative()fetchAllAssociativeIndexed()fetchAllKeyValue()fetchAllNumeric()fetchAssociative()fetchFirstColumn()fetchNumeric()fetchOne()
The usage of the colon prefix when binding named parameters is no longer supported.
The Doctrine\DBAL\Abstraction\Result interface is removed. Use the Doctrine\DBAL\Result class instead.
The Doctrine\DBAL\Types\Type::getDefaultLength() method has been removed as it served no purpose.
The Doctrine\DBAL\DBALException class has been renamed to Doctrine\DBAL\Exception.
Deprecated parameter $idGeneratorType removed and added a new parameter $uniqueConstraints.
Constructor changed like so:
- __construct($name, array $columns = [], array $indexes = [], array $fkConstraints = [], $idGeneratorType = 0, array $options = [])
+ __construct($name, array $columns = [], array $indexes = [], array $uniqueConstraints = [], array $fkConstraints = [], array $options = [])When dropping a database, the DBAL no longer attempts to kill the client sessions that use the database. It's the responsibility of the operator to make sure that the database is not being used.
The Doctrine\DBAL\Schema\Synchronizer\SchemaSynchronizer interface and all its implementations have been removed.
The following methods of the Connection class have been removed:
query().exec().executeUpdate().
The wrapper-level Connection and Statement classes no longer implement the corresponding driver-level interfaces.
The following factory methods of the DBALException class have been removed:
DBALException::invalidPlatformSpecified().DBALException::invalidPdoInstance().
The following classes have been renamed:
PDOMySql\Driver→PDO\MySQL\DriverPDOOracle\Driver→PDO\OCI\DriverPDOPgSql\Driver→PDO\PgSQL\DriverPDOSqlite\Driver→PDO\SQLite\DriverPDOSqlsrv\Driver→PDO\SQLSrv\DriverPDOSqlsrv\Connection→PDO\SQLSrv\ConnectionPDOSqlsrv\Statement→PDO\SQLSrv\Statement
- The
$platformargument of all schema manager constructors is no longer optional. - A new
$platformargument has been added to theDriver::getSchemaManager()method.
- All implementations of the
Driverinterface have been made final. - The
PDO\ConnectionandPDO\Statementclasses have been made final. - The
PDOSqlsrv\ConnectionandPDOSqlsrv\Statementclasses have been made final and no longer extend the corresponding PDO classes. - The
SQLSrv\LastInsertIdclass has been made final.
DBALException::invalidTableName() has been replaced with the InvalidTableName class.
- The
convertException()method has been removed from theDriverinterface. The logic of exception conversion has been moved to theExceptionConverterinterface. The drivers now must implement thegetExceptionConverter()method. - The
driverException()anddriverExceptionDuringQuery()factory methods have been removed from theDBALExceptionclass. - Non-driver exceptions (e.g. exceptions of type
Error) are no longer wrapped in aDBALException.
The following driver-level methods are allowed to throw a Driver\Exception:
Connection::prepare()Connection::lastInsertId()Connection::beginTransaction()Connection::commit()Connection::rollBack()ServerInfoAwareConnection::getServerVersion()Statement::bindParam()Statement::bindValue()Result::rowCount()Result::columnCount()
The driver-level implementations of Connection::query() and Connection::exec() may no longer throw a DBALException.
All drivers must implement the convertException() method which is now part of the Driver interface.
The functionality of pinging the server is no longer supported. Lost connections are now automatically reconnected by Doctrine internally.
AbstractDriverExceptionDriverExceptionPDOConnectionPDOExceptionPDOStatementIBMDB2\DB2ConnectionIBMDB2\DB2DriverIBMDB2\DB2ExceptionIBMDB2\DB2StatementMysqli\MysqliConnectionMysqli\MysqliExceptionMysqli\MysqliStatementOCI8\OCI8ConnectionOCI8\OCI8ExceptionOCI8\OCI8StatementSQLSrv\SQLSrvConnectionSQLSrv\SQLSrvExceptionSQLSrv\SQLSrvStatement
The ServerInfoAwareConnection::requiresQueryForServerVersion() method has been removed as an implementation detail which is the same for all supported drivers.
- The
Doctrine\DBAL\Driver\DriverException::getErrorCode()method is removed. In order to obtain the driver error code, please use::getCode()or::getSQLState(). - The value returned by
Doctrine\DBAL\Driver\PDOException::getSQLState()no longer falls back to the driver error code.
The $database argument is no longer nullable or optional.
Relying on string representation was discouraged and has been removed.
- Removed unused method
Doctrine\DBAL\Schema\AbstractSchemaManager::_getPortableFunctionsList() - Removed unused method
Doctrine\DBAL\Schema\AbstractSchemaManager::_getPortableFunctionDefinition() - Removed unused method
Doctrine\DBAL\Schema\OracleSchemaManager::_getPortableFunctionDefinition() - Removed unused method
Doctrine\DBAL\Schema\SqliteSchemaManager::_getPortableTableIndexDefinition()
The support for DB-generated UUIDs was removed as non-portable. Please generate UUIDs on the application side (e.g. using ramsey/uuid).
- The following methods have been removed as leaking internal implementation details:
::getHost(),::getPort(),::getUsername(),::getPassword().
ConnectionEventArgs::getDriver(),::getDatabasePlatform()and::getSchemaManager()methods have been removed. The connection information can be obtained from the connection which is available via::getConnection().SchemaColumnDefinitionEventArgs::getDatabasePlatform()andSchemaIndexDefinitionEventArgs::getDatabasePlatform()have been removed for the same reason as above.
- The
Doctrine\DBAL\Driver::getDatabase()method has been removed. Please useDoctrine\DBAL\Connection::getDatabase()instead. Doctrine\DBAL\Connection::getDatabase()will always return the name of the database currently connected to, regardless of the configuration parameters and will initialize a database connection if it's not yet established.- A call to
Doctrine\DBAL\Connection::getDatabase(), when connected to an SQLite database, will no longer return the database file path.
The Doctrine\DBAL\Driver::getName() has been removed.
- Removed
json_arraytype and all associated hacks. - Removed
Connection::TRANSACTION_*constants. - Removed
AbstractPlatform::DATE_INTERVAL_UNIT_*andAbstractPlatform::TRIM_*constants. - Removed
AbstractPlatform::getSQLResultCasing(),::prefersSequences()and::supportsForeignKeyOnUpdate()methods. - Removed
PostgreSqlPlatform::getDisallowDatabaseConnectionsSQL()and::getCloseActiveDatabaseConnectionsSQL()methods. - Removed
MysqlSessionInitlistener. - Removed
MySQLPlatform::getCollationFieldDeclaration(). - Removed
AbstractPlatform::getIdentityColumnNullInsertSQL(). - Removed
AbstractPlatform::fixSchemaElementName(). - Removed
Table::addUnnamedForeignKeyConstraint()andTable::addNamedForeignKeyConstraint(). - Removed
Table::renameColumn(). - Removed
SQLParserUtils::getPlaceholderPositions(). - Removed
LoggerChain::addLogger. - Removed
AbstractSchemaManager::getFilterSchemaAssetsExpression(),Configuration::getFilterSchemaAssetsExpression()andConfiguration::getFilterSchemaAssetsExpression(). SQLParserUtils::*_TOKENconstants made private.
The method no longer accepts the $username, $password and $driverOptions arguments. The corresponding values are expected to be passed as the "user", "password" and "driver_options" keys of the $params argument respectively.
This class was deprecated in favor of PrimaryReadReplicaConnection
- The platform-specific portability constants (
Portability\Connection::PORTABILITY_{PLATFORM}) were internal implementation details which are no longer relevant. - The
Portability\Connectionclass no longer extends the DBALConnection. - The
Portability\Classclass has been made final.
- The
Statementinterface no longer extendsResultStatement. - The
ResultStatementinterface has been renamed toResult. - Instead of returning
bool,Statement::execute()now returns aResultthat should be used for fetching the result data and metadata. - The functionality previously available via
Statement::closeCursor()is now available viaResult::free(). The behavior of fetching data from a freed result is no longer portable. In this case, some drivers will returnfalsewhile others may throw an exception.
Additional related changes:
- The
ArrayStatementandResultCacheStatementclasses from theCachepackage have been renamed toArrayResultandCachingResultrespectively and marked@internal.
Statement::rowCount() has been moved to the ResultStatement interface where it belongs by definition.
- The
FetchModeclass and thesetFetchMode()method of theConnectionandStatementinterfaces are removed. - The
Statement::fetch()method is replaced withfetchNumeric(),fetchAssociative()andfetchOne(). - The
Statement::fetchAll()method is replaced withfetchAllNumeric(),fetchAllAssociative()andfechColumn(). - The
Statement::fetchColumn()method is replaced withfetchOne(). - The
Connection::fetchArray()andfetchAssoc()methods are replaced withfetchNumeric()andfetchAssociative()respectively. - The
StatementIteratorclass is removed. The usage of aStatementobject asTraversableis no longer possible. UseiterateNumeric(),iterateAssociative()anditerateColumn()instead. - Fetching data in mixed mode (former
FetchMode::MIXED) is no longer possible.
The statement implementations no longer detect whether $params is a zero- or one-based array. A zero-based numeric array is expected.
- The
Statement::project()method has been removed. Use::executeQuery()and fetch the data from the statement using one of theStatement::fetch*()methods instead.
The error information is available in DriverException thrown in case of an error.
Instead of fetching an object, fetch an array and map it to an object of the desired class.
BC BREAK: Dropped support for the $columnIndex argument in ResultStatement::fetchColumn(), other ResultStatement::fetch*() methods invoked with FetchMode::COLUMN and Connection::fetchColumn().
In order to fetch a column with an index other than 0, use FetchMode::NUMERIC and the array element with the corresponding index.
EchoSQLLogger is no longer available as part of the package.
The support for the SQL Anywhere database platform and the corresponding driver has been removed.
DBAL now requires PostgreSQL 9.4 or newer, support for unmaintained versions has been dropped. If you are using any of the legacy versions, you have to upgrade to a newer PostgreSQL version (9.6+ is recommended).
The following classes have been removed:
Doctrine\DBAL\Platforms\PostgreSqlPlatformDoctrine\DBAL\Platforms\PostgreSQL91PlatformDoctrine\DBAL\Platforms\PostgreSQL92PlatformDoctrine\DBAL\Platforms\Keywords\PostgreSQLKeywordsDoctrine\DBAL\Platforms\Keywords\PostgreSQL91KeywordsDoctrine\DBAL\Platforms\Keywords\PostgreSQL92Keywords
DBAL now requires MariaDB 10.1 or newer, support for unmaintained versions has been dropped. If you are using any of the legacy versions, you have to upgrade to a newer MariaDB version (10.1+ is recommended).
All implementations of the ServerInfoAwareConnection interface have to implement the methods defined in the Connection interface as well.
All implementations of the VersionAwarePlatformDriver interface have to implement the methods defined in the Driver interface as well.
The Doctrine\DBAL\Platforms\MsSQLKeywords class has been removed.
Please use Doctrine\DBAL\Platforms\SQLServerPlatform instead.
This PDO-based IBM DB2 driver (built on top of pdo_ibm extension) has already been unsupported as of 2.5, it has been now removed.
The following class has been removed:
Doctrine\DBAL\Driver\PDOIbm\Driver
DBAL now requires SQL Server 2012 or newer, support for unmaintained versions has been dropped. If you are using any of the legacy versions, you have to upgrade to a newer SQL Server version.
The following classes have been removed:
Doctrine\DBAL\Platforms\SQLServerPlatformDoctrine\DBAL\Platforms\SQLServer2005PlatformDoctrine\DBAL\Platforms\SQLServer2008PlatformDoctrine\DBAL\Platforms\Keywords\SQLServerKeywordsDoctrine\DBAL\Platforms\Keywords\SQLServer2005KeywordsDoctrine\DBAL\Platforms\Keywords\SQLServer2008Keywords
The AbstractSQLServerDriver class and its subclasses no longer implement the VersionAwarePlatformDriver interface.
The Doctrine\DBAL\Version class is no longer available: please refrain from checking the DBAL version at runtime.
In order to share the same PDO instances between DBAL and other components, initialize the connection in DBAL and access it using Connection::getWrappedConnection()->getWrappedConnection().
- The support of
PDO::PARAM_*,PDO::FETCH_*,PDO::CASE_*andPDO::PARAM_INPUT_OUTPUTconstants in the DBAL API is removed. \Doctrine\DBAL\Driver\PDOConnectiondoes not extend\PDOanymore. Please use\Doctrine\DBAL\Driver\PDOConnection::getWrappedConnection()to access the underlyingPDOobject.\Doctrine\DBAL\Driver\PDOStatementdoes not extend\PDOStatementanymore.
Before:
use Doctrine\DBAL\Portability\Connection;
$params = array(
'wrapperClass' => Connection::class,
'fetch_case' => PDO::CASE_LOWER,
);
$stmt->bindValue(1, 1, PDO::PARAM_INT);
$stmt->fetchAll(PDO::FETCH_COLUMN);After:
use Doctrine\DBAL\ColumnCase;
use Doctrine\DBAL\FetchMode;
use Doctrine\DBAL\ParameterType;
use Doctrine\DBAL\Portability\Connection;
$params = array(
'wrapperClass' => Connection::class,
'fetch_case' => ColumnCase::LOWER,
);
$stmt->bindValue(1, 1, ParameterType::INTEGER);
$stmt->fetchAll(FetchMode::COLUMN);The Drizzle project is abandoned and is therefore not supported by Doctrine DBAL anymore.
The dbal:import CLI command has been removed since it only worked with PDO-based drivers by relying on a non-documented behavior of the extension, and it was impossible to make it work with other drivers.
Please use other database client applications for import, e.g.:
- For MySQL and MariaDB:
mysql [dbname] < data.sql. - For PostgreSQL:
psql [dbname] < data.sql. - For SQLite:
sqlite3 /path/to/file.db < data.sql.
Before:
public function convert(string $message, Doctrine\DBAL\Driver\Exception $exception): DriverExceptionAfter:
public function convert(Doctrine\DBAL\Driver\Exception $exception, ?Doctrine\DBAL\Query $query): DriverExceptionThe constructor of Doctrine\DBAL\Exception\DriverException is now @internal.
- all
Configurationmethods are now typed Configuration::setSchemaAssetsFilter()now returnsvoidConfiguration::$_attributeshas been removed; use individual properties in subclasses instead
The SQLAnywhere driver has been deprecated and will be removed from DBAL.
The usage of one-based and other non-zero-based keys when binding positional parameters is deprecated.
It is recommended to not use any array keys so that the value of the parameter array complies with the list<> type constraint.
// This is valid (implicit zero-based parameter indexes)
$conn->fetchNumeric('SELECT ?, ?', [1, 2]);
// This is invalid (one-based parameter indexes)
$conn->fetchNumeric('SELECT ?, ?', [1 => 1, 2 => 2]);
// This is invalid (arbitrary parameter indexes)
$conn->fetchNumeric('SELECT ?, ?', [-31 => 1, 5 => 2]);
// This is invalid (non-sequential parameter indexes)
$conn->fetchNumeric('SELECT ?, ?', [0 => 1, 3 => 2]);Some underlying drivers currently allow skipping prepared statement parameters. For instance:
$conn->fetchOne('SELECT ?');
// NULLThis behavior should not be relied upon and may change in future versions.
The usage of the colon prefix when binding named parameters is deprecated.
$sql = 'SELECT * FROM users WHERE name = :name OR username = :username';
$stmt = $conn->prepare($sql);
// The usage of the leading colon is deprecated
$stmt->bindValue(':name', $name);
// Only the parameter name should be passed
$stmt->bindValue('username', $username);
$stmt->execute();In php 8.0, the method signatures of two PDO classes which are extended by DBAL have changed. This affects the following classes:
Doctrine\DBAL\Driver\PDOConnectionDoctrine\DBAL\Driver\PDOStatement
Code that extends either of the classes needs to be adjusted in order to function properly on php 8. The updated method signatures are:
PDOConnection::query(?string $query = null, ?int $fetchMode = null, mixed ...$fetchModeArgs)PDOStatement::setFetchMode($mode, ...$args)PDOStatement::fetchAll($mode = null, ...$args)
The usage of the Doctrine\DBAL\Abstraction\Result interface is deprecated. In DBAL 3.0, the statement result at the wrapper level will be represented by the Doctrine\DBAL\Result class.
The corresponding getDisallowDatabaseConnectionsSQL() and getCloseActiveDatabaseConnectionsSQL methods
of the PostgreSqlPlatform class have been deprecated.
The Doctrine\DBAL\Schema\Synchronizer\SchemaSynchronizer interface and all its implementations are deprecated.
The usage of the wrapper Connection and Statement classes as implementations of the Driver\Connection and Driver\Statement interfaces is deprecated.
- The
executeUpdate()method has been deprecated in favor ofexecuteStatement(). - The
query()method has been deprecated in favor ofexecuteQuery(). - The
exec()method has been deprecated in favor ofexecuteStatement().
Note that PrimaryReplicaConnection::query() ensures connection to the primary instance while executeQuery() doesn't.
Depending on the desired behavior:
- If the statement doesn't have to be executed on the primary instance, use
executeQuery(). - If the statement has to be executed on the primary instance and yields rows (e.g.
SELECT), prependexecuteQuery()withensureConnectedToPrimary(). - Otherwise, use
executeStatement().
The following PDO-related classes outside of the PDO namespace have been deprecated in favor of their counterparts in the PDO namespace:
PDOMySql\Driver→PDO\MySQL\DriverPDOOracle\Driver→PDO\OCI\DriverPDOPgSql\Driver→PDO\PgSQL\DriverPDOSqlite\Driver→PDO\SQLite\DriverPDOSqlsrv\Driver→PDO\SQLSrv\DriverPDOSqlsrv\Connection→PDO\SQLSrv\ConnectionPDOSqlsrv\Statement→PDO\SQLSrv\Statement
- The
ExceptionConverterDriverinterface and the usage of theconvertException()method on theDriverobjects are deprecated. - The
driverException()anddriverExceptionDuringQuery()factory methods of theDBALExceptionclass are deprecated. - Relying on the wrapper layer handling non-driver exceptions is deprecated.
DBALException::invalidPlatformType()is deprecated as unused as of v2.7.0.DBALException::invalidPdoInstance()as passing a PDO instance via configuration is deprecated.
fixSchemaElementName().getSQLResultCasing().prefersSequences().supportsForeignKeyOnUpdate().
The ServerInfoAwareConnection::requiresQueryForServerVersion() method has been deprecated as an implementation detail which is the same for almost all supported drivers.
- Driver connection objects can be only created by the corresponding drivers.
- Wrapper connection objects can be only created by the driver manager.
- The driver and wrapper connection objects can be only created by the corresponding connection objects.
Additionally, the SQLSrv\LastInsertId class has been marked internal.
The wrapper connection will automatically handle the lost connection if the driver supports reporting it.
The DriverException::getErrorCode() is deprecated as redundant and inconsistently supported by drivers. Use ::getCode() or ::getSQLState() instead.
The non-interface methods of driver-level classes have been marked internal:
OCI8Connection::getExecuteMode()OCI8Statement::convertPositionalToNamedPlaceholders()
The Doctrine\DBAL\DBALException class has been deprecated in favor of Doctrine\DBAL\Exception.
The following classes under the Driver namespace have been deprecated in favor of their consistently named counterparts:
DriverException→ExceptionAbstractDriverException→AbstractExceptionIBMDB2\DB2Driver→IBMDB2\DriverIBMDB2\DB2Connection→IBMDB2\ConnectionIBMDB2\DB2Statement→IBMDB2\StatementMysqli\MysqliConnection→Mysqli\ConnectionMysqli\MysqliStatement→Mysqli\StatementOCI8\OCI8Connection→OCI8\ConnectionOCI8\OCI8Statement→OCI8\StatementSQLSrv\SQLSrvConnection→SQLSrv\ConnectionSQLSrv\SQLSrvStatement→SQLSrv\StatementPDOConnection→PDO\ConnectionPDOStatement→PDO\Statement
All driver-specific exception classes have been deprecated:
IBMDB2\DB2ExceptionMysqli\MysqliExceptionOCI8\OCI8ExceptionPDOExceptionSQLSrv\SQLSrvException
A driver-level exception should be only identified as a subtype of Driver\Exception.
Internal driver-level exception implementations may use Driver\AbstractException as the base class.
Driver-specific exception handling has to be implemented either in the driver or based on the type of the Driver implementation.
The Driver\AbstractException class has been marked internal.
Consumers of the Connection class should not rely on connection parameters stored in the connection object. If needed, they should be obtained from a different source, e.g. application configuration.
- The usage of
Doctrine\DBAL\Driver::getDatabase()is deprecated. Please useDoctrine\DBAL\Connection::getDatabase()instead. - The behavior of the SQLite connection returning the database file path as the database is deprecated and shouldn't be relied upon.
The platform-specific portability mode flags are meant to be used only by the portability layer internally to optimize the user-provided mode for the current database platform.
The Doctrine\DBAL\Connections\MasterSlaveConnection class is renamed to Doctrine\DBAL\Connections\PrimaryReadReplicaConnection.
In addition its configuration parameters master, slaves and keepSlave are renamed to primary, replica and keepReplica.
Before:
$connection = DriverManager::getConnection(
'wrapperClass' => 'Doctrine\DBAL\Connections\MasterSlaveConnection',
'driver' => 'pdo_mysql',
'master' => array('user' => '', 'password' => '', 'host' => '', 'dbname' => ''),
'slaves' => array(
array('user' => 'replica1', 'password', 'host' => '', 'dbname' => ''),
array('user' => 'replica2', 'password', 'host' => '', 'dbname' => ''),
),
'keepSlave' => true,
));
$connection->connect('slave');
$connection->connect('master');
$connection->isConnectedToMaster();
After:
$connection = DriverManager::getConnection(array(
'wrapperClass' => 'Doctrine\DBAL\Connections\PrimaryReadReplicaConnection',
'driver' => 'pdo_mysql',
'primary' => array('user' => '', 'password' => '', 'host' => '', 'dbname' => ''),
'replica' => array(
array('user' => 'replica1', 'password', 'host' => '', 'dbname' => ''),
array('user' => 'replica2', 'password', 'host' => '', 'dbname' => ''),
)
'keepReplica' => true,
));
$connection->ensureConnectedToReplica();
$connection->ensureConnectedToPrimary();
$connection->isConnectedToPrimary();
The ArrayStatement and ResultCacheStatement classes are deprecated. In a future major release they will be renamed and marked internal as implementation details of the caching layer.
- The
ResultStatementinterface is deprecated. Use theDriver\ResultandAbstraction\Resultinterfaces instead. ResultStatement::closeCursor()is deprecated in favor ofResult::free().
- The
FetchModeclass and thesetFetchMode()method of theConnectionandStatementinterfaces are deprecated. - The
Statement::fetch()method is deprecated in favor ofResult::fetchNumeric(),::fetchAssociative()and::fetchOne(). - The
Statement::fetchAll()method is deprecated in favor ofResult::fetchAllNumeric(),::fetchAllAssociative()and::fetchFirstColumn(). - The
Statement::fetchColumn()method is deprecated in favor ofResult::fetchOne(). - The
Connection::fetchArray()andfetchAssoc()method are deprecated in favor offetchNumeric()andfetchAssociative()respectively. - The
StatementIteratorclass and the usage of aStatementobject asTraversableis deprecated in favor ofResult::iterateNumeric(),::iterateAssociative()and::iterateColumn(). - Fetching data in mixed mode (
FetchMode::MIXED) is deprecated.
The Connection::project() method is deprecated. Implement data transformation outside of DBAL.
The Statement::errorCode() and errorInfo() methods are deprecated. The error information is available via exceptions.
The EchoSQLLogger class is deprecated. Implement your logger with the desired logic.
- PostgreSQL 9.3 and older
- MariaDB 10.0 and older
- SQL Server 2008 and older
- SQL Anywhere 12 and older
- Drizzle
- Azure SQL Database
- PDO-based IBM DB2 driver
- Drizzle MySQL driver
The sharding functionality in DBAL has been effectively unmaintained for a long time.
The usage of the Doctrine\DBAL\Version class is deprecated as internal implementation detail. Please refrain from checking the DBAL version at runtime.
The usage of the andX() and orX() methods of the ExpressionBuilder class has been deprecated. Use and() and or() instead.
- The usage of the
add()andaddMultiple()methods of theCompositeExpressionclass has been deprecated. Usewith()instead, which returns a new instance. In the future, theadd*()methods will be removed and the class will be effectively immutable. - The usage of the
CompositeExpressionconstructor has been deprecated. Use theand()/or()factory methods.
Calling the select(), addSelect(), groupBy() and addGroupBy() methods with an array argument is deprecated.
The usage of the getDriver(), getDatabasePlatform() and getSchemaManager() methods of the ConnectionEventArgs class has been deprecated. Obtain the underlying connection via getConnection() and call the corresponding methods on the connection instance.
The usage of the getDatabasePlatform() method of the SchemaColumnDefinitionEventArgs class has been deprecated. Obtain the underlying connection via getConnection() and call the corresponding method on the connection instance.
The usage of the getHost(), getPort(), getUsername() and getPassword() methods of the Connection class has been deprecated as they leak implementation details.
Passing multiple SQL statements as an array to SchemaAlterTableAddColumnEventArgs::addSql() and the same method in other SchemaEventArgs-based classes is deprecated. Pass each statement as an individual argument instead.
Instead of passing a string, pass a one-element array.
In order to create a database, always pass the database name.
The following methods have been deprecated as unused:
AbstractSchemaManager::_getPortableFunctionsList(),AbstractSchemaManager::_getPortableFunctionDefinition(),OracleSchemaManager::_getPortableFunctionDefinition(),SqliteSchemaManager::_getPortableTableIndexDefinition().
- The usage of NULL to indicate empty
$usernameor$passwordwhen callingconnect()is deprecated. Use an empty string instead.
Method Doctrine\DBAL\Platforms::_getAlterTableIndexForeignKeySQL() has been deprecated as no longer used.
Property Doctrine\DBAL\Driver\OCI8\OCI8Statement::$_PARAM has been deprecated as not used.
Relying on the name of the driver is discouraged. For referencing the driver, use its class name.
The usage of user-provided PDO instance is deprecated. The known use cases are:
- Persistent PDO connections. DBAL 3.0 will supported establishing persistent connections, therefore, providing a pre-created persistent PDO connection will be no longer needed.
- Sharing
PDOinstance between DBAL and legacy components. In order to share a PDO instance, initialize the connection in DBAL and access it usingConnection::getWrappedConnection()->getWrappedConnection().
They are converted to SQL literals (e.g. escaped). Clients must now specify default values in their initial form, not in the form of an SQL literal (e.g. escaped).
Before:
$column->setDefault('Foo\\\\Bar\\\\Baz');
After:
$column->setDefault('Foo\\Bar\\Baz');
The constants for built-in types have been moved from Doctrine\DBAL\Types\Type to a separate class Doctrine\DBAL\Types\Types.
Some of the constants were renamed in the process:
TARRAY->ARRAYDATE->DATE_MUTABLEDATETIME->DATETIME_MUTABLEDATETIMETZ->DATETIMETZ_MUTABLETIME->TIME_MUTABLE
The Doctrine\DBAL\Driver\SQLSrv\SQLSrvStatement::LAST_INSERT_ID_SQL constant has been deprecated and will be made private in 3.0.
The constants in Doctrine\DBAL\SQLParserUtils have been deprecated and will be made private in 3.0.
The Doctrine\DBAL\Logging\LoggerChain::addLogger method has been deprecated. Inject list of loggers via constructor instead.
Calls to Statement::fetchColumn() with an invalid column index currently return NULL. In the future, such calls will result in a exception.
Deprecated Configuration::getFilterSchemaAssetsExpression(), ::setFilterSchemaAssetsExpression() and AbstractSchemaManager::getFilterSchemaAssetsExpression().
Regular expression-based filters are hard to extend by combining together. Instead, you may use callback-based filers via ::getSchemaAssetsFilter() and ::getSchemaAssetsFilter(). Callbacks can use regular expressions internally.
This method was never used by DBAL internally. It is now deprecated and will be removed in DBAL 3.0.
Relying on string representation is discouraged and will be removed in DBAL 3.0.
The NULL value of the $offset argument in AbstractPlatform::(do)?ModifyLimitQuery() methods is deprecated. If explicitly used in the method call, the absence of the offset should be indicated with a 0.
The dbal:import CLI command has been deprecated since it only works with PDO-based drivers by relying on a non-documented behavior of the extension, and it's impossible to make it work with other drivers.
Please use other database client applications for import, e.g.:
- For MySQL and MariaDB:
mysql [dbname] < data.sql. - For PostgreSQL:
psql [dbname] < data.sql. - For SQLite:
sqlite3 /path/to/file.db < data.sql.
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) to generate UUIDs on the application side.
- The usage of binary fields whose length exceeds the maximum field size on a given platform is deprecated. Use binary fields of a size which fits all target platforms, or use blob explicitly instead.
The dependency on doctrine/common package has been removed. DBAL now depends on doctrine/cache and doctrine/event-manager instead. If you are using any other component from doctrine/common package, you will have to add an explicit dependency to your composer.json.
Corrected exception thrown by Doctrine\DBAL\Platforms\SQLAnywhere16Platform::getAdvancedIndexOptionsSQL()
This method now throws SPL UnexpectedValueException instead of accidentally throwing Doctrine\Common\Proxy\Exception\UnexpectedValueException.
Doctrine\DBAL\Platforms\AbstractPlatform::DATE_INTERVAL_UNIT_* constants were moved into Doctrine\DBAL\Platforms\DateIntervalUnit class without the DATE_INTERVAL_UNIT_ prefix.
Doctrine\DBAL\Platforms\AbstractPlatform::TRIM_* constants were moved into Doctrine\DBAL\Platforms\TrimMode class without the TRIM_ prefix.
Doctrine\DBAL\Connection::TRANSACTION_* were moved into Doctrine\DBAL\TransactionIsolationLevel class without the TRANSACTION_ prefix.
- When calling
Doctrine\DBAL\Driver\Statementmethods, instead ofPDO::PARAM_*constants,Doctrine\DBAL\ParameterTypeconstants should be used. - When calling
Doctrine\DBAL\Driver\ResultStatementmethods, instead ofPDO::FETCH_*constants,Doctrine\DBAL\FetchModeconstants should be used. - When configuring
Doctrine\DBAL\Portability\Connection, instead ofPDO::CASE_*constants,Doctrine\DBAL\ColumnCaseconstants should be used. - Usage of
PDO::PARAM_INPUT_OUTPUTinDoctrine\DBAL\Driver\Statement::bindValue()is deprecated. - Usage of
PDO::FETCH_FUNCinDoctrine\DBAL\Driver\ResultStatement::fetch()is deprecated. - Calls to
\PDOStatementmethods on a\Doctrine\DBAL\Driver\PDOStatementinstance (e.g.fetchObject()) are deprecated.
Doctrine\DBAL\Driver\ResultStatement::fetch()now has 3 arguments instead of 1, respectingPDO::fetch()signature.
Before:
Doctrine\DBAL\Driver\ResultStatement::fetch($fetchMode);
After:
Doctrine\DBAL\Driver\ResultStatement::fetch($fetchMode, $cursorOrientation, $cursorOffset);
Doctrine\DBAL\Driver\ResultStatement::fetchAll()now has 3 arguments instead of 1, respectingPDO::fetchAll()signature.
Before:
Doctrine\DBAL\Driver\ResultStatement::fetchAll($fetchMode);
After:
Doctrine\DBAL\Driver\ResultStatement::fetch($fetchMode, $fetchArgument, $ctorArgs);
URL-style DSNs (e.g. mysql://foo@bar:localhost/db) are now assumed to be percent-encoded
in order to allow certain special characters in usernames, paswords and database names. If
you are using a URL-style DSN and have a username, password or database name containing a
percentage sign, you need to update your DSN. If your password is, say, foo%foo, it
should be encoded as foo%25foo.
When adding indexes to Doctrine\DBAL\Schema\Table via addIndex() or addUniqueIndex(),
duplicate indexes are not silently ignored/dropped anymore (based on semantics, not naming!).
Duplicate indexes are considered indexes that pass isFullfilledBy() or overrules()
in Doctrine\DBAL\Schema\Index.
This is required to make the index renaming feature introduced in 2.5.0 work properly and avoid
issues in the ORM schema tool / DBAL schema manager which pretends users from updating
their schemas and migrate to DBAL 2.5.*.
Additionally it offers more flexibility in declaring indexes for the user and potentially fixes
related issues in the ORM.
With this change, the responsibility to decide which index is a "duplicate" is completely deferred
to the user.
Please also note that adding foreign key constraints to a table via addForeignKeyConstraint(),
addUnnamedForeignKeyConstraint() or addNamedForeignKeyConstraint() now first checks if an
appropriate index is already present and avoids adding an additional auto-generated one eventually.
When mapping time type field to PHP's DateTime instance all unused date fields are
reset to UNIX epoch (i.e. 1970-01-01). This might break any logic which relies on comparing
DateTime instances with date fields set to the current date.
Use ! format prefix (see http://php.net/manual/en/datetime.createfromformat.php) for parsing
time strings to prevent having different date fields when comparing user input and DateTime
instances as mapped by Doctrine.
The methods addIndex() and addUniqueIndex() in Doctrine\DBAL\Schema\Table
have an additional, optional parameter. If you override these methods, you should
add this new parameter to the declaration of your overridden methods.
The visibility of the property $_platform in Doctrine\DBAL\Connection
was changed from protected to private. If you have subclassed Doctrine\DBAL\Connection
in your application and accessed $_platform directly, you have to change the code
portions to use getDatabasePlatform() instead to retrieve the underlying database
platform.
The reason for this change is the new automatic platform version detection feature,
which lazily evaluates the appropriate platform class to use for the underlying database
server version at runtime.
Please also note, that calling getDatabasePlatform() now needs to establish a connection
in order to evaluate the appropriate platform class if Doctrine\DBAL\Connection is not
already connected. Under the following circumstances, it is not possible anymore to retrieve
the platform instance from the connection object without having to do a real connect:
Doctrine\DBAL\Connectionwas instantiated without theplatformconnection parameter.Doctrine\DBAL\Connectionwas instantiated without theserverVersionconnection parameter.- The underlying driver is "version aware" and can provide different platform instances for different versions.
- The underlying driver connection is "version aware" and can provide the database server version without having to query for it.
If one of the above conditions is NOT met, there is no need for Doctrine\DBAL\Connection
to do a connect when calling getDatabasePlatform().
Before 2.5 the DateTime type always required a specific format, defined in
$platform->getDateTimeFormatString(), which could cause quite some troubles
on platforms that had various microtime precision formats. Starting with 2.5
whenever the parsing of a date fails with the predefined platform format,
the date_create() function will be used to parse the date.
This could cause some troubles when your date format is weird and not parsed
correctly by date_create, however since databases are rather strict on dates
there should be no problem.
The pdo_ibm driver is buggy and does not work well with Doctrine. Therefore it will no
longer be supported and has been removed from the Doctrine\DBAL\DriverManager drivers
map. It is highly encouraged to to use ibm_db2 driver instead if you want to connect
to an IBM DB2 database as it is much more stable and secure.
If for some reason you have to utilize the pdo_ibm driver you can still use the driverClass
connection parameter to explicitly specify the Doctrine\DBAL\Driver\PDOIbm\Driver class.
However be aware that you are doing this at your own risk and it will not be guaranteed that
Doctrine will work as expected.
If you have custom classes that implement the constraint interface, you have to implement
an additional method getQuotedColumns now. This method is used to build proper constraint
SQL for columns that need to be quoted, like keywords reserved by the specific platform used.
The method has to return the same values as getColumns only that those column names that
need quotation have to be returned quoted for the given platform.
Before 2.3 the Oracle Session Init did not care about the numeric character of the Session. This could lead to problems on non english locale systems that required a comma as a floating point seperator in Oracle. Since 2.3, using the Oracle Session Init on connection start the client session will be altered to set the numeric character to ".,":
ALTER SESSION SET NLS_NUMERIC_CHARACTERS = '.,'
See DBAL-345 for more details.
The query related methods including but not limited to executeQuery, exec, query, and executeUpdate now wrap the driver exceptions such as PDOException with DBALException to add more debugging information such as the executed SQL statement, and any bound parameters.
If you want to retrieve the driver specific exception, you can retrieve it by calling the
getPrevious() method on DBALException.
Before:
catch(\PDOException $ex) {
// ...
}
After:
catch(\Doctrine\DBAL\DBALException $ex) {
$pdoException = $ex->getPrevious();
// ...
}
This method only worked on MySQL and it is considered unsafe on MySQL to use SET NAMES UTF-8 instead of setting the charset directly on connection already. Replace this behavior with the connection charset option:
Before:
$conn = DriverManager::getConnection(array(..));
$conn->setCharset('UTF8');
After:
$conn = DriverManager::getConnection(array('charset' => 'UTF8', ..));
Doctrine\DBAL\Schema\Table#renameColumn() was removed, because it drops and recreates the column instead. There is no fix available, because a schema diff cannot reliably detect if a column was renamed or one column was created and another one dropped.
You should use explicit SQL ALTER TABLE statements to change columns names.
The Filter Schema assets expression is not wrapped in () anymore for the regexp automatically.
Before:
$config->setFilterSchemaAssetsExpression('foo');
After:
$config->setFilterSchemaAssetsExpression('(foo)');
If you are creating a new MySQL Table through the Doctrine API, charset/collate are now set to 'utf8'/'utf8_unicode_ci' by default. Previously the MySQL server defaults were used.
Both methods now accept an optional last parameter $types with binding types of the values passed. This can potentially break child classes that have overwritten one of these methods.
Doctrine\DBAL\Connection#executeQuery() got a new last parameter "QueryCacheProfile $qcp"
The Driver statement was split into a ResultStatement and the normal statement extending from it. This separates the configuration and the retrieval API from a statement.
The MsSqlPlatform was renamed to SQLServerPlatform, the MsSqlSchemaManager was renamed to SQLServerSchemaManager.
DBAL 2.1 and before were actually only compatible to SQL Server 2008, not earlier versions. Still other parts of the platform did use old features instead of newly introduced datatypes in SQL Server 2005. Starting with DBAL 2.2 you can pick the Doctrine abstraction exactly matching your SQL Server version.
The PDO SqlSrv driver now uses the new SQLServer2008Platform as default platform.
This platform uses new features of SQL Server as of version 2008. This also includes a switch
in the used fields for "text" and "blob" field types to:
"text" => "VARCHAR(MAX)"
"blob" => "VARBINARY(MAX)"
Additionally SQLServerPlatform in DBAL 2.1 and before used "DATE", "TIME" and "DATETIME2" for dates.
This types are only available since version 2008 and the introduction of an explicit
SQLServer 2008 platform makes this dependency explicit.
An SQLServer2005Platform was also introduced to differentiate the features between
versions 2003, earlier and 2005.
With this change the SQLServerPlatform now throws an exception for using limit queries
with an offset, since SQLServer 2003 and lower do not support this feature.
To use the old SQL Server Platform, because you are using SQL Server 2003 and below use the following configuration code:
use Doctrine\DBAL\DriverManager;
use Doctrine\DBAL\Platforms\SQLServerPlatform;
use Doctrine\DBAL\Platforms\SQLServer2005Platform;
// You are using SQL Server 2003 or earlier
$conn = DriverManager::getConnection(array(
'driver' => 'pdo_sqlsrv',
'platform' => new SQLServerPlatform()
// .. additional parameters
));
// You are using SQL Server 2005
$conn = DriverManager::getConnection(array(
'driver' => 'pdo_sqlsrv',
'platform' => new SQLServer2005Platform()
// .. additional parameters
));
// You are using SQL Server 2008
$conn = DriverManager::getConnection(array(
'driver' => 'pdo_sqlsrv',
// 2008 is default platform
// .. additional parameters
));