ConnectionMigrator

class \TYPO3\CMS\Core\Database\Schema\ConnectionMigrator

Handling schema migrations per connection.

Tags

todo

The whole ConnectionMigrator and comparison stack needs a refactoring. Specially, the normalization steps needs to be centralized and reworked to a more workable solution. Additionally, the reporting states are eligible for a refactoring to a more suitable solution to group into safe and unsafe operations along with database value normalization for column alterations. Further, operating on the properties for the diff classes is also suboptimal and should be refactored with care. For example, the normalize* methods should be reworked.

Table of Contents

Properties

$deletedPrefix  : string

Methods

__construct()  : mixed
getSchemaDiff()  : SchemaDiff
Return the raw Doctrine SchemaDiff object for the current connection.
getUpdateSuggestions()  : array
Compare current and expected schema definitions and provide updates suggestions in the form of SQL statements.
install()  : array
Perform add/change/create operations on tables and fields in an optimized, non-interactive, mode.
applyDefaultOptionsToTable()  : void
applyDefaultPlatformOptionsToColumns()  : void
buildExistingSchemaDefinitions()  : Schema
buildExpectedSchemaDefinitions()  : Schema
Build the expected schema definitions from raw SQL statements.
buildQuotedColumn()  : Column
Helper function to build a column object that has the _quoted attribute set so that the SchemaManager will use quoted identifiers when creating the final SQL statements. This is needed as Doctrine doesn't provide a method to set the flag after the object has been instantiated and there's no possibility to hook into the createSchema() method early enough to influence the original column object.
buildQuotedForeignKey()  : ForeignKeyConstraint
Helper function to build a foreign key constraint object that has the _quoted attribute set so that the SchemaManager will use quoted identifiers when creating the final SQL statements. This is needed as Doctrine doesn't provide a method to set the flag after the object has been instantiated and there's no possibility to hook into the createSchema() method early enough to influence the original column object.
buildQuotedIndex()  : Index
Helper function to build an index object that has the _quoted attribute set so that the SchemaManager will use quoted identifiers when creating the final SQL statements. This is needed as Doctrine doesn't provide a method to set the flag after the object has been instantiated and there's no possibility to hook into the createSchema() method early enough to influence the original column object.
buildQuotedTable()  : Table
Helper function to build a table object that has the _quoted attribute set so that the SchemaManager will use quoted identifiers when creating the final SQL statements. This is needed as Doctrine doesn't provide a method to set the flag after the object has been instantiated and there's no possibility to hook into the createSchema() method early enough to influence the original table object.
buildSchemaDiff()  : SchemaDiff
If the schema is not for the Default connection remove all tables from the schema that have no mapping in the TYPO3 configuration. This avoids update suggestions for tables that are in the database but have no direct relation to the TYPO3 instance.
calculateUpdateSuggestionsHashes()  : array<non-empty-string, non-empty-string>
Replace the array keys with a md5 sum of the actual SQL statement
getChangedFieldUpdateSuggestions()  : array
Extract update suggestions (SQL statements) for changed fields from the complete schema diff.
getChangedTableOptions()  : array
Extract update suggestions (SQL statements) for changed options (like ENGINE) from the complete schema diff.
getConnectionNameForTable()  : string
Determine the connection name for a table
getDatabasePlatformForTable()  : AbstractPlatform
getDropFieldUpdateSuggestions()  : array
Extract update suggestions (SQL statements) for fields that can be removed from the complete schema diff.
getDropTableUpdateSuggestions()  : array
Extract update suggestions (SQL statements) for tables that can be removed from the complete schema diff.
getNewFieldUpdateSuggestions()  : array
Extract the update suggestions (SQL statements) for newly added fields from the complete schema diff.
getNewTableUpdateSuggestions()  : array
Extract the update suggestions (SQL statements) for newly added tables from the complete schema diff.
getSchemaTableNames()  : mixed
getTableOptions()  : array[]
Get COLLATION, ROW_FORMAT, COMMENT and ENGINE table options on MySQL connections.
getTableRecordCount()  : int
Return the amount of records in the given table.
getUnusedFieldUpdateSuggestions()  : array
Extract update suggestions (SQL statements) for fields that are no longer present in the expected schema from the schema diff.
getUnusedTableUpdateSuggestions()  : array
Extract update suggestions (SQL statements) for tables that are no longer present in the expected schema from the schema diff.
getViewNames()  : array<int, string>
Names of the views of this connection.
hasFullCollationNameSupport()  : bool
MariaDB 11.4 introduced the UCA-1400 collations along with a new `FULL_COLLATION_NAME` column in `information_schema.COLLATION_CHARACTER_SET_APPLICABILITY`.
migrateColumnRenamesToDistinctActions()  : SchemaDiff
Revert the automatic rename optimization that Doctrine performs when it detects a column being added and a column being dropped that only differ by name.
migrateUnprefixedRemovedFieldsToRenames()  : SchemaDiff
Scan the list of changed tables for fields that are going to be dropped. If the name of the field does not start with the deleted prefix mark the column for a rename instead of a drop operation.
migrateUnprefixedRemovedTablesToRenames()  : SchemaDiff
Move tables to be removed that are not prefixed with the deleted prefix to the list of changed tables and set a new prefixed name.
normalizeDecimalTypeColumnDefaultValue()  : void
Normalize DecimalType fields default values to have the correct format defined by the column scale settings to ensure working comparison with Doctrine DBAL v4 {@see AbstractPlatform::columnsEqual()}.
normalizeTableColumnIdentifiers()  : Column[]
Ensure correct initialized identifier names for table columns.
normalizeTableForeignKeyConstraints()  : ForeignKeyConstraint[]
normalizeTableForMariaDBOrMySQL()  : void
Doctrine DBAL 4+ removed the default length for string and binary fields, but they are required for MariaDB and MySQL database backends. Therefore, we need to normalize the tables and set column length for fields not having them.
normalizeTableForPostgreSQL()  : void
Normalize fields towards PostgreSQL compatibility.
normalizeTableForSQLite()  : void
Normalize fields towards SQLite compatibility.
normalizeTableIdentifiers()  : void
normalizeTableIndex()  : void
normalizeTableIndexIdentifiers()  : Index[]
Ensure correct initialized identifier names for table indexes.
normalizeTablesForTargetConnection()  : Table[]
Due to portability reasons it is necessary to normalize the virtual generated schema against the target connection platform.
normalizeTableUniqueConstraintIdentifiers()  : UniqueConstraint[]
Ensure correct initialized identifier names for table unique constraints.
prepareColumnOptions()  : array
removeUnrelatedTables()  : array<non-empty-string, TableDiff|Table>
Helper for buildSchemaDiff to filter an array of TableDiffs against a list of valid table names.

