Note about upgrading: Doctrine uses static and runtime mechanisms to raise awareness about deprecated code.
- Use of
@deprecated
docblock 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 Sequence::isAutoIncrementsFor()
method has been removed.
The Table::setSchemaConfig()
and ::_getMaxIdentifierLength()
methods and the Table::$_schemaConfig
property have
been removed.
The AbstractAsset::_setName()
method has been removed.
The following components have been removed:
- The
KeywordList
class and all its subclasses. - The methods
AbstractPlatform::createReservedKeywordsList()
and::getReservedKeywordsList()
. - The
AbstractPlatform::$_keywords
property.
Prior to this change, DBAL would automatically quote reserved keywords and, as a side effect, preserve their case on platforms that adhere to the SQL-92 standard (i.e., preserve lowercase identifiers on Oracle and IBM DB2, and uppercase ones on PostgreSQL).
With this change, DBAL will:
- Normalize the case of unquoted identifiers to match the behavior of the target database platform:
- Oracle and IBM DB2 – uppercase.
- PostgreSQL – lowercase.
- All other platforms – no modification.
- Consistently quote all identifiers in SQL, regardless of whether they are keywords or not.
To preserve lowercase identifiers on Oracle and IBM DB2 or uppercase identifiers on PostgreSQL, quote the identifiers explicitly.
The AbstractPlatform::quoteIdentifier()
and Connection::quoteIdentifier()
methods have been removed.
The Table::removeForeignKey()
and ::removeUniqueConstraint()
methods have been removed.
The CREATE_INDEXES
and CREATE_FOREIGNKEYS
constants have been removed from the AbstractPlatform
class.
A new method getColumnName()
has been added to the Result
interface and must be implemented by
all drivers and middleware.
- Upgrade to MariaDB 10.5 or later.
- Upgrade to MySQL 8.0 or later.
- Upgrade to Postgres 12 or later.
The AbstractAsset::getShortestName()
method has been deprecated. Use AbstractAsset::getName()
instead.
The Sequence::isAutoIncrementsFor()
method has been deprecated.
Using the following objects with an empty name is deprecated: Column
, View
, Sequence
, Identifier
.
Using the following objects with a qualified name is deprecated: Column
, ForeignKeyConstraint
, Index
, Schema
,
UniqueConstraint
. If the object name contains a dot, the name should be quoted.
Using the following objects with a name that has more than one qualifier is deprecated: Sequence
, Table
, View
.
The name should be unqualified or contain one qualifier.
The AbstractAsset
class has been marked as internal.
The Table::setSchemaConfig()
method and $_schemaConfig
property have been deprecated. Pass a TableConfiguration
instance to the constructor instead.
The Table::_getMaxIdentifierLength()
method has been deprecated.
Setting object name via AbstractAsset::_setName()
has been deprecated. Pass the name to the AbstractAsset
constructor instead.
In order to build SQL identifiers, use AbstractPlatform::quoteSingleIdentifier()
.
The use of DBAL as the source for platform-specific reserved keyword lists has been deprecated. The following components have been deprecated:
- The
KeywordList
class and all its subclasses. - The methods
AbstractPlatform::createReservedKeywordsList()
and::getReservedKeywordsList()
. - The
AbstractPlatform::$_keywords
property.
Please refer to the official documentation provided by the respective database vendor for up-to-date information on reserved keywords.
Additionally, the MySQL84Platform
class has been deprecated. Use the MySQLPlatform
class instead.
The current object name parser implicitly quotes identifiers in the following cases:
- If the object name is a reserved keyword (e.g.,
select
). - If an unquoted identifier is preceded by a quoted identifier (e.g.,
"inventory".product
).
As a result, the original case of such identifiers is preserved on platforms that respect the SQL-92 standard (i.e., identifiers are not upper-cased on Oracle and IBM DB2, and not lower-cased on PostgreSQL). This behavior is deprecated.
If preserving the original case of an identifier is required, please explicitly quote it (e.g., select
→ "select"
).
Additionally, the current parser exhibits the following defects:
- It ignores a missing closing quote in a quoted identifier (e.g.,
"inventory
). - It allows names with more than two identifiers (e.g.,
warehouse.inventory.product
) but only uses the first two, ignoring the remaining ones. - If a quoted identifier contains a dot, it incorrectly treats the part before the dot as a qualifier, despite the identifier being quoted.
Relying on the above behaviors is deprecated.
The AbstractPlatform::quoteIdentifier()
and Connection::quoteIdentifier()
methods have been deprecated.
Use the corresponding quoteSingleIdentifier()
method individually for each part of a qualified name instead.
Dropping columns that are referenced by constraints is deprecated. The constraints should be dropped first.
The usage of Table::removeForeignKey()
and ::removeUniqueConstraint()
is deprecated. Use Table::dropForeignKey()
and ::dropUniqueConstraint()
respectively instead.
On PHP 8.4, if you call getNativeConnection()
on a connection established through one of the PDO drivers,
you will get an instance of the new PDO subclasses, e.g. Pdo\Mysql
or Pdo\Ppgsql
instead of just PDO
.
However, this currently does not apply to persistent connections. See php/php-src#16314 for details.
The query cache format has been changed to address the issue where a cached result with no rows would miss the metadata. This change is not backwards compatible. If you are using the query cache, you should clear the cache before the upgrade.
The TableDiff
methods getModifiedColumns()
and getRenamedColumns()
have been merged into a single
method getChangedColumns()
. Use this method instead.
- Upgrade to MariaDB 10.5 or later.
- Upgrade to MySQL 8.0 or later.
- Upgrade to Postgres 12 or later.
Driver and middleware results need to implement a new method getColumnName()
that gives access to the
column name. Not doing so is deprecated.
getColumnTypeSQLSnippets()
,getDatabaseNameSQL()
.
The methods AbstractPlatform::getReadLockSQL()
, ::getWriteLockSQL()
and ::getForUpdateSQL()
have been removed
Use QueryBuilder::forUpdate()
as a replacement for the latter.
BigIntType
casts values retrieved from the database to int if they're inside
the integer range of PHP. Previously, those values were always cast to string.
The following types don't accept or return DateTimeImmutable
instances anymore:
DateTimeType
DateTimeTzType
DateType
TimeType
VarDateTimeType
As a consequence, the following type classes don't extend their mutable counterparts anymore:
DateTimeImmutableType
DateTimeTzImmutableType
DateImmutableType
TimeImmutableType
VarDateTimeImmutableType
The following methods have been removed:
Result::fetch()
Result::fetchAll()
Connection::exec()
Connection::executeUpdate()
Connection::query()
Additionally, the FetchMode
class has been removed.
DBAL ships with a new and configurable DSN parser that can be used to parse a
database URL into connection parameters understood by DriverManager
.
$connection = DriverManager::getConnection(
['url' => 'mysql://my-user:t0ps3cr3t@my-host/my-database']
);
$dsnParser = new DsnParser(['mysql' => 'pdo_mysql']);
$connection = DriverManager::getConnection(
$dsnParser->parse('mysql://my-user:t0ps3cr3t@my-host/my-database')
);
Use the enum ArrayParameterType
instead.
The serverVersion
connection parameter must consist of 3 numbers:
-'serverVersion' => '8.0'
+'serverVersion' => '8.0.31'
Previously, it was necessary to prefix the serverVersion
parameter with
mariadb-
when using MariaDB. Doing so is now considered invalid, and you
should prefer using the version as returned by SELECT VERSION();
-'serverVersion' => 'mariadb-10.9.3'
+'serverVersion' => '10.9.3-MariaDB-1'
The functionality of automatically dropping the foreign keys referencing the tables being dropped has been removed.
DBAL does not register functions for SQLite anymore. The following functions which were previously provided by DBAL have been removed:
-
locate()
: SQLite provides the functioninstr()
that behaves similarly. UseAbstractPlatform::getLocateExpression()
if you need a portable solution. -
mod()
: SQLite provides a%
operator for modulo calculations. UseAbstractPlatform::getModExpression()
if you need a portable solution. Since version 3.35.0 SQLite also provides amod()
function if math functions have been enabled. -
sqrt()
: Upgrade to SQLite 3.35.0 and compile SQLite with math functions to get a nativesqrt()
function. If you need asqrt()
implementation for an earlier release of SQLite, you can polyfill it.// pdo_sqlite driver $connection->getNativeConnection() ->sqliteCreateFunction('sqrt', \sqrt(...), 1); // sqlite3 driver $connection->getNativeConnection() ->createFunction('sqrt', \sqrt(...), 1);
The userDefinedFunctions
driver option has also been removed. If you want
to register your own functions, do so by calling sqliteCreateFunction()
or createFunction()
on the PDO or SQLite3 connection.
The following Table
methods have been removed:
changeColumn()
,getForeignKeyColumns()
,getPrimaryKeyColumns()
,hasPrimaryKey()
.
The following SchemaException
class constants have been removed:
TABLE_DOESNT_EXIST
,TABLE_ALREADY_EXISTS
,COLUMN_DOESNT_EXIST
,COLUMN_ALREADY_EXISTS
,INDEX_DOESNT_EXIST
,INDEX_ALREADY_EXISTS
,SEQUENCE_DOENST_EXIST
,SEQUENCE_ALREADY_EXISTS
,INDEX_INVALID_NAME
,FOREIGNKEY_DOESNT_EXIST
,CONSTRAINT_DOESNT_EXIST
,NAMESPACE_ALREADY_EXISTS
.
The Doctrine\DBAL\Exception
and the Doctrine\DBAL\Schema\SchemaException
classes are now interfaces.
This method's name was spelled incorrectly. Use isFulfilledBy
instead.
When connecting to a PostgreSQL server, the driver will no longer connect to the "postgres" database by default.
The "default_dbname" parameter of the wrapper Connection
is no longer supported.
When determining the database platform, if an attempt to connect using the provided configuration fails, the wrapper connection will no longer fall back to a configuration without the database name.
Driver name aliases are no longer supported.
The support for the "platform" parameter of the wrapper Connection
has been removed.
The "unique" and "check" column properties are no longer supported.
The DBAL no longer provides default values for precision and scale of decimal columns.
The Connection::update()
and ::delete()
methods no longer enforce a non-empty WHERE clause. If modification
of all table rows should not be allowed, it should be implemented in the application code.
The following methods have been removed:
Doctrine\DBAL\Statement::bindParam()
,Doctrine\DBAL\Driver\Statement::bindParam()
.
The $type
parameter of the driver-level Statement::bindValue()
has been made required.
The value of parameter type used in the wrapper layer (e.g. in Connection::executeQuery()
or Statement::bindValue()
) can no longer be NULL
.
The following classes have been converted to enums:
Doctrine\DBAL\ColumnCase
,Doctrine\DBAL\LockMode
,Doctrine\DBAL\ParameterType
,Doctrine\DBAL\ArrayParameterType
,Doctrine\DBAL\TransactionIsolationLevel
,Doctrine\DBAL\Platforms\DateIntervalUnit
,Doctrine\DBAL\Platforms\TrimMode
.Doctrine\DBAL\Query\ForUpdate\ConflictResolutionMode
The corresponding class constants are now instances of their enum type.
The DBAL no longer generates default constraint names using the table name and column name. The name is now generated by the database.
SqlitePlatform
=>SQLitePlatform
SqliteSchemaManager
=>SQLiteSchemaManager
getTinyIntTypeDeclarationSQL()
,getMediumIntTypeDeclarationSQL()
.
getColumnsFieldDeclarationListSQL()
,getCustomTypeDeclarationSQL()
,getDefaultSchemaName()
,getIdentitySequenceName()
,getIndexFieldDeclarationListSQL()
,supportsCreateDropDatabase()
,usesSequenceEmulatedIdentityColumns()
.
The argument of Configuration::setSchemaAssetsFilter()
is now required and non-nullable.
The following Column
class properties and methods have been removed:
$_customSchemaOptions
,setCustomSchemaOption()
,hasCustomSchemaOption()
,getCustomSchemaOption()
,setCustomSchemaOptions()
,getCustomSchemaOptions()
.
The following classes and constants have been removed:
ArrayType
,ObjectType
,Types::ARRAY
,Types::OBJECT
.
The Driver::getSchemaManager()
method has been removed.
The AbstractSchemaManager::getDatabasePlatform()
and ::listTableDetails()
methods have been removed.
The following interfaces and classes have been removed:
Doctrine\DBAL\Schema\Visitor
,Doctrine\DBAL\Schema\NamespaceVisitor
,Doctrine\DBAL\Schema\AbstractVisitor
.
The following methods have been removed:
Doctrine\DBAL\Schema\Schema::visit()
,Doctrine\DBAL\Schema\Table::visit()
,Doctrine\DBAL\Schema\Sequence::visit()
.
The RemoveNamespacedAssets
schema visitor has been removed.
The following components have been removed:
- The
dbal:reserved-words
console command. - The
ReservedWordsCommand
andReservedKeywordsValidator
classes. - The
KeywordList::getName()
method.
The AbstractPlatform::supportsForeignKeyConstraints()
method has been removed.
The DBAL generates DDL for foreign keys regardless of the MySQL storage engines used by the table that owns the foreign key constraint.
The AbstractPlatform::getStringLiteralQuoteCharacter()
and ::getIdentifierQuoteCharacter()
methods
have been removed.
The AbstractPlatform::CREATE_INDEXES
and ::CREATE_FOREIGNKEYS
constants have been deprecated
as they no longer have any effect on the behavior of the AbstractPlatform::getCreateTableSQL()
method.
The $createFlags
parameter of AbstractPlatform::getCreateTableSQL()
has been removed.
The CreateSchemaSqlCollector
and DropSchemaSqlCollector
classes have been removed.
Starting a transaction inside another transaction with
Doctrine\DBAL\Connection::beginTransaction()
now always results in
savepoints being used.
In case your platform does not support savepoints, you will have to rework your application logic so as to avoid nested transaction blocks.
Since it is no longer possible to configure whether transaction nesting is emulated with savepoints or not, configuring that behavior has no effect and it is deprecated to attempt to change it or to know how it is configured. As a result, the following methods are deprecated:
Connection::setNestTransactionsWithSavepoints()
Connection::getNestTransactionsWithSavepoints()
Instead of using SERIAL*
column types for autoincrement
columns, the DBAL will now use
the GENERATED BY DEFAULT AS IDENTITY
clause.
The upgrade to DBAL 4 will require manual migration of the database schema. See the documentation for more details.
The documentation explains how the console tools can be bootstrapped for standalone usage.
Passing $database
to the following methods is no longer supported:
AbstractSchemaManager::listSequences()
,AbstractSchemaManager::listTableColumns()
,AbstractSchemaManager::listTableForeignKeys()
.
The following schema introspection methods have been removed:
AbstractPlatform::getListTablesSQL()
,AbstractPlatform::getListTableColumnsSQL()
,AbstractPlatform::getListTableIndexesSQL()
,AbstractPlatform::getListTableForeignKeysSQL()
,AbstractPlatform::getListTableConstraintsSQL()
.
The following abstract methods in the AbstractSchemaManager
class have been declared as abstract
:
selectDatabaseColumns()
,selectDatabaseIndexes()
,selectDatabaseForeignKeys()
,getDatabaseTableOptions()
.
Every non-abstract schema manager class must implement them in order to satisfy the API.
The signatures of the methods returning the number of affected rows changed as returning int|string
instead of int
.
If the number is greater than PHP_INT_MAX
, the number of affected rows may be returned as a string if the driver supports it.
Use collation
instead.
As a consequence, only types extending JsonType
or that type itself can have
the jsonb
platform option set.
Database column comments no longer contain type comments added by DBAL.
If you use doctrine/migrations
, it should generate a migration dropping those
comments from all columns that have them.
As a consequence, introspecting a table no longer guarantees getting the same
column types that were used when creating that table.
The AbstractPlatform::prefersIdentityColumns()
method has been removed.
The Doctrine\DBAL\Schema\Visitor\Graphviz
class has been removed.
Oracle 12c (12.2.0.1) and older are not supported anymore.
MariaDB 10.4.2 and older are not supported anymore. The following classes have been removed:
Doctrine\DBAL\Platforms\MariaDb1027Platform
Doctrine\DBAL\Platforms\MariaDB1043Platform
Doctrine\DBAL\Platforms\Keywords\MariaDb102Keywords
MySQL 5.6 and older are not supported anymore. The following classes have been merged into their respective parent classes:
Doctrine\DBAL\Platforms\MySQL57Platform
Doctrine\DBAL\Platforms\Keywords\MySQL57Keywords
Postgres 9 is not actively supported anymore. The following classes have been merged into their respective parent class:
Doctrine\DBAL\Platforms\PostgreSQL100Platform
Doctrine\DBAL\Platforms\Keywords\PostgreSQL100Keywords
The following methods are removed:
AbstractPlatform::hasNativeJsonType()
AbstractPlatform::hasNativeGuidType()
AbstractPlatform::isCommentedDoctrineType()
AbstractPlatform::initializeCommentedDoctrineTypes()
AbstractPlatform::markDoctrineTypeCommented()
Type::requiresSQLCommentHint()
The protected property AbstractPlatform::$doctrineTypeComments
is removed as
well.
The Type::canRequireSQLConversion()
method has been removed.
The wrapper-level Connection::getWrappedConnection()
method has been removed. The Connection::connect()
method
has been made protected
and now must return the underlying driver-level connection.
Driver and middleware connections must implement getNativeConnection()
now. This new method replaces several accessors
that have been removed:
Doctrine\DBAL\Driver\PDO\Connection::getWrappedConnection()
Doctrine\DBAL\Driver\PDO\SQLSrv\Connection::getWrappedConnection()
Doctrine\DBAL\Driver\Mysqli\Connection::getWrappedResourceHandle()
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()
,AbstractSchemaMVersionAwarePlatformDriveranager::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 following QueryBuilder
methods have been removed:
execute()
,getState()
,getType()
,getConnection()
.
The following QueryBuilder
constants have been removed:
SELECT
,DELETE
,UPDATE
,INSERT
,STATE_DIRTY
,STATE_CLEAN
.
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 TableDiff::$name
property and TableDiff::getName()
method have been removed.
The TableDiff::$newName
property and the TableDiff::getNewName()
method have been removed.
The SchemaDiff
class no longer accepts or exposes a reference to the original schema.
- The
$fromColumn
parameter of theColumnDiff
constructor has been made required. - The
$oldColumnName
property and thegetOldColumnName()
method 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:
PostgreSQL94Platform
andPostgreSQL94Keywords
.SQLServer2012Platform
andSQLServer2012Keywords
.
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 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 Comparator::compare()
, ::diffTable()
and ::diffColumn()
methods have been removed.
The ColumnDiff::hasChanged()
method has been removed.
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::createSchema()
,AbstractSchemaManager::listNamespaceNames()
,AbstractSchemaManager::getPortableNamespacesList()
,AbstractSchemaManager::getPortableNamespaceDefinition()
,PostgreSQLSchemaManager::getSchemaNames()
.
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$table
parameter, 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 noSELECT
expressions have been provided.
- 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
AbstractPlatform
methods 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.
- 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.
SchemaAlterTableAddColumnEventArgs::addSql()
and the same method in otherSchemaEventArgs
-based classes no longer accept an array of SQL statements. They accept a variadic string.
- Method
Doctrine\DBAL\Schema\AbstractSchemaManager::_getPortableViewDefinition()
no longer optionally returns false. It will always return aDoctrine\DBAL\Schema\View
instance. - Property
Doctrine\DBAL\Schema\Table::$_primaryKeyName
is 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 acceptsnull
for$database
argument.
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.
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
$expression
argument in::getCountExpression()
, - the
$decimals
argument in::getRoundExpression()
, - the
$seconds
argument in::getDateAddSecondsExpression()
, - the
$seconds
argument in::getDateSubSecondsExpression()
, - the
$minutes
argument in::getDateAddMinutesExpression()
, - the
$minutes
argument in::getDateSubMinutesExpression()
, - the
$hours
argument in::getDateAddHourExpression()
, - the
$hours
argument in::getDateAddHourExpression()
, - the
$days
argument in::getDateAddDaysExpression()
, - the
$days
argument in::getDateSubDaysExpression()
, - the
$weeks
argument in::getDateAddWeeksExpression()
, - the
$weeks
argument in::getDateSubWeeksExpression()
, - the
$months
argument in::getDateAddMonthExpression()
, - the
$months
argument in::getDateSubMonthExpression()
, - the
$quarters
argument in::getDateAddQuartersExpression()
, - the
$quarters
argument in::getDateSubQuartersExpression()
, - the
$years
argument in::getDateAddYearsExpression()
, - the
$years
argument 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.
Note that OraclePlatform::getSubstringExpression()
will no longer automatically format the values of the $start
and $length
parameters as integers. The caller of the method is responsible for the validity of the SQL expressions.
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()
, ::bindValue()
and ::execute()
no longer return a boolean value. They will throw an exception in case of failure.
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 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.
- Binary fields whose length exceeds the maximum field size on a given platform are no longer represented as
BLOB
s. 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 usage of AbstractPlatform::getReadLockSQL()
, ::getWriteLockSQL()
and ::getForUpdateSQL()
is deprecated as
this API is not portable. Use QueryBuilder::forUpdate()
as a replacement for the latter.
AbstractMySQLPlatform::getColumnTypeSQLSnippets()
has been deprecated in favor ofAbstractMySQLPlatform::getColumnTypeSQLSnippet()
.AbstractMySQLPlatform::getDatabaseNameSQL()
has been deprecated without replacement.- Not passing a database name to
AbstractMySQLPlatform::getColumnTypeSQLSnippet()
has been deprecated.
QueryBuilder::resetQueryParts()
has been deprecated.
Resetting individual query parts through the generic resetQueryPart()
method has been deprecated as well.
However, several replacements have been put in place depending on the $queryPartName
parameter:
$queryPartName |
suggested replacement |
---|---|
'select' |
Call select() with a new set of columns. |
'distinct' |
distinct(false) |
'where' |
resetWhere() |
'groupBy' |
resetGroupBy() |
'having' |
resetHaving() |
'orderBy' |
resetOrderBy() |
'values' |
Call values() with a new set of values. |
The usage of QueryBuilder::getQueryPart()
and ::getQueryParts()
is deprecated. The query parts
are implementation details and should not be relied upon.
DBAL 4 will change the way the schema manager is created. To opt in to the new behavior, please configure the schema manager factory:
$configuration = new Configuration();
$configuration->setSchemaManagerFactory(new DefaultSchemaManagerFactory());
$connection = DriverManager::getConnection(
[/* your parameters */],
$configuration,
);
If you use a custom platform implementation, please make sure it implements
the createSchemaManager()
method . Otherwise, the connection will fail to
create a schema manager.
DBAL ships with a new and configurable DSN parser that can be used to parse a
database URL into connection parameters understood by DriverManager
.
$connection = DriverManager::getConnection(
['url' => 'mysql://my-user:t0ps3cr3t@my-host/my-database']
);
$dsnParser = new DsnParser(['mysql' => 'pdo_mysql']);
$connection = DriverManager::getConnection(
$dsnParser->parse('mysql://my-user:t0ps3cr3t@my-host/my-database')
);
Use the corresponding constants on ArrayParameterType
instead. Please be aware that
ArrayParameterType
will be a native enum type in DBAL 4.
Extension of the library behavior via Doctrine Event Manager has been deprecated.
The following methods and properties have been deprecated:
AbstractPlatform::$_eventManager
,AbstractPlatform::getEventManager()
,AbstractPlatform::setEventManager()
,Connection::$_eventManager
,Connection::getEventManager()
.
Subscription to the postConnect
event has been deprecated. Use one of the following replacements for the standard
event listeners or implement a custom middleware instead.
The following postConnect
event listeners have been deprecated:
OracleSessionInit
. UseDoctrine\DBAL\Driver\OCI8\Middleware\InitializeSession
.SQLiteSessionInit
. UseDoctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware\EnableForeignKeys
.SQLSessionInit
. Implement a custom middleware.
Subscription to the following events has been deprecated:
onTransactionBegin
,onTransactionCommit
,onTransactionRollBack
.
The upgrade path will depend on the use case:
- If you need to extend the behavior of only the actual top-level transactions (not the ones emulated via savepoints), implement a driver middleware.
- If you need to extend the behavior of the top-level and nested transactions, either implement a driver middleware or implement a custom wrapper connection.
Subscription to the following events has been deprecated:
onSchemaColumnDefinition
,onSchemaIndexDefinition
.
Use a custom schema manager instead.
Subscription to the following events has been deprecated:
onSchemaCreateTable
,onSchemaCreateTableColumn
,onSchemaDropTable
,onSchemaAlterTable
,onSchemaAlterTableAddColumn
,onSchemaAlterTableRemoveColumn
,onSchemaAlterTableChangeColumn
,onSchemaAlterTableRenameColumn
.
The upgrade path will depend on the use case:
- If you are using the events to modify the behavior of the platform, you should extend the platform class and implement the corresponding logic in the sub-class.
- If you are using the events to modify the arguments processed by the platform (e.g. modify the table definition
before the platform generates the
CREATE TABLE
DDL), you should do the needed modifications before calling the corresponding platform or schema manager method.
Relying on the availability of the LOCATE()
on SQLite deprecated. SQLite does not provide that function natively,
but the function INSTR()
can be a drop-in replacement in most situations. Use
AbstractPlatform::getLocateExpression()
if you need a portable solution.
Using SchemaDiff::toSql()
to generate SQL representing the diff has been deprecated.
Use AbstractPlatform::getAlterSchemaSQL()
instead.
SchemaDiff::toSaveSql()
has been deprecated without a replacement.
Relying on the schema diff tracking foreign keys referencing the tables that have been dropped is deprecated. Before dropping a table referenced by foreign keys, drop the foreign keys first.
Instead of funneling custom functions through the userDefinedFunctions
option, use getNativeConnection()
to access the wrapped PDO connection and register your custom functions directly.
$connection = DriverManager::getConnection([
'driver' => 'pdo_sqlite',
'path' => '/path/to/file.db',
'driverOptions' => [
'userDefinedFunctions' => [
'my_function' => ['callback' => [SomeClass::class, 'someMethod'], 'numArgs' => 2],
],
]
]);
$connection = DriverManager::getConnection([
'driver' => 'pdo_sqlite',
'path' => '/path/to/file.db',
]);
$connection->getNativeConnection()
->sqliteCreateFunction('my_function', [SomeClass::class, 'someMethod'], 2);
The hasPrimaryKey()
method has been deprecated. Use getPrimaryKey()
and check if the return value is not null.
The getPrimaryKeyColumns()
method has been deprecated. Use getPrimaryKey()
and Index::getColumns()
instead.
The getForeignKeyColumns()
method has been deprecated. Use getForeignKey()
and ForeignKeyConstraint::getLocalColumns()
instead.
The changeColumn()
method has been deprecated. Use modifyColumn()
instead.
Relying on the error code of SchemaException
is deprecated. In order to handle a specific type of exception,
catch the corresponding exception class instead.
Error Code | Class |
---|---|
TABLE_DOESNT_EXIST |
TableDoesNotExist |
TABLE_ALREADY_EXISTS |
TableAlreadyExists |
COLUMN_DOESNT_EXIST |
ColumnDoesNotExist |
COLUMN_ALREADY_EXISTS |
ColumnAlreadyExists |
INDEX_DOESNT_EXIST |
IndexDoesNotExist |
INDEX_ALREADY_EXISTS |
IndexAlreadyExists |
SEQUENCE_DOENST_EXIST |
SequenceDoesNotExist |
SEQUENCE_ALREADY_EXISTS |
SequenceAlreadyExists |
FOREIGNKEY_DOESNT_EXIST |
ForeignKeyDoesNotExist |
CONSTRAINT_DOESNT_EXIST |
UniqueConstraintDoesNotExist |
NAMESPACE_ALREADY_EXISTS |
NamespaceAlreadyExists |
Relying on a fallback connection used to determine the database platform while connecting to a non-existing database has been deprecated. Either use an existing database name in connection parameters or omit the database name if the platform and the server configuration allow that.
This method's name was spelled incorrectly. Use isFulfilledBy
instead.
Relying on the DBAL connecting to the "postgres" database by default is deprecated. Unless you want to have the server determine the default database for the connection, specify the database name explicitly.
The "default_dbname" parameter of the wrapper Connection
has been deprecated. Use "dbname" instead.
The "platform" parameter of the wrapper Connection
has been deprecated. Use a driver middleware that would instantiate
the platform instead.
Relying on driver name aliases in connection parameters has been deprecated. Use the actual driver names instead.
The "unique" and "check" column properties have been deprecated. Use unique constraints to define unique columns.
Relying on the default precision and scale of decimal columns provided by the DBAL is deprecated. When declaring decimal columns, specify the precision and scale explicitly.
The Comparator::diffTable()
method has been deprecated in favor of Comparator::compareTables()
and TableDiff::isEmpty()
.
Instead of having to check whether the diff is equal to the boolean false
, you can optionally check
if the returned table diff is empty.
$diff = $comparator->diffTable($oldTable, $newTable);
// mandatory check
if ($diff !== false) {
// we have a diff
}
$diff = $comparator->compareTables($oldTable, $newTable);
// optional check
if (! $diff->isEmpty()) {
// we have a diff
}
Not passing $fromTable
to the TableDiff
constructor has been deprecated.
The TableDiff::$name
property and the TableDiff::getName()
method have been deprecated as well. In order to obtain
the name of the table that the diff describes, use TableDiff::getOldTable()
.
Renaming tables via setting the $newName
property on a TableDiff
and passing it to AbstractPlatform::alterTable()
is deprecated. The implementations of AbstractSchemaManager::alterTable()
should use AbstractPlatform::renameTable()
instead.
The TableDiff::$newName
property and the TableDiff::getNewName()
method have been deprecated.
The following Comparator
methods have been marked as internal:
columnsEqual()
,diffForeignKey()
,diffIndex()
.
The diffColumn()
method has been deprecated. Use diffTable()
instead.
The public properties of the SchemaDiff
class have been marked as internal. Use the following corresponding methods
instead:
Property | Method |
---|---|
$newNamespaces |
getCreatedSchemas() |
$removedNamespaces |
getDroppedSchemas() |
$newTables |
getCreatedTables() |
$changedTables |
getAlteredTables() |
$removedTables |
getDroppedTables() |
$newSequences |
getCreatedSequences() |
$changedSequences |
getAlteredSequence() |
$removedSequences |
getDroppedSequences() |
The public properties of the TableDiff
class have been marked as internal. Use the following corresponding methods
instead:
Property | Method |
---|---|
$addedColumns |
getAddedColumns() |
$changedColumns |
getModifiedColumns() |
$removedColumns |
getDroppedColumns() |
$renamedColumns |
getRenamedColumns() |
$addedIndexes |
getAddedIndexes() |
$changedIndexes |
getModifiedIndexes() |
$removedIndexes |
getDroppedIndexes() |
$renamedIndexes |
getRenamedIndexes() |
$addedForeignKeys |
getAddedForeignKeys() |
$changedForeignKeys |
getModifiedForeignKeys() |
$removedForeignKeys |
getDroppedForeignKeys() |
The $fromColumn
and $column
properties of the ColumnDiff
class have been marked as internal. Use the
getOldColumn()
and getNewColumn()
methods instead.
The ColumnDiff::$changedProperties
property and the hasChanged()
method have been deprecated. Use one of the
following ColumnDiff
methods in order to check if a given column property has changed:
hasTypeChanged()
,hasLengthChanged()
,hasPrecisionChanged()
,hasScaleChanged()
,hasUnsignedChanged()
,hasFixedChanged()
,hasNotNullChanged()
,hasDefaultChanged()
,hasAutoIncrementChanged()
,hasCommentChanged()
.
The $oldColumnName
property and the getOldColumnName()
method of the ColumnDiff
class have been deprecated.
Make sure the $fromColumn
argument is passed to the ColumnDiff
constructor and use the $fromColumn
property
instead.
The constructors of the following classes have been marked as internal:
SchemaDiff
,TableDiff
,ColumnDiff
.
These classes can be instantiated only by schema comparators. The signatures of the constructors may change in future versions.
The SchemaDiff::$fromSchema
property has been deprecated.
The AbstractSchemaManager::_execSql()
method has been marked as internal. It will not be available in 4.0.
The following AbstractSchemaManager
methods has been deprecated:
listTableDetails()
. UseintrospectTable()
instead,createSchema()
. UseintrospectSchema()
instead.
The following methods have been deprecated:
Doctrine\DBAL\Statement::bindParam()
,Doctrine\DBAL\Driver\Statement::bindParam()
.
Use the corresponding bindValue()
instead.
Not passing $type
to the driver-level Statement::bindParam()
and ::bindValue()
is deprecated.
Pass the type corresponding to the parameter being bound.
Passing $params
to the driver-level Statement::execute()
and the wrapper-level Statement::executeQuery()
and Statement::executeStatement()
methods has been deprecated.
Bind parameters using Statement::bindParam()
or Statement::bindValue()
instead.
- The
QueryBuilder::getState()
method has been deprecated as the builder state is an internal concern. - Relying on the type of the query being built by using
QueryBuilder::getType()
has been deprecated. If necessary, track the type of the query being built outside of the builder. - The
QueryBuilder::getConnection()
method has been deprecated. Use the connection used to instantiate the builder instead.
The following QueryBuilder
constants related to the above methods have been deprecated:
SELECT
,DELETE
,UPDATE
,INSERT
,STATE_DIRTY
,STATE_CLEAN
.
The Connection::ARRAY_PARAM_OFFSET
constant has been marked as internal. It will be removed in 4.0.
Omit the type or use ParameterType::STRING
instead.
Passing assets to the following AbstractPlatform
methods and parameters has been deprecated:
- The
$table
parameter ofgetDropTableSQL()
, - The
$table
parameter ofgetDropTemporaryTableSQL()
, - The
$index
and$table
parameters ofgetDropIndexSQL()
, - The
$constraint
and$table
parameters ofgetDropConstraintSQL()
, - The
$foreignKey
and$table
parameters ofgetDropForeignKeySQL()
, - The
$sequence
parameter ofgetDropSequenceSQL()
, - The
$table
parameter ofgetCreateConstraintSQL()
, - The
$table
parameter ofgetCreatePrimaryKeySQL()
, - The
$table
parameter ofgetCreateForeignKeySQL()
.
Passing assets to the following AbstractSchemaManager
methods and parameters has been deprecated:
- The
$index
and$table
parameters ofdropIndex()
, - The
$table
parameter ofdropConstraint()
, - The
$foreignKey
and$table
parameters ofdropForeignKey()
.
Pass a string representing the quoted asset name instead.
The following methods have been marked internal as they are not designed to be used from outside the platform classes:
getAdvancedForeignKeyOptionsSQL()
,getColumnCharsetDeclarationSQL()
,getColumnCollationDeclarationSQL()
,getColumnDeclarationSQL()
,getCommentOnColumnSQL()
,getDefaultValueDeclarationSQL()
,getForeignKeyDeclarationSQL()
,getForeignKeyReferentialActionSQL()
,getIndexDeclarationSQL()
,getInlineColumnCommentSQL()
,supportsColumnCollation()
,supportsCommentOnStatement()
,supportsInlineColumnComments()
,supportsPartialIndexes()
.
The following methods have been deprecated as they do not represent any platform-level abstraction:
getCustomTypeDeclarationSQL()
,getIndexFieldDeclarationListSQL()
,getColumnsFieldDeclarationListSQL()
.
usesSequenceEmulatedIdentityColumns()
andgetIdentitySequenceName()
have been deprecated since the fact of emulation of identity columns and the underlying sequence name are internal platform-specific implementation details.getDefaultSchemaName()
has been deprecated since it's not used to implement any of the portable APIs.supportsCreateDropDatabase()
has been deprecated. Try callingAbstractSchemaManager::createDatabase
and/or::dropDatabase()
to see if the corresponding operations are supported by the current database platform or implement conditional logic based on the platform class name.
Deprecated SqlitePlatform::getTinyIntTypeDeclarationSQL()
and ::getMediumIntTypeDeclarationSQL()
methods.
The methods have been deprecated since they are implemented only by the SQLite platform, and the column types they implement are not portable across the rest of the supported platforms.
Use SqlitePlatform::getSmallIntTypeDeclarationSQL()
and ::getIntegerTypeDeclarationSQL()
respectively instead.
Not passing an argument to Configuration::setSchemaAssetsFilter()
and passing NULL
as the value of $callable
has been deprecated. In order to disable filtering, pass a callable that always returns true.
Custom schema options have been deprecated since they effectively duplicate the functionality of platform options.
The following Column
class properties and methods have been deprecated:
$_customSchemaOptions
,setCustomSchemaOption()
,hasCustomSchemaOption()
,getCustomSchemaOption()
,setCustomSchemaOptions()
,getCustomSchemaOptions()
.
Use platform options instead.
The array
and object
column types have been deprecated since they use PHP built-in serialization. Without additional
configuration, which the API of these types doesn't allow, the usage of built-in serialization may lead to
security issues.
The following classes and constants have been deprecated:
ArrayType
,ObjectType
,Types::ARRAY
,Types::OBJECT
.
Use JSON for storing unstructured data.
The Driver::getSchemaManager()
method has been deprecated. Use AbstractPlatform::createSchemaManager()
instead.
The ConsoleRunner
class has been deprecated. Use Symfony Console documentation
to bootstrap a command-line application.
The following interfaces and classes have been deprecated:
Visitor
,NamespaceVisitor
,AbstractVisitor
.
The following methods have been deprecated:
Schema::visit()
,Table::visit()
,Sequence::visit()
.
Instead of having schema objects call the visitor API, call the API of the schema objects.
The RemoveNamespacedAssets
schema visitor and the usage of namespaced database object names with the platforms
that don't support them have been deprecated.
The following components have been deprecated:
- The
dbal:reserved-words
console command. - The
ReservedWordsCommand
andReservedKeywordsValidator
classes. - The
KeywordList::getName()
method.
Use the documentation on the used database platform(s) instead.
The CreateSchemaSqlCollector
and DropSchemaSqlCollector
classes have been deprecated in favor of
CreateSchemaObjectsSQLBuilder
and DropSchemaObjectsSQLBuilder
respectively.
Deprecated calling AbstractPlatform::getCreateTableSQL()
with any of the CREATE_INDEXES
and CREATE_FOREIGNKEYS
flags unset.
Not setting the CREATE_FOREIGNKEYS
flag and unsetting the CREATE_INDEXES
flag when calling
AbstractPlatform::getCreateTableSQL()
has been deprecated. The table should be always created with indexes.
In order to build the statements that create multiple tables referencing each other via foreign keys,
use AbstractPlatform::getCreateTablesSQL()
.
The AbstractPlatform::supportsForeignKeyConstraints()
method has been deprecated. All platforms should support
foreign key constraints.
Relying on the DBAL not generating DDL for foreign keys on MySQL engines other than InnoDB is deprecated. Define foreign key constraints only if they are necessary.
The AbstractPlatform::getStringLiteralQuoteCharacter()
and ::getIdentifierQuoteCharacter()
methods
have been deprecated. Use ::quoteStringLiteral()
and ::quoteIdentifier()
to quote string literals and identifiers
respectively.
The AbstractSchemaManager::getDatabasePlatform()
method has been deprecated. Use Connection::getDatabasePlatform()
instead.
Passing date interval parameters to the following AbstractPlatform
methods as integer has been deprecated:
- the
$seconds
argument in::getDateAddSecondsExpression()
, - the
$seconds
parameter in::getDateSubSecondsExpression()
, - the
$minutes
parameter in::getDateAddMinutesExpression()
, - the
$minutes
parameter in::getDateSubMinutesExpression()
, - the
$hours
parameter in::getDateAddHourExpression()
, - the
$hours
parameter in::getDateAddHourExpression()
, - the
$days
parameter in::getDateAddDaysExpression()
, - the
$days
parameter in::getDateSubDaysExpression()
, - the
$weeks
parameter in::getDateAddWeeksExpression()
, - the
$weeks
parameter in::getDateSubWeeksExpression()
, - the
$months
parameter in::getDateAddMonthExpression()
, - the
$months
parameter in::getDateSubMonthExpression()
, - the
$quarters
parameter in::getDateAddQuartersExpression()
, - the
$quarters
parameter in::getDateSubQuartersExpression()
, - the
$years
parameter in::getDateAddYearsExpression()
, - the
$years
parameter in::getDateSubYearsExpression()
.
Use the strings representing numeric SQL literals instead (e.g. '1'
instead of 1
).
Starting a transaction inside another transaction with
Doctrine\DBAL\Connection::beginTransaction()
without enabling transaction
nesting with savepoints beforehand is deprecated.
Transaction nesting with savepoints can be enabled with
$connection->setNestTransactionsWithSavepoints(true);
In case your platform does not support savepoints, you will have to rework your application logic so as to avoid nested transaction blocks.
In addition to the formal deprecation introduced in DBAL 3.2, the library will now emit a deprecation message at runtime if the string or binary column length is omitted, but it's required by the target database platform.
The AbstractPlatform::getVarcharTypeDeclarationSQL()
method has been deprecated.
Use AbstractPlatform::getStringTypeDeclarationSQL()
instead.
Passing $database
to the following methods has been deprecated:
AbstractSchemaManager::listSequences()
,AbstractSchemaManager::listTableColumns()
,AbstractSchemaManager::listTableForeignKeys()
.
Only introspection of the current database will be supported in DBAL 4.0.
The following schema introspection methods have been deprecated:
AbstractPlatform::getListTablesSQL()
,AbstractPlatform::getListTableColumnsSQL()
,AbstractPlatform::getListTableIndexesSQL()
,AbstractPlatform::getListTableForeignKeysSQL()
.
The following schema introspection methods have been marked as internal:
AbstractPlatform::getListDatabasesSQL()
,AbstractPlatform::getListSequencesSQL()
,AbstractPlatform::getListViewsSQL()
.
The queries used for schema introspection are an internal implementation detail of the DBAL.
This undocumented option is deprecated in favor of collation
.
This method is unused by the DBAL since 2.0.
This method is not useful for the DBAL anymore, and will be removed in 4.0.
As a consequence, depending on the name of a type being json
for jsonb
to
be used for the Postgres platform is deprecated in favor of extending
Doctrine\DBAL\Types\JsonType
.
You can use Type::getTypeRegistry()->lookupName($type)
instead.
AbstractPlatform::hasNative*Type()
and Type::requiresSQLCommentHint()
DBAL no longer needs column comments to ensure proper diffing. Note that all the methods should probably have been marked as internal as these comments were an implementation detail of the DBAL.
Consumers should call Type::convertToDatabaseValueSQL()
and Type::convertToPHPValueSQL()
regardless of the type.
The documentation explains how the console tools can be bootstrapped for standalone usage.
The method ConsoleRunner::printCliConfigTemplate()
is deprecated because it was only useful in the context of the
doctrine-dbal
binary.
This class is not part of the database abstraction provided by the library and will be removed in DBAL 4.
This option does not have any effect anymore and will be removed in DBAL 4.
Since Type::requiresSQLCommentTypeHint()
already allows determining whether a
type should result in SQL columns with a type hint in their comments, the
following methods are deprecated:
AbstractPlatform::isCommentedDoctrineType()
AbstractPlatform::initializeCommentedDoctrineTypes()
AbstractPlatform::markDoctrineTypeCommented()
The protected property AbstractPlatform::$doctrineTypeComments
is deprecated
as well.
IBM DB2 10.5 and older won't be supported in DBAL 4. Consider upgrading to IBM DB2 11.1 or later.
Oracle 12c (12.2.0.1) won't be supported in DBAL 4. Consider upgrading to Oracle 18c (12.2.0.2) or later.
MariaDB 10.2.6 and older won't be supported in DBAL 4. Consider upgrading to MariaDB 10.2.7 or later. The following classes have been deprecated:
Doctrine\DBAL\Platforms\MariaDb1027Platform
Doctrine\DBAL\Platforms\Keywords\MariaDb102Keywords
MySQL 5.6 and older won't be actively supported in DBAL 4. Consider upgrading to MySQL 5.7 or later. The following classes have been deprecated:
Doctrine\DBAL\Platforms\MySQL57Platform
Doctrine\DBAL\Platforms\Keywords\MySQL57Keywords
Postgres 9 won't be actively supported in DBAL 4. Consider upgrading to Postgres 10 or later. The following classes have been deprecated:
Doctrine\DBAL\Platforms\PostgreSQL100Platform
Doctrine\DBAL\Platforms\Keywords\PostgreSQL100Keywords
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.
We have been working on phasing out doctrine/cache
, and 3.2.0 allows to use
psr/cache
instead. To help calling our own internal APIs in a unified way, we
also wrap doctrine/cache
implementations with a psr/cache
adapter.
Using cache keys containing characters reserved by psr/cache
will result in
an exception. The characters are the following: {}()/\@:
.
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 Configuration
methods getSQLLogger()
and setSQLLogger()
have been deprecated as well.
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
Schema
using "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.
PostgreSQL94Platform
andPostgreSQL94Keywords
. UsePostgreSQLPlatform
andPostgreSQLKeywords
instead.SQLServer2012Platform
andSQLServer2012Keywords
. UseSQLServerPlatform
andSQLServerKeywords
instead.
Deprecated schema comparison APIs that don't account for the current database connection and the database platform
- Instantiation of the
Comparator
class 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.
Whether to use identity columns should be decided by the application developer. For example, based on the set of supported database platforms.
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\Driver
PDOOracle\Driver
→PDO\OCI\Driver
PDOPgSql\Driver
→PDO\PgSQL\Driver
PDOSqlite\Driver
→PDO\SQLite\Driver
PDOSqlsrv\Driver
→PDO\SQLSrv\Driver
PDOSqlsrv\Connection
→PDO\SQLSrv\Connection
PDOSqlsrv\Statement
→PDO\SQLSrv\Statement
- The
$platform
argument of all schema manager constructors is no longer optional. - A new
$platform
argument has been added to theDriver::getSchemaManager()
method.
- All implementations of the
Driver
interface have been made final. - The
PDO\Connection
andPDO\Statement
classes have been made final. - The
PDOSqlsrv\Connection
andPDOSqlsrv\Statement
classes have been made final and no longer extend the corresponding PDO classes. - The
SQLSrv\LastInsertId
class has been made final.
DBALException::invalidTableName()
has been replaced with the InvalidTableName
class.
- The
convertException()
method has been removed from theDriver
interface. The logic of exception conversion has been moved to theExceptionConverter
interface. The drivers now must implement thegetExceptionConverter()
method. - The
driverException()
anddriverExceptionDuringQuery()
factory methods have been removed from theDBALException
class. - 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.
AbstractDriverException
DriverException
PDOConnection
PDOException
PDOStatement
IBMDB2\DB2Connection
IBMDB2\DB2Driver
IBMDB2\DB2Exception
IBMDB2\DB2Statement
Mysqli\MysqliConnection
Mysqli\MysqliException
Mysqli\MysqliStatement
OCI8\OCI8Connection
OCI8\OCI8Exception
OCI8\OCI8Statement
SQLSrv\SQLSrvConnection
SQLSrv\SQLSrvException
SQLSrv\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_array
type 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
MysqlSessionInit
listener. - 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::*_TOKEN
constants 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\Connection
class no longer extends the DBALConnection
. - The
Portability\Class
class has been made final.
- The
Statement
interface no longer extendsResultStatement
. - The
ResultStatement
interface has been renamed toResult
. - Instead of returning
bool
,Statement::execute()
now returns aResult
that 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 returnfalse
while others may throw an exception.
Additional related changes:
- The
ArrayStatement
andResultCacheStatement
classes from theCache
package have been renamed toArrayResult
andCachingResult
respectively and marked@internal
.
Statement::rowCount()
has been moved to the ResultStatement
interface where it belongs by definition.
- The
FetchMode
class and thesetFetchMode()
method of theConnection
andStatement
interfaces are removed. - The
Statement::fetch()
method is replaced withfetchNumeric()
,fetchAssociative()
andfetchOne()
. - The
Statement::fetchAll()
method is replaced withfetchAllNumeric()
,fetchAllAssociative()
andfetchColumn()
. - The
Statement::fetchColumn()
method is replaced withfetchOne()
. - The
Connection::fetchArray()
andfetchAssoc()
methods are replaced withfetchNumeric()
andfetchAssociative()
respectively. - The
StatementIterator
class is removed. The usage of aStatement
object asTraversable
is 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\PostgreSqlPlatform
Doctrine\DBAL\Platforms\PostgreSQL91Platform
Doctrine\DBAL\Platforms\PostgreSQL92Platform
Doctrine\DBAL\Platforms\Keywords\PostgreSQLKeywords
Doctrine\DBAL\Platforms\Keywords\PostgreSQL91Keywords
Doctrine\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\SQLServerPlatform
Doctrine\DBAL\Platforms\SQLServer2005Platform
Doctrine\DBAL\Platforms\SQLServer2008Platform
Doctrine\DBAL\Platforms\Keywords\SQLServerKeywords
Doctrine\DBAL\Platforms\Keywords\SQLServer2005Keywords
Doctrine\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_OUTPUT
constants in the DBAL API is removed. \Doctrine\DBAL\Driver\PDOConnection
does not extend\PDO
anymore. Please use\Doctrine\DBAL\Driver\PDOConnection::getWrappedConnection()
to access the underlyingPDO
object.\Doctrine\DBAL\Driver\PDOStatement
does not extend\PDOStatement
anymore.
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): DriverException
After:
public function convert(Doctrine\DBAL\Driver\Exception $exception, ?Doctrine\DBAL\Query $query): DriverException
The constructor of Doctrine\DBAL\Exception\DriverException
is now @internal
.
- all
Configuration
methods are now typed Configuration::setSchemaAssetsFilter()
now returnsvoid
Configuration::$_attributes
has been removed; use individual properties in subclasses instead