UPGRADE.md
Note about upgrading: Doctrine uses static and runtime mechanisms to raise awareness about deprecated code.
@deprecated docblock that is detected by IDEs (like PHPStorm) or
Static Analysis tools (like Psalm, phpstan)Using SQL expressions for the current date, time, or timestamp as column default values is deprecated. Instead, use an
instance of the CurrentDate, CurrentTime, or CurrentTimestamp class, respectively.
Schema::createNamespace() and the $namespaces constructor parameterThe Schema::createNamespace() method and the $namespaces constructor parameter have been deprecated. The schema
automatically derives namespace names from the names of its tables and sequences. Creating empty namespaces is
deprecated.
TableDiff::getDroppedForeignKeys()The TableDiff::getDroppedForeignKeys() method has been deprecated. Use
TableDiff::getDroppedForeignKeyConstraintNames() instead.
AbstractSchemaManager methodsThe following AbstractSchemaManager methods have been deprecated:
listDatabases() - use introspectDatabaseNames() instead.listSchemaNames() - use introspectSchemaNames() instead.listTableNames() - use introspectTableNames() instead.listTableColumns() - use introspectTableColumns(), introspectTableColumnsByUnquotedName()
or introspectTableColumnsByQuotedName() instead.listTableIndexes() - use introspectTableIndexes(), introspectTableIndexesByUnquotedName()
or introspectTableIndexesByQuotedName() instead.listTableForeignKeys() - use introspectTableForeignKeys(), introspectTableForeignKeysByUnquotedName()
or introspectTableForeignKeysByQuotedName() instead.introspectTable() - use introspectTableByUnquotedName() or introspectTableByQuotedName() instead.listTables() - use introspectTables() instead.listViews() - use introspectViews() instead.listSequences() - use introspectSequences() instead.PostgreSQLPlatform::getDefaultColumnValueSQLSnippet() as internalThe PostgreSQLPlatform::getDefaultColumnValueSQLSnippet() method has been marked as internal.
Passing unnamed foreign key constraints as part of the $droppedForeignKeys argument of the TableDiff constructor
has been deprecated.
Adding a foreign key constraint with a name that matches an existing one, whether explicitly specified or
auto-generated, has been deprecated. In order to replace an existing constraint, drop it first
via dropForeignKey().
View featuresThe View constructor has been marked as internal. Use View::editor() to instantiate an editor and
ViewEditor::create() to create a view.
Sequence featuresSequence constructor has been marked as internal. Use Sequence::editor() to instantiate an editor and
SequenceEditor::create() to create a sequence.The following Sequence methods have been deprecated:
Sequence::getCache() - use Sequence::getCacheSize() instead.Sequence::setAllocationSize(), Sequence::setInitialValue() and Sequence::setCache() - use
SequenceEditor::setAllocationSize(), SequenceEditor::setInitialValue() and SequenceEditor::setCacheSize()
instead.Extending the following classes has been deprecated. Use them directly.
SchemaSequenceTableViewTable::getIndexes(), Table::getUniqueConstraints() and Table::getForeignKeys()Using the keys of the arrays returned by Table::getIndexes(), Table::getUniqueConstraints() and
Table::getForeignKeys() as index or constraint names is deprecated. Instead, retrieve the name from the index or
constraint object using NamedObject::getObjectName() or OptionallyNamedObject::getObjectName(). In order to retrieve
an object by name, use Table::getIndex(), Table::getUniqueConstraint() or Table::getForeignKey() respectively.
AbstractAsset::getName()The AbstractAsset::getName() method has been deprecated. Instead, use NamedObject::getObjectName() or
OptionallyQualifiedName::getObjectName() to get the object representation of the name. In SQL context, convert the
resulting Name to SQL using Name::toSQL(). In other contexts, convert the resulting name to string using
Name::toString().
AbstractAsset::isQuoted()The AbstractAsset::isQuoted() method has been deprecated. The recommended approach depends on the object class:
NamedObject::getObjectName() or OptionallyNamedObject::getObjectName().UnqualifiedName::getIdentifier()OptionallyQualifiedName::getQualifier() and/or
OptionallyQualifiedName::getUnqualifiedName().Identifier::isQuoted() to check if corresponding identifier(s) is (are) quoted.service connection parameter for oci8 and pdo_oci connections.Using the service connection parameter to indicate that the value of the dbname parameter is the service name has
been deprecated. Use the servicename parameter instead.
Column methodsThe following Column methods have been deprecated:
Column::getPlatformOptions(), Column::hasPlatformOption(), Column::getPlatformOption() – use
Column::getCharset(), Column::getCollation(), Column::getMinimumValue() and Column::getMaximumValue()
instead.Additionally,
Column class has been deprecated. Use the Column class directly.Column constructor has been marked as internal. Use Column::editor() to instantiate an
editor and ColumnEditor::create() to create a column.jsonb column platform option has been deprecatedThe jsonb column platform option has been deprecated. To define a JSONB column, use the JSONB type instead.
version column platform option has been deprecatedThe version column platform option has been deprecated without a replacement.
Doctrine\DBAL\Query\Limit class has been marked as internalExtending the following classes has been deprecated. Use them directly.
QueryCacheProfileStaticServerVersionProviderColumnDiffTableDiffSchemaDiffIndex methods, properties and behaviorThe following Index methods and properties have been deprecated:
Index::getColumns(), Index::getQuotedColumns(), Index::getUnquotedColumns(),
Index::$_columns – use Index::getIndexedColumns() instead.Index::isSimpleIndex(), Index::isUnique(), Index::$_isUnique – use Index::getType() and compare with
IndexType::REGULAR or IndexType::UNIQUE instead.Index::addFlag(), Index::removeFlag(), Index::getFlags(), Index::hasFlag(), Index::$_flags – use
IndexEditor::setType(), Index::getType(), IndexEditor::setIsClustered() and Index::isClustered() instead.Index::getOption(), Index::hasOption() and Index::getOptions() – use Index::getIndexedColumns() and
Index::getPredicate() instead.Index::overrules(), Index::hasColumnAtPosition() – no replacement provided.AbstractPlatform::supportsColumnLengthIndexes() – no replacement provided.Additionally,
Index::spansColumns() method has been marked as internal.Index constructor has been marked as internal. Use Index::editor() to instantiate an editor and
IndexEditor::create() to create an index.The following conflicting index configurations have been deprecated:
The AbstractPlatform::getCreatePrimaryKeySQL() method has been deprecated. Use the schema manager to create and
alter tables.
Building the SQL for dropping a primary key constraint via PostgreSQLPlatform::getDropIndexSQL() has been
deprecated. Use PostgreSQLPlatform::getDropConstraintSQL() instead.
Using the Index class to represent a primary key constraint has been deprecated, including:
true as the $isPrimary constructor argument.$_isPrimary property and the isPrimary() method.Use the PrimaryKeyConstraint class to represent a primary key constraint instead.
The following features of the Table class have been deprecated:
Table::getPrimaryKey() method. Use Table::getPrimaryKeyConstraint() instead.Table::setPrimaryKey() method. Instead, pass the $primaryKeyConstraint argument to the constructor or add
the constraint via Table::addPrimaryKeyConstraint().Table::renameIndex() to rename the primary key constraint. Use Table::dropPrimaryKey() and
Table::addPrimaryKeyConstraint() instead.The following auto-increment column definitions are deprecated in SQLite:
Relying on the auto-increment attribute of a MySQL column being automatically dropped once the column is no longer part of the primary key constraint is deprecated. Instead, drop the auto-increment attribute explicitly.
TableDiffPassing a non-empty $modifiedIndexes value to the TableDiff constructor is deprecated. Instead, pass dropped
indexes via $droppedIndexes and added indexes via $addedIndexes.
Detection of modified indexes is deprecated. Please disable it by configuring the comparator using
ComparatorConfig::withReportModifiedIndexes(false). With this configuration, the old version of the index will be
included in the return value of TableDiff::getDroppedIndexes(), and the new version will be included in the return
value of TableDiff::getAddedIndexes().
The TableDiff::getModifiedIndexes() method has been deprecated.
TableDiffPassing a non-empty $modifiedForeignKeys value to the TableDiff constructor is deprecated. Instead, pass dropped
constraints via $droppedForeignKeys and added constraints via $addedForeignKeys.
The TableDiff::getModifiedForeignKeys() method has been deprecated. The old version of the foreign key constraint is
included in the return value of TableDiff::getDroppedForeignKeys(), the new version is included in the return value of
TableDiff::getAddedForeignKeys().
$options to AbstractPlatform::_getCreateTableSQL()Not passing the $options argument or any of its following keys to the AbstractPlatform::_getCreateTableSQL() method
has been deprecated: primary, indexes, uniqueConstraints, foreignKeys.
AbstractPlatform::getCheckDeclarationSQL() method has been marked as internal.$definition argument to AbstractPlatform::getCheckDeclarationSQL() is
deprecated. Pass column definitions represented as array instead.Index usage scenariosThe following Index usage scenarios have been deprecated:
Index class has been deprecated. Use the Index class directly.Relying on table names containing dots not being parsed on platforms that don't support schemas is deprecated. If a table name contains a dot or other special characters, it should be quoted.
Passing names that are not valid SQL to the schema introspection methods is also deprecated.
The following platform and schema manager methods are considered implementation details and have been marked as internal:
AbstractMySQLPlatform::getColumnTypeSQLSnippet()AbstractMySQLPlatform::fetchTableOptionsByTable()MariaDB1010Platform::fetchTableOptionsByTable()MariaDBPlatform::getColumnTypeSQLSnippet()OraclePlatform::getCreateAutoincrementSql()OraclePlatform::getIdentitySequenceName()OracleSchemaManager::dropAutoincrement()SQLServerPlatform::getCreateColumnCommentSQL()SQLServerPlatform::getDefaultConstraintDeclarationSQL()SQLServerPlatform::getAlterColumnCommentSQL()SQLServerPlatform::getDropColumnCommentSQL()SQLServerPlatform::getAddExtendedPropertySQL()SQLServerPlatform::getDropExtendedPropertySQL()SQLServerPlatform::getUpdateExtendedPropertySQL()AbstractSchemaManager::_normalizeName()The AbstractSchemaManager::_normalizeName() method has been deprecated. Use Identifier::toNormalizedValue() to
obtain the value of the identifier normalized according to the rules of the target database platform.
AbstractSchemaManager::_getPortableTableDefinition()The AbstractSchemaManager::_getPortableTableDefinition() method has been deprecated. Use the schema name and the
unqualified table name separately instead.
PostgreSQLSchemaManager methods related to the current schemaThe following PostgreSQLSchemaManager methods have been deprecated:
getCurrentSchema() - use getCurrentSchemaName() insteaddetermineCurrentSchema() - use determineCurrentSchemaName() insteadSchema as AbstractAssetRelying on the Schema class extending AbstractAsset is deprecated. Use only the methods declared immediately in
the Schema class itself.
ForeignKeyConstraint methods, properties and behaviorThe following ForeignKeyConstraint methods and properties have been deprecated:
ForeignKeyConstraint::getForeignTableName(), ForeignKeyConstraint::getQuotedForeignTableName(),
ForeignKeyConstraint::getUnqualifiedForeignTableName(), ForeignKeyConstraint::$_foreignTableName – use
ForeignKeyConstraint::getReferencedTableName() instead.ForeignKeyConstraint::getLocalColumns(), ForeignKeyConstraint::getQuotedLocalColumns(),
ForeignKeyConstraint::getUnquotedLocalColumns(), ForeignKeyConstraint::$_localColumnNames – use
ForeignKeyConstraint::getReferencingColumnNames() instead.ForeignKeyConstraint::getForeignColumns(), ForeignKeyConstraint::getQuotedForeignColumns(),
ForeignKeyConstraint::getUnquotedForeignColumns(), ForeignKeyConstraint::$_foreignColumnNames – use
ForeignKeyConstraint::getReferencedColumnNames() instead.ForeignKeyConstraint::getOption(), ForeignKeyConstraint::getOptions(), ForeignKeyConstraint::hasOption(),
ForeignKeyConstraint::onUpdate(), ForeignKeyConstraint::onDelete(), ForeignKeyConstraint::$options – use
ForeignKeyConstraint::getMatchType(), ForeignKeyConstraint::getOnUpdateAction(),
ForeignKeyConstraint::getOnDeleteAction() and ForeignKeyConstraint::getDeferrability() instead.ForeignKeyConstraint::intersectsIndexColumns().Additionally,
ForeignKeyConstraint class has been deprecated. Use the ForeignKeyConstraint class directly.ForeignKeyConstraint constructor has been marked as internal. Use ForeignKeyConstraint::editor() to
instantiate an editor and ForeignKeyConstraintEditor::create() to create a foreign key constraint.AbstractPlatform::getForeignKeyBaseDeclarationSQL() method has been marked as internal.Table::columnsAreIndexed()The Table::columnsAreIndexed() method has been deprecated.
RESTRICT with Oracle and SQL ServerRelying on automatic conversion of the RESTRICT constraint referential action to NO ACTION on Oracle and SQL Server
is deprecated. Use NO ACTION instead.
If the referenced column names are omitted in a foreign key constraint declaration, it implies that the constraint references the primary key columns of the referenced table. If the referenced table is not present in the schema, the constraint cannot be properly introspected, and the referenced column names are introspected as an empty list. This behavior is deprecated.
In order to mitigate this issue, either ensure that the referenced table is present in the schema when introspecting foreign constraints, or provide the referenced column names explicitly in the constraint declaration.
UniqueConstraint methods, properties and behaviorThe following UniqueConstraint methods and property have been deprecated:
UniqueConstraint::addColumn() – the constraint should not be modified once instantiated.UniqueConstraint::addFlag(), UniqueConstraint::getFlags(), UniqueConstraint::hasFlag(),
UniqueConstraint::removeFlag(), UniqueConstraint::$flags – the only supported flag is "is clustered". Use
UniqueConstraintEditor::setIsClustered() to set the flag and UniqueConstraint::isClustered() to check it instead.UniqueConstraint::getColumns(), UniqueConstraint::getQuotedColumns(), UniqueConstraint::getUnquotedColumns(),
UniqueConstraint::$columns – use UniqueConstraint::getColumnNames() instead.UniqueConstraint::getOption(), UniqueConstraint::getOptions(), UniqueConstraint::hasOption() – DBAL doesn't
support any options for unique constraints. Passing non-empty options to the UniqueConstraint constructor is
deprecated as well.Additionally,
UniqueConstraint class has been deprecated. Use the UniqueConstraint class directly.UniqueConstraint constructor has been marked as internal. Use UniqueConstraint::editor() to instantiate an
editor and UniqueConstraintEditor::create() to create a unique constraint.AbstractPlatform::getUniqueConstraintDeclarationSQL() method has been marked as internal.AbstractAsset::isIdentifierQuoted()The AbstractAsset::isIdentifierQuoted() method has been deprecated. Parse the name and introspect its identifiers
individually using Identifier::isQuoted() instead.
If a schema lacks a default namespace configuration and has at least one object with an unqualified name, adding or referencing objects with qualified names is deprecated.
If a schema lacks a default namespace configuration and has at least one object with a qualified name, adding or referencing objects with unqualified names is deprecated.
Mixing unqualified and qualified names is permitted as long as the schema is configured to use a default namespace. In this case, the default namespace will be used to resolve unqualified names.
AbstractAsset::getQuotedName()The AbstractAsset::getQuotedName() method has been deprecated. Use NamedObject::getObjectName() or
OptionallyQualifiedName::getObjectName() followed by Name::toSQL() instead.
AbstractAsset namespace-related methods and propertyThe following namespace-related methods and property have been deprecated:
AbstractAsset::getNamespaceName()AbstractAsset::isInDefaultNamespace()AbstractAsset::$_namespaceIn order to identify the namespace of an object, use the following methods instead:
$qualifier = $table->getObjectName()->getQualifier();
If the return value is not null, then it will contain the identifier representing the namespace name – its value and whether it's quoted.
Table::__construct() marked as internalThe Table::__construct() method has been marked as internal. Use Table::editor() to instantiate an editor and
TableEditor::create() to create a table.
AbstractAsset::getShortestName()The AbstractAsset::getShortestName() method has been deprecated. Use NamedObject::getObjectName() instead.
Sequence::isAutoIncrementsFor()The Sequence::isAutoIncrementsFor() method has been deprecated.
Using the following objects with an empty name is deprecated: Table, Column, Index, 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.
Table methodsThe Table::setSchemaConfig() method and $_schemaConfig property have been deprecated. Pass a TableConfiguration
instance to the constructor instead.
The Table::_getMaxIdentifierLength() method has been deprecated.
AbstractAsset::_setName()Setting object name via AbstractAsset::_setName() has been deprecated. Pass the name to the AbstractAsset
constructor instead.
Identifier class as internalIn 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:
KeywordList class and all its subclasses.AbstractPlatform::createReservedKeywordsList() and ::getReservedKeywordsList().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:
select)."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:
"inventory).warehouse.inventory.product) but only uses the first two,
ignoring the remaining ones.Relying on the above behaviors is deprecated.
AbstractPlatform::quoteIdentifier() and Connection::quoteIdentifier()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.
Table::removeForeignKey() and ::removeUniqueConstraint()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\Pgsql instead of just PDO.
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.
TableDiff methodsThe TableDiff methods getModifiedColumns() and getRenamedColumns() have been merged into a single
method getChangedColumns(). Use this method instead.
Result::getColumnName()Driver and middleware results need to implement a new method getColumnName() that gives access to the
column name. Not doing so is deprecated.
AbstractMySQLPlatform methods.getColumnTypeSQLSnippets(),getDatabaseNameSQL().AbstractPlatform methodsThe 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.
DateTime typesThe following types don't accept or return DateTimeImmutable instances anymore:
DateTimeTypeDateTimeTzTypeDateTypeTimeTypeVarDateTimeTypeAs a consequence, the following type classes don't extend their mutable counterparts anymore:
DateTimeImmutableTypeDateTimeTzImmutableTypeDateImmutableTypeTimeImmutableTypeVarDateTimeImmutableTypeThe following methods have been removed:
Result::fetch()Result::fetchAll()Connection::exec()Connection::executeUpdate()Connection::query()Additionally, the FetchMode class has been removed.
url connection parameterDBAL 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')
);
Connection::PARAM_*_ARRAY constantsUse the enum ArrayParameterType instead.
serverVersionThe serverVersion connection parameter must consist of 3 numbers:
-'serverVersion' => '8.0'
+'serverVersion' => '8.0.31'
mariadb- prefix hackPreviously, 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'
SchemaDiff::$orphanedForeignKeysThe 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 function instr() that behaves similarly.
Use AbstractPlatform::getLocateExpression() if you need a portable solution.
mod(): SQLite provides a % operator for modulo calculations.
Use AbstractPlatform::getModExpression() if you need a portable solution.
Since version 3.35.0 SQLite also provides a mod() function if math
functions have been enabled.
sqrt(): Upgrade to SQLite 3.35.0 and compile SQLite with math functions to
get a native sqrt() function. If you need a sqrt() 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.
Table methodsThe following Table methods have been removed:
changeColumn(),getForeignKeyColumns(),getPrimaryKeyColumns(),hasPrimaryKey().SchemaException error code constantsThe 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.
Connection.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.
Connection.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.
Connection methods.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.
Statement::bindParam() methods.The following methods have been removed:
Doctrine\DBAL\Statement::bindParam(),Doctrine\DBAL\Driver\Statement::bindParam().Statement::bindValue() required.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\ConflictResolutionModeThe 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 => SQLitePlatformSqliteSchemaManager => SQLiteSchemaManagerSqlitePlatform methods.getTinyIntTypeDeclarationSQL(),getMediumIntTypeDeclarationSQL().AbstractPlatform methods.getColumnsFieldDeclarationListSQL(),getCustomTypeDeclarationSQL(),getDefaultSchemaName(),getIdentitySequenceName(),getIndexFieldDeclarationListSQL(),supportsCreateDropDatabase(),usesSequenceEmulatedIdentityColumns().NULL value of schema asset filter.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().array and object column types.The following classes and constants have been removed:
ArrayType,ObjectType,Types::ARRAY,Types::OBJECT.Driver::getSchemaManager()The Driver::getSchemaManager() method has been removed.
AbstractSchemaManager methodsThe 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().RemoveNamespacedAssets.The RemoveNamespacedAssets schema visitor has been removed.
The following components have been removed:
dbal:reserved-words console command.ReservedWordsCommand and ReservedKeywordsValidator classes.KeywordList::getName() method.AbstractPlatform::supportsForeignKeyConstraints().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.
AbstractPlatform methods exposing quote characters.The AbstractPlatform::getStringLiteralQuoteCharacter() and ::getIdentifierQuoteCharacter() methods
have been removed.
AbstractPlatform::CREATE_* constantsThe 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.
$createFlags from AbstractPlatform::getCreateTableSQL()The $createFlags parameter of AbstractPlatform::getCreateTableSQL() has been removed.
CreateSchemaSqlCollector and DropSchemaSqlCollectorThe 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()IDENTITY, not SERIAL.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.
doctrine-dbal binary and the ConsoleRunner class.The documentation explains how the console tools can be bootstrapped for standalone usage.
$database parameter of AbstractSchemaManager::list*() methodsPassing $database to the following methods is no longer supported:
AbstractSchemaManager::listSequences(),AbstractSchemaManager::listTableColumns(),AbstractSchemaManager::listTableForeignKeys().AbstractPlatform schema introspection methodsThe following schema introspection methods have been removed:
AbstractPlatform::getListTablesSQL(),AbstractPlatform::getListTableColumnsSQL(),AbstractPlatform::getListTableIndexesSQL(),AbstractPlatform::getListTableForeignKeysSQL(),AbstractPlatform::getListTableConstraintsSQL().AbstractSchemaManager class have been declared as abstractThe 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.
int|stringThe 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.
collate option for MySQLUse collation instead.
Type::getName()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.
AbstractPlatform::prefersIdentityColumns()The AbstractPlatform::prefersIdentityColumns() method has been removed.
Graphviz visitor.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\MariaDb1027PlatformDoctrine\DBAL\Platforms\MariaDB1043PlatformDoctrine\DBAL\Platforms\Keywords\MariaDb102KeywordsMySQL 5.6 and older are not supported anymore. The following classes have been merged into their respective parent classes:
Doctrine\DBAL\Platforms\MySQL57PlatformDoctrine\DBAL\Platforms\Keywords\MySQL57KeywordsPostgres 9 is not actively supported anymore. The following classes have been merged into their respective parent class:
Doctrine\DBAL\Platforms\PostgreSQL100PlatformDoctrine\DBAL\Platforms\Keywords\PostgreSQL100KeywordsThe 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.
Type::canRequireSQLConversion()The Type::canRequireSQLConversion() method has been removed.
Connection::getWrappedConnection(), Connection::connect() made protected.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.
getNativeConnection() to driver connections and removed old accessorsDriver 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()SQLLogger and its implementations.The SQLLogger interface and its implementations DebugStack and LoggerChain have been removed.
The corresponding Configuration methods, getSQLLogger() and setSQLLogger(), have been removed as well.
SqliteSchemaManager::createDatabase() and dropDatabase() methods.The SqliteSchemaManager::createDatabase() and dropDatabase() methods have been removed.
AbstractSchemaManager::dropAndCreate*() and ::tryMethod() methods.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.
Statement::execute() marked private.The Statement::execute() method has been marked private.
QueryBuilder methods and contstants.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.Constraint interface.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().AbstractSchemaManager::getSchemaSearchPaths().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.
AbstractAsset::getFullQualifiedName().The AbstractAsset::getFullQualifiedName() method has been removed.
The following methods have been removed:
Schema::hasExplicitForeignKeyIndexes(),SchemaConfig::hasExplicitForeignKeyIndexes(),SchemaConfig::setExplicitForeignKeyIndexes().Schema::getTableNames().The Schema::getTableNames() method has been removed.
Schema method return values.The Schema::getNamespaces(), Schema::getTables() and Schema::getSequences() methods will return numeric arrays
of namespaces, tables and sequences respectively instead of associative arrays.
SqlitePlatform::udf*() methods.The following SqlitePlatform methods have been removed:
udfSqrt(),udfMod(),udfLocate().SQLServerPlatform methods marked protected.The following SQLServerPlatform methods have been marked protected:
getDefaultConstraintDeclarationSQL(),getAddExtendedPropertySQL(),getDropExtendedPropertySQL(),getUpdateExtendedPropertySQL().OraclePlatform methods marked protected.The OraclePlatform::getCreateAutoincrementSql() method has been marked protected.
OraclePlatform::assertValidIdentifier().The OraclePlatform::assertValidIdentifier() method has been removed.
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.
AbstractPlatform::canEmulateSchemas()The AbstractPlatform::canEmulateSchemas() method and the schema emulation implemented in the SQLite platform
have been removed.
TableDiff::$name name TableDiff::getName().The TableDiff::$name property and TableDiff::getName() method have been removed.
TableDiff and AbstractPlatform::alterTable().The TableDiff::$newName property and the TableDiff::getNewName() method have been removed.
SchemaDiff reference to the original schema.The SchemaDiff class no longer accepts or exposes a reference to the original schema.
ColumnDiff class$fromColumn parameter of the ColumnDiff constructor has been made required.$oldColumnName property and the getOldColumnName() method have been removed.Table::getColumns()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.
AbstractPlatform::getName()The AbstractPlatform::getName() method has been removed.
The following platform-related classes have been removed:
PostgreSQL94Platform and PostgreSQL94Keywords.SQLServer2012Platform and SQLServer2012Keywords.AbstractPlatform::getNowExpression().The AbstractPlatform::getNowExpression() method has been removed.
ForeignKeyConstraint to its local (referencing) Table.Reference from ForeignKeyConstraint to its local (referencing) Table is removed as well as the following methods:
setLocalTable(),getLocalTable(),getLocalTableName().AbstractPlatform methods.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().AbstractPlatform class have been declared as abstract.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.
Connection::lastInsertId() throws an exception when there's no identity value.Instead of returning an empty value, Connection::lastInsertId() throws an exception when there's no identity value.
Comparator::compareSchemas() signatureThe method Comparator::compareSchemas() cannot be called statically anymore.
Comparator methodsThe Comparator::compare(), ::diffTable() and ::diffColumn() methods have been removed.
ColumnDiff methodsThe ColumnDiff::hasChanged() method has been removed.
TableGenerator componentThe TableGenerator component has been removed.
Connection::lastInsertId($name)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.
ReservedWordsCommand::setKeywordListClass()To add or replace a keyword list, use ReservedWordsCommand::setKeywordList().
AbstractPlatform::getReservedKeywordsClass()Instead of implementing AbstractPlatform::getReservedKeywordsClass(), platforms must implement AbstractPlatform::createReservedKeywordsList(). The latter has been made abstract.
PostgreSQLSchemaManager methods have been made protected.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().Connection::$_schemaManager and Connection::getSchemaManager()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.
Connection::$_expr and Connection::getExpressionBuilder()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.
ExpressionBuilder methodsThe andX() and orX() methods of the ExpressionBuilder class have been removed. Use and() and or() instead.
CompositeExpression methodsThe 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.
select(), addSelect(), groupBy() and addGroupBy() methods no longer accept an array of arguments. Pass each expression as an individual argument or expand an array of expressions using the ... operator.select(), addSelect(), groupBy() and addGroupBy() methods no longer ignore the first argument if it's empty.addSelect() method can be no longer called without arguments.insert(), update() and delete() methods now require the $table parameter, and do not support aliases anymore.add(), getQueryPart(), getQueryParts(), resetQueryPart() and resetQueryParts() methods are removed.select() query, the getSQL() method now throws an expression if no SELECT expressions have been provided.\DBAL\Platforms\AbstractPlatform::getVarcharTypeDeclarationSQL() method has been renamed to ::getStringTypeDeclarationSQL().AbstractPlatform methods have been removed as no longer relevant: ::getCharMaxLength(), ::getVarcharMaxLength(), ::getVarcharDefaultLength(), ::getBinaryMaxLength(), ::getBinaryDefaultLength().Doctrine\DBAL\Event\SchemaCreateTableEventArgsTable columns are no longer indexed by column name. Use the name attribute of the column instead.
Doctrine\DBAL\Schema APIDoctrine\DBAL\Event APISchemaAlterTableAddColumnEventArgs::addSql() and the same method in other SchemaEventArgs-based classes no longer accept an array of SQL statements. They accept a variadic string.Doctrine\DBAL\Schema APIDoctrine\DBAL\Schema\AbstractSchemaManager::_getPortableViewDefinition() no longer optionally returns false. It will always return a Doctrine\DBAL\Schema\View instance.Doctrine\DBAL\Schema\Table::$_primaryKeyName is now optionally null instead of false.Doctrine\DBAL\Schema\AbstractSchemaManager::tablesExist() no longer accepts a string. Use Doctrine\DBAL\Schema\AbstractSchemaManager::tableExists() instead.Doctrine\DBAL\Schema\OracleSchemaManager::createDatabase() no longer accepts null for $database argument.feferred misspelling removedPostgreSqlPlatform::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.
DB2SchemaManager::_getPortableForeignKeyRuleDef() removedThe method was used internally and is no longer needed.
AbstractPlatform::get*Expression() methods no loner accept integer values as argumentsThe following methods' arguments do not longer accept integer value:
$expression argument in ::getCountExpression(),$decimals argument in ::getRoundExpression(),$seconds argument in ::getDateAddSecondsExpression(),$seconds argument in ::getDateSubSecondsExpression(),$minutes argument in ::getDateAddMinutesExpression(),$minutes argument in ::getDateSubMinutesExpression(),$hours argument in ::getDateAddHourExpression(),$hours argument in ::getDateAddHourExpression(),$days argument in ::getDateAddDaysExpression(),$days argument in ::getDateSubDaysExpression(),$weeks argument in ::getDateAddWeeksExpression(),$weeks argument in ::getDateSubWeeksExpression(),$months argument in ::getDateAddMonthExpression(),$months argument in ::getDateSubMonthExpression(),$quarters argument in ::getDateAddQuartersExpression(),$quarters argument in ::getDateSubQuartersExpression(),$years argument in ::getDateAddYearsExpression(),$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).
$start in AbstractPlatform::getLocateExpression() changed from string|false to ?stringThe default value of $start is now null, not false.
$start and $length in AbstractPlatform::getSubstringExpression() changed from int and ?int to string and ?string respectivelyThe 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.
$char in AbstractPlatform::getTrimExpression() changed from string|false to ?stringThe 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() only accepts strings.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.
Statement and Connection methods return void.Connection::connect(), ::bindValue() and ::execute() no longer return a boolean value. They will throw an exception in case of failure.
Statement methods return void.Statement::beginTransaction(), ::commit() and ::rollBack() no longer return a boolean value. They will throw a DriverException in case of failure.
Statement::fetchColumn() with an invalid index.Similarly to PDOStatement::fetchColumn(), DBAL statements throw an exception in case of an invalid column index.
Statement::execute() with redundant parameters.Similarly to the drivers based on pdo_pgsql and pdo_sqlsrv, OCI8Statement::execute() and MySQLiStatement::execute() do not longer ignore redundant parameters.
NULL value of $offset in LIMIT queries is not allowedThe 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.
BLOBs.
Use binary fields of a size which fits all target platforms, or use blob explicitly instead.The following methods have been removed.
| class | method | replacement |
|---|---|---|
Configuration | setResultCacheImpl() | setResultCache() |
Configuration | getResultCacheImpl() | getResultCache() |
QueryCacheProfile | setResultCacheDriver() | setResultCache() |
QueryCacheProfile | getResultCacheDriver() | getResultCache() |
In 3.10.2, we've backported support for new PDO subclasses introduced in PHP 8.4 because not using them could trigger deprecation warnings under certain circumstances in PHP 8.5.
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\Pgsql instead of just PDO.
doctrine/cache dependencyThe doctrine/cache package is now an optional dependency. If you are using the
Doctrine\DBAL\Cache classes, you need to require the doctrine/cache package
explicitly.
AbstractPlatform methodsThe 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 methodsAbstractMySQLPlatform::getColumnTypeSQLSnippets() has been deprecated
in favor of AbstractMySQLPlatform::getColumnTypeSQLSnippet().AbstractMySQLPlatform::getDatabaseNameSQL() has been deprecated without replacement.AbstractMySQLPlatform::getColumnTypeSQLSnippet() has been deprecated.QueryBuilderQueryBuilder::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. |
QueryBuilderThe 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.
url connection parameterDBAL 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')
);
Connection::PARAM_*_ARRAY constantsUse 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. Use Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession.SQLiteSessionInit. Use Doctrine\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:
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:
CREATE TABLE DDL), you should do the needed modifications before calling
the corresponding platform or schema manager method.LOCATE() function for SQLiteRelying 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.
SchemaDiff::toSql() and SchemaDiff::toSaveSql()Using SchemaDiff::toSql() to generate SQL representing the diff has been deprecated.
Use AbstractPlatform::getAlterSchemaSQL() instead.
SchemaDiff::toSaveSql() has been deprecated without a replacement.
SchemaDiff::$orphanedForeignKeysRelying 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.
userDefinedFunctions driver option for pdo_sqliteInstead 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);
Table methods.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.
SchemaException error codes.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.
Connection.The "default_dbname" parameter of the wrapper Connection has been deprecated. Use "dbname" instead.
Connection.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.
Comparator::diffTable() method.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
}
$fromTable to the TableDiff constructor.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().
TableDiff and AbstractPlatform::alterTable().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.
Comparator methods as internal.The following Comparator methods have been marked as internal:
columnsEqual(),diffForeignKey(),diffIndex().The diffColumn() method has been deprecated. Use diffTable() instead.
SchemaDiff public properties as internal.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() |
TableDiff public properties as internal.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() |
ColumnDiff public properties as internal.The $fromColumn and $column properties of the ColumnDiff class have been marked as internal. Use the
getOldColumn() and getNewColumn() methods instead.
ColumnDiff::$changedProperties and ::hasChanged().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().ColumnDiff APIs dedicated to the old column name.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.
SchemaDiff reference to the original schema.The SchemaDiff::$fromSchema property has been deprecated.
AbstractSchemaManager::_execSql() as internal.The AbstractSchemaManager::_execSql() method has been marked as internal. It will not be available in 4.0.
AbstractSchemaManager schema introspection methods.The following AbstractSchemaManager methods has been deprecated:
listTableDetails(). Use introspectTable() instead,createSchema(). Use introspectSchema() instead.Statement::bindParam() methods.The following methods have been deprecated:
Doctrine\DBAL\Statement::bindParam(),Doctrine\DBAL\Driver\Statement::bindParam().Use the corresponding bindValue() instead.
Statement::bind*() methods.Not passing $type to the driver-level Statement::bindParam() and ::bindValue() is deprecated.
Pass the type corresponding to the parameter being bound.
$params to Statement::execute*() methods.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.
QueryBuilder methods and constants.QueryBuilder::getState() method has been deprecated as the builder state is an internal concern.QueryBuilder::getType() has been deprecated.
If necessary, track the type of the query being built outside of the builder.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.Connection::ARRAY_PARAM_OFFSET as internal.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.
AbstractPlatform and AbstractSchemaManager methods.Passing assets to the following AbstractPlatform methods and parameters has been deprecated:
$table parameter of getDropTableSQL(),$table parameter of getDropTemporaryTableSQL(),$index and $table parameters of getDropIndexSQL(),$constraint and $table parameters of getDropConstraintSQL(),$foreignKey and $table parameters of getDropForeignKeySQL(),$sequence parameter of getDropSequenceSQL(),$table parameter of getCreateConstraintSQL(),$table parameter of getCreatePrimaryKeySQL(),$table parameter of getCreateForeignKeySQL().Passing assets to the following AbstractSchemaManager methods and parameters has been deprecated:
$index and $table parameters of dropIndex(),$table parameter of dropConstraint(),$foreignKey and $table parameters of dropForeignKey().Pass a string representing the quoted asset name instead.
AbstractPlatform methods as internal.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().AbstractPlatform methods.The following methods have been deprecated as they do not represent any platform-level abstraction:
getCustomTypeDeclarationSQL(),getIndexFieldDeclarationListSQL(),getColumnsFieldDeclarationListSQL().AbstractPlatform methods.usesSequenceEmulatedIdentityColumns() and getIdentitySequenceName() 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 calling AbstractSchemaManager::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.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.
NULL schema asset filter.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.
array and object column types.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.
You can keep the old type behavior by copying (and adapting) the old type classes (Array and Object) into your own code- base and re-register them in the TypeRegistry:
use Doctrine\DBAL\Types\TypeFactory;
use MyApp\Doctrine\Types\ArrayType;
use MyApp\Doctrine\Types\ObjectType;
TypeRegistry::register('array', new ArrayType());
TypeRegistry::register('object', new ObjectType());
Driver::getSchemaManager().The Driver::getSchemaManager() method has been deprecated. Use AbstractPlatform::createSchemaManager() instead.
ConsolerRunner.The ConsoleRunner class has been deprecated. Use Symfony Console documentation
to bootstrap a command-line application.
Visitor interfaces and visit() methods on schema objects.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:
dbal:reserved-words console command.ReservedWordsCommand and ReservedKeywordsValidator classes.KeywordList::getName() method.Use the documentation on the used database platform(s) instead.
CreateSchemaSqlCollector and DropSchemaSqlCollector.The CreateSchemaSqlCollector and DropSchemaSqlCollector classes have been deprecated in favor of
CreateSchemaObjectsSQLBuilder and DropSchemaObjectsSQLBuilder respectively.
AbstractPlatform::getCreateTableSQL() with any of the CREATE_INDEXES and CREATE_FOREIGNKEYSflags 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().
AbstractPlatform::supportsForeignKeyConstraints().The AbstractPlatform::supportsForeignKeyConstraints() method has been deprecated. All platforms should support
foreign key constraints.
AbstractPlatform::supportsForeignKeyConstraints().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.
AbstractPlatform methods exposing quote characters.The AbstractPlatform::getStringLiteralQuoteCharacter() and ::getIdentifierQuoteCharacter() methods
have been deprecated. Use ::quoteStringLiteral() and ::quoteIdentifier() to quote string literals and identifiers
respectively.
AbstractSchemaManager::getDatabasePlatform()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:
$seconds argument in ::getDateAddSecondsExpression(),$seconds parameter in ::getDateSubSecondsExpression(),$minutes parameter in ::getDateAddMinutesExpression(),$minutes parameter in ::getDateSubMinutesExpression(),$hours parameter in ::getDateAddHourExpression(),$hours parameter in ::getDateAddHourExpression(),$days parameter in ::getDateAddDaysExpression(),$days parameter in ::getDateSubDaysExpression(),$weeks parameter in ::getDateAddWeeksExpression(),$weeks parameter in ::getDateSubWeeksExpression(),$months parameter in ::getDateAddMonthExpression(),$months parameter in ::getDateSubMonthExpression(),$quarters parameter in ::getDateAddQuartersExpression(),$quarters parameter in ::getDateSubQuartersExpression(),$years parameter in ::getDateAddYearsExpression(),$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.
AbstractPlatform::getVarcharTypeDeclarationSQL()The AbstractPlatform::getVarcharTypeDeclarationSQL() method has been deprecated.
Use AbstractPlatform::getStringTypeDeclarationSQL() instead.
$database parameter of AbstractSchemaManager::list*() methodsPassing $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.
AbstractPlatform schema introspection methodsThe following schema introspection methods have been deprecated:
AbstractPlatform::getListTablesSQL(),AbstractPlatform::getListTableColumnsSQL(),AbstractPlatform::getListTableIndexesSQL(),AbstractPlatform::getListTableForeignKeysSQL().AbstractPlatform schema introspection methods made internalThe 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.
collate option for MySQLThis undocumented option is deprecated in favor of collation.
AbstractPlatform::getListTableConstraintsSQL()This method is unused by the DBAL since 2.0.
Type::getName()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::getColumnComment(), AbstractPlatform::getDoctrineTypeComment(),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.
Type::canRequireSQLConversion().Consumers should call Type::convertToDatabaseValueSQL() and Type::convertToPHPValueSQL() regardless of the type.
doctrine-dbal binary.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.
Graphviz visitor.This class is not part of the database abstraction provided by the library and will be removed in DBAL 4.
--depth option of RunSqlCommand.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.
Db2 10.5 and older won't be supported in DBAL 4. Consider upgrading to 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\MariaDb1027PlatformDoctrine\DBAL\Platforms\Keywords\MariaDb102KeywordsMySQL 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\MySQL57PlatformDoctrine\DBAL\Platforms\Keywords\MySQL57KeywordsPostgres 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\PostgreSQL100PlatformDoctrine\DBAL\Platforms\Keywords\PostgreSQL100KeywordsConnection::getWrappedConnection(), Connection::connect() made @internal.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.
Connection::getNativeConnection()Driver and middleware connections need to implement a new method getNativeConnection() that gives access to the
native database connection. Not doing so is deprecated.
getNativeConnection()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.
psr/cacheWe 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: {}()/\@:.
SQLLogger and its implementations.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.
SqliteSchemaManager::createDatabase() and dropDatabase() methods.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.
AbstractSchemaManager::dropAndCreate*() and ::tryMethod() methods.The following AbstractSchemaManager::dropAndCreate*() methods have been deprecated:
AbstractSchemaManager::dropAndCreateConstraint(). Use AbstractSchemaManager::dropIndex()
and AbstractSchemaManager::createIndex(), AbstractSchemaManager::dropForeignKey()
and AbstractSchemaManager::createForeignKey() or AbstractSchemaManager::dropUniqueConstraint()
and AbstractSchemaManager::createUniqueConstraint() instead.AbstractSchemaManager::dropAndCreateIndex(). Use AbstractSchemaManager::dropIndex()
and AbstractSchemaManager::createIndex() instead.AbstractSchemaManager::dropAndCreateForeignKey().
Use AbstractSchemaManager::dropForeignKey() and AbstractSchemaManager::createForeignKey() instead.AbstractSchemaManager::dropAndCreateSequence(). Use AbstractSchemaManager::dropSequence()
and AbstractSchemaManager::createSequence() instead.AbstractSchemaManager::dropAndCreateTable(). Use AbstractSchemaManager::dropTable()
and AbstractSchemaManager::createTable() instead.AbstractSchemaManager::dropAndCreateDatabase(). Use AbstractSchemaManager::dropDatabase()
and AbstractSchemaManager::createDatabase() instead.AbstractSchemaManager::dropAndCreateView(). Use AbstractSchemaManager::dropView()
and AbstractSchemaManager::createView() instead.The AbstractSchemaManager::tryMethod() method has been also deprecated.
AbstractSchemaManager::getSchemaSearchPaths().AbstractSchemaManager::getSchemaSearchPaths() method has been deprecated.AbstractSchemaManager::createSchemaConfig() populating the schema name for those database
platforms that don't support schemas (currently, all except for PostgreSQL) is deprecated.Schema using "public" as the default name is deprecated.AbstractAsset::getFullQualifiedName().The AbstractAsset::getFullQualifiedName() method has been deprecated. Use ::getNamespaceName()
and ::getName() instead.
The following methods have been deprecated:
Schema::hasExplicitForeignKeyIndexes(),SchemaConfig::hasExplicitForeignKeyIndexes(),SchemaConfig::setExplicitForeignKeyIndexes().Schema::getTableNames().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.
Schema::getTables()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().
AbstractPlatform::canEmulateSchemas().The AbstractPlatform::canEmulateSchemas() method and the schema emulation implemented in the SQLite platform
have been deprecated.
udf* methods of the SQLitePlatform methods.The following SQLServerPlatform methods have been deprecated in favor of their implementations
in the UserDefinedFunctions class:
udfSqrt(),udfMod(),udfLocate().SQLServerPlatform methods marked internal.The following SQLServerPlatform methods have been marked internal:
getDefaultConstraintDeclarationSQL(),getAddExtendedPropertySQL(),getDropExtendedPropertySQL(),getUpdateExtendedPropertySQL().OraclePlatform methods marked internal.The OraclePlatform::getCreateAutoincrementSql() and ::getDropAutoincrementSql() have been marked internal.
OraclePlatform::assertValidIdentifier()The OraclePlatform::assertValidIdentifier() method has been deprecated.
Table::getColumns()Column::getName() instead. In order to retrieve a column by name, use Table::getColumn().$fromColumn argument to the ColumnDiff constructor.Not passing the $fromColumn argument to the ColumnDiff constructor is deprecated.
AbstractPlatform::getName()Relying on the name of the platform is discouraged. To identify the platform, use its class name.
PostgreSQL94Platform and PostgreSQL94Keywords. Use PostgreSQLPlatform and PostgreSQLKeywords instead.SQLServer2012Platform and SQLServer2012Keywords. Use SQLServerPlatform and SQLServerKeywords instead.Comparator class outside the DBAL is deprecated. Use SchemaManager::createComparator()
to create the comparator specific to the current database connection and the database platform.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.
AbstractPlatform::prefersIdentityColumns().Whether to use identity columns should be decided by the application developer. For example, based on the set of supported database platforms.
AbstractPlatform::getNowExpression().Relying on dates generated by the database is deprecated. Generate dates within the application.
ForeignKeyConstraint to its local (referencing) Table.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.
AbstractPlatform methods.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.
AbstractPlatform methods that describe the default and the maximum column lengths.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.
Comparator::compareSchemas($fromSchema, $toSchema)The usage of Comparator::compareSchemas($fromSchema, $toSchema) statically is
deprecated in order to provide a more consistent API.
Comparator::compare($fromSchema, $toSchema)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.
Connection::lastInsertId($name)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 methods marked internal.PostgreSQLSchemaManager::getExistingSchemaSearchPaths() and ::determineExistingSchemaSearchPaths() have been marked internal.
OracleSchemaManager methods marked internal.OracleSchemaManager::dropAutoincrement() has been marked internal.
AbstractPlatform::getReservedKeywordsClass()Instead of implementing getReservedKeywordsClass(), AbstractPlatform subclasses should implement
createReservedKeywordsList().
ReservedWordsCommand::setKeywordListClass()The usage of ReservedWordsCommand::setKeywordListClass() has been deprecated. To add or replace a keyword list,
use setKeywordList() instead.
$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.
Connection::$_schemaManager and Connection::getSchemaManager()The usage of Connection::$_schemaManager and Connection::getSchemaManager() is deprecated.
Use Connection::createSchemaManager() instead.
Connection::$_expr and Connection::getExpressionBuilder()The usage of Connection::$_expr and Connection::getExpressionBuilder() is deprecated.
Use Connection::createExpressionBuilder() instead.
QueryBuilder::execute()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.
Doctrine\DBAL\Abstraction\Result removedThe Doctrine\DBAL\Abstraction\Result interface is removed. Use the Doctrine\DBAL\Result class instead.
Doctrine\DBAL\Types\Type::getDefaultLength() removedThe Doctrine\DBAL\Types\Type::getDefaultLength() method has been removed as it served no purpose.
Doctrine\DBAL\DBALException class renamedThe Doctrine\DBAL\DBALException class has been renamed to Doctrine\DBAL\Exception.
Doctrine\DBAL\Schema\Table constructor new parameterDeprecated 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 = [])
SchemaManager::dropDatabase()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.
Synchronizer packageThe Doctrine\DBAL\Schema\Synchronizer\SchemaSynchronizer interface and all its implementations have been removed.
Connection methodsThe 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.
DBALException factory methodsThe following factory methods of the DBALException class have been removed:
DBALException::invalidPlatformSpecified().DBALException::invalidPdoInstance().PDO namespaceThe 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$platform argument of all schema manager constructors is no longer optional.$platform argument has been added to the Driver::getSchemaManager() method.Driver interface have been made final.PDO\Connection and PDO\Statement classes have been made final.PDOSqlsrv\Connection and PDOSqlsrv\Statement classes have been made final and no longer extend the corresponding PDO classes.SQLSrv\LastInsertId class has been made final.DBALException::invalidTableName() has been replaced with the InvalidTableName class.
convertException() method has been removed from the Driver interface. The logic of exception conversion has been moved to the ExceptionConverter interface. The drivers now must implement the getExceptionConverter() method.driverException() and driverExceptionDuringQuery() factory methods have been removed from the DBALException class.Error) are no longer wrapped in a DBALException.Driver\Exception.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.
ExceptionConverterDriver interface is removedAll drivers must implement the convertException() method which is now part of the Driver interface.
PingableConnection interface is removedThe 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\SQLSrvStatementServerInfoAwareConnection::requiresQueryForServerVersion() is removed.The ServerInfoAwareConnection::requiresQueryForServerVersion() method has been removed as an implementation detail which is the same for all supported drivers.
Doctrine\DBAL\Driver\DriverException::getErrorCode() method is removed. In order to obtain the driver error code, please use ::getCode() or ::getSQLState().Doctrine\DBAL\Driver\PDOException::getSQLState() no longer falls back to the driver error code.OracleSchemaManager::createDatabase()The $database argument is no longer nullable or optional.
Doctrine\DBAL\Types\Type::__toString() removedRelying on string representation was discouraged and has been removed.
Doctrine\DBAL\Schema APIDoctrine\DBAL\Schema\AbstractSchemaManager::_getPortableFunctionsList()Doctrine\DBAL\Schema\AbstractSchemaManager::_getPortableFunctionDefinition()Doctrine\DBAL\Schema\OracleSchemaManager::_getPortableFunctionDefinition()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).
Doctrine\DBAL\Connection API::getHost(), ::getPort(), ::getUsername(), ::getPassword().Doctrine\DBAL\Event APIConnectionEventArgs::getDriver(), ::getDatabasePlatform() and ::getSchemaManager() methods have been removed. The connection information can be obtained from the connection which is available via ::getConnection().SchemaColumnDefinitionEventArgs::getDatabasePlatform() and SchemaIndexDefinitionEventArgs::getDatabasePlatform() have been removed for the same reason as above.Doctrine\DBAL\Driver::getDatabase() method has been removed. Please use Doctrine\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.Doctrine\DBAL\Connection::getDatabase(), when connected to an SQLite database, will no longer return the database file path.Doctrine\DBAL\Driver::getName() removedThe Doctrine\DBAL\Driver::getName() has been removed.
json_array type removedRemoved json_array type and all associated hacks.
It is recommened to migrate to the json type while still being on the ORM 2
branch. You then need to migrate the database (using migrations or SchemaTool)
to update both the type and especially remove the (Dc2Type:json_array) column
comment, before you ugprade to DBAL 3.
If you cannot migrate the database or rely on this type, especially its behavior with regard to NULL and empty values, you can copy (adapt) the JsonArrayType class into your own codebase and re-regsiter under the name:
use Doctrine\DBAL\Types\TypeFactory;
use MyApp\Doctrine\Types\JsonArrayType;
TypeRegistry::register('json_array', new JsonArrayType());
Or if you want to opt into the newer type instead, with its slightly changed null behavior, you can register that with:
use Doctrine\DBAL\Types\TypeFactory;
use Doctrine\DBAL\Types\JsonType;
TypeRegistry::register('json_array', new JsonType());
In Symfony you can register this type with:
doctrine:
dbal:
types:
json_array: "Doctrine\\DBAL\\Types\\JsonType"
Connection::TRANSACTION_* constants.AbstractPlatform::DATE_INTERVAL_UNIT_* and AbstractPlatform::TRIM_* constants.AbstractPlatform::getSQLResultCasing(), ::prefersSequences() and ::supportsForeignKeyOnUpdate() methods.PostgreSqlPlatform::getDisallowDatabaseConnectionsSQL() and ::getCloseActiveDatabaseConnectionsSQL() methods.MysqlSessionInit listener.MySQLPlatform::getCollationFieldDeclaration().AbstractPlatform::getIdentityColumnNullInsertSQL().AbstractPlatform::fixSchemaElementName().Table::addUnnamedForeignKeyConstraint() and Table::addNamedForeignKeyConstraint().Table::renameColumn().SQLParserUtils::getPlaceholderPositions().LoggerChain::addLogger.AbstractSchemaManager::getFilterSchemaAssetsExpression(), Configuration::getFilterSchemaAssetsExpression()
and Configuration::getFilterSchemaAssetsExpression().SQLParserUtils::*_TOKEN constants made private.Driver::connect() signatureThe 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.
MasterSlaveConnectionThis class was deprecated in favor of PrimaryReadReplicaConnection
Portability\Connection::PORTABILITY_{PLATFORM}) were internal implementation details which are no longer relevant.Portability\Connection class no longer extends the DBAL Connection.Portability\Class class has been made final.Statement interface no longer extends ResultStatement.ResultStatement interface has been renamed to Result.bool, Statement::execute() now returns a Result that should be used for fetching the result data and metadata.Statement::closeCursor() is now available via Result::free(). The behavior of fetching data from a freed result is no longer portable. In this case, some drivers will return false while others may throw an exception.Additional related changes:
ArrayStatement and ResultCacheStatement classes from the Cache package have been renamed to ArrayResult and CachingResult respectively and marked @internal.Statement::rowCount() is moved.Statement::rowCount() has been moved to the ResultStatement interface where it belongs by definition.
FetchMode and the corresponding methodsFetchMode class and the setFetchMode() method of the Connection and Statement interfaces are removed.Statement::fetch() method is replaced with fetchNumeric(), fetchAssociative() and fetchOne().Statement::fetchAll() method is replaced with fetchAllNumeric(), fetchAllAssociative() and fetchColumn().Statement::fetchColumn() method is replaced with fetchOne().Connection::fetchArray() and fetchAssoc() methods are replaced with fetchNumeric() and fetchAssociative() respectively.StatementIterator class is removed. The usage of a Statement object as Traversable is no longer possible. Use iterateNumeric(), iterateAssociative() and iterateColumn() instead.FetchMode::MIXED) is no longer possible.Statement::execute()The statement implementations no longer detect whether $params is a zero- or one-based array. A zero-based numeric array is expected.
Statement::project() has been removedStatement::project() method has been removed. Use ::executeQuery() and fetch the data from the statement using one of the Statement::fetch*() methods instead.::errorCode() and ::errorInfo() removed from Connection and Statement APIsThe error information is available in DriverException thrown in case of an error.
FetchMode::CUSTOM_OBJECT and ::STANDARD_OBJECTInstead of fetching an object, fetch an array and map it to an object of the desired class.
$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.
EchoSQLLoggerEchoSQLLogger 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\PostgreSQL92KeywordsDBAL 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).
ServerInfoAwareConnection interface now extends ConnectionAll implementations of the ServerInfoAwareConnection interface have to implement the methods defined in the Connection interface as well.
VersionAwarePlatformDriver interface now extends DriverAll implementations of the VersionAwarePlatformDriver interface have to implement the methods defined in the Driver interface as well.
MsSQLKeywords classThe Doctrine\DBAL\Platforms\MsSQLKeywords class has been removed.
Please use Doctrine\DBAL\Platforms\SQLServerPlatform instead.
This PDO-based 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\DriverDBAL 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\SQLServer2008KeywordsThe AbstractSQLServerDriver class and its subclasses no longer implement the VersionAwarePlatformDriver interface.
Doctrine\DBAL\VersionThe Doctrine\DBAL\Version class is no longer available: please refrain from checking the DBAL version at runtime.
PDO instance is no longer supportedIn order to share the same PDO instances between DBAL and other components, initialize the connection in DBAL and access it using Connection::getWrappedConnection()->getWrappedConnection().
PDO::PARAM_*, PDO::FETCH_*, PDO::CASE_* and PDO::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 underlying PDO 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.
dbal:import CLI commandThe 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.:
mysql [dbname] < data.sql.psql [dbname] < data.sql.sqlite3 /path/to/file.db < data.sql.ExceptionConverter::convert()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
DriverException constructor is now internalThe constructor of Doctrine\DBAL\Exception\DriverException is now @internal.
ConfigurationConfiguration methods are now typedConfiguration::setSchemaAssetsFilter() now returns voidConfiguration::$_attributes has been removed; use individual properties in subclasses instead