Properties

$deletedPrefix

protected string $deletedPrefix = 'zzz_deleted_'

Prefix of deleted tables

Methods

getSchemaDiff()

Return the raw Doctrine SchemaDiff object for the current connection.

public getSchemaDiff() : SchemaDiff

This diff contains all changes without any pre-processing.

Return values

SchemaDiff

getUpdateSuggestions()

Compare current and expected schema definitions and provide updates suggestions in the form of SQL statements.

public getUpdateSuggestions([bool $remove = false ]) : array

Parameters

$remove : bool = false

Return values

array

install()

Perform add/change/create operations on tables and fields in an optimized, non-interactive, mode.

public install([bool $createOnly = false ]) : array

Parameters

$createOnly : bool = false

Return values

array

applyDefaultOptionsToTable()

protected applyDefaultOptionsToTable(AbstractPlatform $platform, SchemaConfig $schemaConfig, Table $table) : void

Parameters

$platform : AbstractPlatform
$schemaConfig : SchemaConfig
$table : Table

applyDefaultPlatformOptionsToColumns()

protected applyDefaultPlatformOptionsToColumns(AbstractPlatform $platform, SchemaConfig $schemaConfig, Table $table) : void

Parameters

$platform : AbstractPlatform
$schemaConfig : SchemaConfig
$table : Table

buildExistingSchemaDefinitions()

protected buildExistingSchemaDefinitions(AbstractSchemaManager $schemaManager) : Schema

Parameters

$schemaManager : AbstractSchemaManager

Return values

Schema

buildExpectedSchemaDefinitions()

Build the expected schema definitions from raw SQL statements.

protected buildExpectedSchemaDefinitions(string $connectionName, AbstractSchemaManager $schemaManager) : Schema

Parameters

$connectionName : string
$schemaManager : AbstractSchemaManager

Tags

throws
Exception
throws
InvalidArgumentException

Return values

Schema

buildQuotedColumn()

Helper function to build a column object that has the _quoted attribute set so that the SchemaManager will use quoted identifiers when creating the final SQL statements. This is needed as Doctrine doesn't provide a method to set the flag after the object has been instantiated and there's no possibility to hook into the createSchema() method early enough to influence the original column object.

protected buildQuotedColumn(Column $column) : Column

Parameters

$column : Column

Return values

Column

buildQuotedForeignKey()

Helper function to build a foreign key constraint object that has the _quoted attribute set so that the SchemaManager will use quoted identifiers when creating the final SQL statements. This is needed as Doctrine doesn't provide a method to set the flag after the object has been instantiated and there's no possibility to hook into the createSchema() method early enough to influence the original column object.

protected buildQuotedForeignKey(ForeignKeyConstraint $index) : ForeignKeyConstraint

Parameters

$index : ForeignKeyConstraint

Return values

ForeignKeyConstraint

buildQuotedIndex()

Helper function to build an index object that has the _quoted attribute set so that the SchemaManager will use quoted identifiers when creating the final SQL statements. This is needed as Doctrine doesn't provide a method to set the flag after the object has been instantiated and there's no possibility to hook into the createSchema() method early enough to influence the original column object.

protected buildQuotedIndex(Index $index) : Index

Parameters

$index : Index

Return values

Index

buildQuotedTable()

Helper function to build a table object that has the _quoted attribute set so that the SchemaManager will use quoted identifiers when creating the final SQL statements. This is needed as Doctrine doesn't provide a method to set the flag after the object has been instantiated and there's no possibility to hook into the createSchema() method early enough to influence the original table object.

protected buildQuotedTable(Table $table) : Table

Parameters

$table : Table

Return values

Table

buildSchemaDiff()

If the schema is not for the Default connection remove all tables from the schema that have no mapping in the TYPO3 configuration. This avoids update suggestions for tables that are in the database but have no direct relation to the TYPO3 instance.

protected buildSchemaDiff([bool $renameUnused = true ]) : SchemaDiff

Parameters

$renameUnused : bool = true

Tags

throws
Exception
throws
SchemaException
throws
InvalidArgumentException

Return values

SchemaDiff

calculateUpdateSuggestionsHashes()

Replace the array keys with a md5 sum of the actual SQL statement

protected calculateUpdateSuggestionsHashes(string[] $statements) : array<non-empty-string, non-empty-string>

Parameters

$statements : string[]

Return values

array<non-empty-string, non-empty-string>

getChangedFieldUpdateSuggestions()

Extract update suggestions (SQL statements) for changed fields from the complete schema diff.

protected getChangedFieldUpdateSuggestions(SchemaDiff $schemaDiff) : array

Parameters

$schemaDiff : SchemaDiff

Tags

throws
SchemaException
throws
InvalidArgumentException

Return values

array

getChangedTableOptions()

Extract update suggestions (SQL statements) for changed options (like ENGINE) from the complete schema diff.

protected getChangedTableOptions(SchemaDiff $schemaDiff) : array

Parameters

$schemaDiff : SchemaDiff

Tags

throws
SchemaException
throws
InvalidArgumentException

Return values

array

getConnectionNameForTable()

Determine the connection name for a table

protected getConnectionNameForTable(string $tableName) : string

Parameters

$tableName : string

Tags

throws
InvalidArgumentException

Return values

string

getDatabasePlatformForTable()

protected getDatabasePlatformForTable(string $tableName) : AbstractPlatform

Parameters

$tableName : string

Return values

AbstractPlatform

getDropFieldUpdateSuggestions()

Extract update suggestions (SQL statements) for fields that can be removed from the complete schema diff.

protected getDropFieldUpdateSuggestions(SchemaDiff $schemaDiff) : array

Fields that can be removed have been prefixed in a previous run of the schema migration.

Parameters

$schemaDiff : SchemaDiff

Tags

throws
SchemaException
throws
InvalidArgumentException

Return values

array

getDropTableUpdateSuggestions()

Extract update suggestions (SQL statements) for tables that can be removed from the complete schema diff.

protected getDropTableUpdateSuggestions(SchemaDiff $schemaDiff) : array

Tables that can be removed have been prefixed in a previous run of the schema migration.

Parameters

$schemaDiff : SchemaDiff

Tags

throws
SchemaException
throws
InvalidArgumentException

Return values

array

getNewFieldUpdateSuggestions()

Extract the update suggestions (SQL statements) for newly added fields from the complete schema diff.

protected getNewFieldUpdateSuggestions(SchemaDiff $schemaDiff) : array

Parameters

$schemaDiff : SchemaDiff

Tags

throws
SchemaException
throws
InvalidArgumentException

Return values

array

getNewTableUpdateSuggestions()

Extract the update suggestions (SQL statements) for newly added tables from the complete schema diff.

protected getNewTableUpdateSuggestions(SchemaDiff $schemaDiff) : array

Parameters

$schemaDiff : SchemaDiff

Tags

throws
InvalidArgumentException

Return values

array

getSchemaTableNames()

protected getSchemaTableNames(Schema $schema) : mixed

Parameters

$schema : Schema

getTableOptions()

Get COLLATION, ROW_FORMAT, COMMENT and ENGINE table options on MySQL connections.

protected getTableOptions(string[] $tableNames) : array[]

Parameters

$tableNames : string[]

Tags

throws
InvalidArgumentException

Return values

array[]

getTableRecordCount()

Return the amount of records in the given table.

protected getTableRecordCount(string $tableName) : int

Parameters

$tableName : string

Tags

throws
InvalidArgumentException

Return values

int

getUnusedFieldUpdateSuggestions()

Extract update suggestions (SQL statements) for fields that are no longer present in the expected schema from the schema diff.

protected getUnusedFieldUpdateSuggestions(SchemaDiff $schemaDiff) : array

In this case the update suggestions are renames of the fields with a prefix to mark them for deletion in a second sweep.

Parameters

$schemaDiff : SchemaDiff

Tags

throws
SchemaException
throws
InvalidArgumentException

Return values

array

getUnusedTableUpdateSuggestions()

Extract update suggestions (SQL statements) for tables that are no longer present in the expected schema from the schema diff.

protected getUnusedTableUpdateSuggestions(SchemaDiff $schemaDiff) : array

In this case the update suggestions are renames of the tables with a prefix to mark them for deletion in a second sweep.

Parameters

$schemaDiff : SchemaDiff

Tags

throws
SchemaException
throws
InvalidArgumentException

Return values

array

getViewNames()

Names of the views of this connection.

protected getViewNames(AbstractSchemaManager $schemaManager) : array<int, string>

Parameters

$schemaManager : AbstractSchemaManager

Return values

array<int, string>

hasFullCollationNameSupport()

MariaDB 11.4 introduced the UCA-1400 collations along with a new `FULL_COLLATION_NAME` column in `information_schema.COLLATION_CHARACTER_SET_APPLICABILITY`.

protected hasFullCollationNameSupport() : bool

For these collations COLLATION_NAME only holds the character-set independent part, for example uca1400_ai_ci, while FULL_COLLATION_NAME holds utf8mb4_uca1400_ai_ci which is what information_schema.TABLES.TABLE_COLLATION reports. Joining on COLLATION_NAME would therefore not match at all for tables using such a collation.

Return values

bool

migrateColumnRenamesToDistinctActions()

Revert the automatic rename optimization that Doctrine performs when it detects a column being added and a column being dropped that only differ by name.

protected migrateColumnRenamesToDistinctActions(SchemaDiff $schemaDiff) : SchemaDiff

Parameters

$schemaDiff : SchemaDiff

Tags

throws
SchemaException
throws
InvalidArgumentException

Return values

SchemaDiff

migrateUnprefixedRemovedFieldsToRenames()

Scan the list of changed tables for fields that are going to be dropped. If the name of the field does not start with the deleted prefix mark the column for a rename instead of a drop operation.

protected migrateUnprefixedRemovedFieldsToRenames(SchemaDiff $schemaDiff) : SchemaDiff

Parameters

$schemaDiff : SchemaDiff

Tags

throws
InvalidArgumentException

Return values

SchemaDiff

migrateUnprefixedRemovedTablesToRenames()

Move tables to be removed that are not prefixed with the deleted prefix to the list of changed tables and set a new prefixed name.

protected migrateUnprefixedRemovedTablesToRenames(SchemaDiff $schemaDiff) : SchemaDiff

Without this help the Doctrine SchemaDiff has no idea if a table has been renamed and performs a drop of the old table and creates a new table, which leads to all data in the old table being lost.

Parameters

$schemaDiff : SchemaDiff

Tags

throws
InvalidArgumentException

Return values

SchemaDiff

normalizeDecimalTypeColumnDefaultValue()

Normalize DecimalType fields default values to have the correct format defined by the column scale settings to ensure working comparison with Doctrine DBAL v4 {@see AbstractPlatform::columnsEqual()}.

protected normalizeDecimalTypeColumnDefaultValue(AbstractPlatform $platform, Table $table) : void

Parameters

$platform : AbstractPlatform
$table : Table

normalizeTableColumnIdentifiers()

Ensure correct initialized identifier names for table columns.

protected normalizeTableColumnIdentifiers(AbstractPlatform $platform, Column[] $columns) : Column[]

Parameters

$platform : AbstractPlatform
$columns : Column[]

Return values

Column[]

normalizeTableForeignKeyConstraints()

protected normalizeTableForeignKeyConstraints(AbstractPlatform $platform, ForeignKeyConstraint[] $foreignKeyConstraints) : ForeignKeyConstraint[]

Parameters

$platform : AbstractPlatform
$foreignKeyConstraints : ForeignKeyConstraint[]

Return values

ForeignKeyConstraint[]

normalizeTableForMariaDBOrMySQL()

Doctrine DBAL 4+ removed the default length for string and binary fields, but they are required for MariaDB and MySQL database backends. Therefore, we need to normalize the tables and set column length for fields not having them.

protected normalizeTableForMariaDBOrMySQL(AbstractPlatform $databasePlatform, Table $table) : void

Missing column length may happen by the DefaultTCASchema enriched structure information, which is and should be database vendor unaware. Therefore, we normalize this here now.

Parameters

$databasePlatform : AbstractPlatform
$table : Table

Tags

see
https://github.com/doctrine/dbal/blob/4.0.x/UPGRADE.md#bc-break-changes-in-handling-string-and-binary-columns
see
https://github.com/doctrine/dbal/blob/3.7.x/UPGRADE.md#deprecated-abstractplatform-methods-that-describe-the-default-and-the-maximum-column-lengths

normalizeTableForPostgreSQL()

Normalize fields towards PostgreSQL compatibility.

protected normalizeTableForPostgreSQL(AbstractPlatform $databasePlatform, Table $table) : void

Parameters

$databasePlatform : AbstractPlatform
$table : Table

normalizeTableIdentifiers()

protected normalizeTableIdentifiers(AbstractPlatform $platform, Table &$table) : void

Parameters

$platform : AbstractPlatform
$table : Table

normalizeTableIndex()

protected normalizeTableIndex(AbstractPlatform $platform, Connection $connection, SchemaConfig $schemaConfig, Table &$table) : void

Parameters

$platform : AbstractPlatform
$connection : Connection
$schemaConfig : SchemaConfig
$table : Table

normalizeTableIndexIdentifiers()

Ensure correct initialized identifier names for table indexes.

protected normalizeTableIndexIdentifiers(AbstractPlatform $platform, Index[] $indexes) : Index[]

Parameters

$platform : AbstractPlatform
$indexes : Index[]

Return values

Index[]

normalizeTablesForTargetConnection()

Due to portability reasons it is necessary to normalize the virtual generated schema against the target connection platform.

protected normalizeTablesForTargetConnection(Connection $connection, SchemaConfig $schemaConfig, Table[] $tables) : Table[]
  • SQLite: Needs some special treatment regarding autoincrement fields. [1]
  • MySQL/MariaDB: varchar fields needs to have a length, but doctrine dropped the default size. This need's to be addressed in application code. [2][3]

Parameters

$connection : Connection
$schemaConfig : SchemaConfig
$tables : Table[]

Tags

see
https://github.com/doctrine/dbal/commit/33555d36e7e7d07a5880e01

[1]

see
https://github.com/doctrine/dbal/blob/3.7.x/UPGRADE.md#deprecated-abstractplatform-methods-that-describe-the-default-and-the-maximum-column-lengths

[2]

see
https://github.com/doctrine/dbal/blob/4.0.x/UPGRADE.md#bc-break-changes-in-handling-string-and-binary-columns

[3]

throws
Exception

Return values

Table[]

normalizeTableUniqueConstraintIdentifiers()

Ensure correct initialized identifier names for table unique constraints.

protected normalizeTableUniqueConstraintIdentifiers(AbstractPlatform $platform, UniqueConstraint[] $uniqueConstraints) : UniqueConstraint[]

Parameters

$platform : AbstractPlatform
$uniqueConstraints : UniqueConstraint[]

Return values

UniqueConstraint[]

prepareColumnOptions()

protected prepareColumnOptions(Column $column) : array

Parameters

$column : Column

Return values

array

removeUnrelatedTables()

Helper for buildSchemaDiff to filter an array of TableDiffs against a list of valid table names.

protected removeUnrelatedTables(array<non-empty-string, TableDiff|TableDiff|Table> $tableDiffs, string[] $validTableNames) : array<non-empty-string, TableDiff|Table>

Parameters

$tableDiffs : array<non-empty-string, TableDiff|TableDiff|Table>
$validTableNames : string[]

Tags

throws
InvalidArgumentException

Return values

array<non-empty-string, TableDiff|Table>
On this page