ConnectionMigrator

Handling schema migrations per connection.

Internal

not part of public core API.

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
create()  : self
getSchemaDiff()  : SchemaDiff
Return the raw Doctrine SchemaDiff object for the current connection.
getUpdateSuggestions()  : array<string|int, mixed>
Compare current and expected schema definitions and provide updates suggestions in the form of SQL statements.
install()  : array<string|int, mixed>
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<string|int, mixed>
Extract update suggestions (SQL statements) for changed fields from the complete schema diff.
getChangedTableOptions()  : array<string|int, mixed>
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<string|int, mixed>
Extract update suggestions (SQL statements) for fields that can be removed from the complete schema diff.
getDropTableUpdateSuggestions()  : array<string|int, mixed>
Extract update suggestions (SQL statements) for tables that can be removed from the complete schema diff.
getNewFieldUpdateSuggestions()  : array<string|int, mixed>
Extract the update suggestions (SQL statements) for newly added fields from the complete schema diff.
getNewTableUpdateSuggestions()  : array<string|int, mixed>
Extract the update suggestions (SQL statements) for newly added tables from the complete schema diff.
getSchemaTableNames()  : mixed
getTableOptions()  : array<string|int, array<string|int, mixed>>
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<string|int, mixed>
Extract update suggestions (SQL statements) for fields that are no longer present in the expected schema from the schema diff.
getUnusedTableUpdateSuggestions()  : array<string|int, mixed>
Extract update suggestions (SQL statements) for tables that are no longer present in the expected schema from the schema diff.
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()  : array<string|int, Column>
Ensure correct initialized identifier names for table columns.
normalizeTableForeignKeyConstraints()  : array<string|int, 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()  : array<string|int, Index>
Ensure correct initialized identifier names for table indexes.
normalizeTablesForTargetConnection()  : array<string|int, Table>
Due to portability reasons it is necessary to normalize the virtual generated schema against the target connection platform.
normalizeTableUniqueConstraintIdentifiers()  : array<string|int, UniqueConstraint>
Ensure correct initialized identifier names for table unique constraints.
prepareColumnOptions()  : array<string|int, mixed>
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

__construct()

public __construct(string $connectionName, Connection $connection, array<string|int, Table> $tables) : mixed
Parameters
$connectionName : string
$connection : Connection
$tables : array<string|int, Table>

create()

public static create(non-empty-string $connectionName, Connection $connection, array<string|int, Table> $tables) : self
Parameters
$connectionName : non-empty-string
$connection : Connection
$tables : array<string|int, Table>
Return values
self

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<string|int, mixed>
Parameters
$remove : bool = false
Return values
array<string|int, mixed>

install()

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

public install([bool $createOnly = false ]) : array<string|int, mixed>
Parameters
$createOnly : bool = false
Return values
array<string|int, mixed>

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) : Schema
Parameters
$connectionName : string
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(array<string|int, string> $statements) : array<non-empty-string, non-empty-string>
Parameters
$statements : array<string|int, 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<string|int, mixed>
Parameters
$schemaDiff : SchemaDiff
Tags
throws
SchemaException
throws
InvalidArgumentException
Return values
array<string|int, mixed>

getChangedTableOptions()

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

protected getChangedTableOptions(SchemaDiff $schemaDiff) : array<string|int, mixed>
Parameters
$schemaDiff : SchemaDiff
Tags
throws
SchemaException
throws
InvalidArgumentException
Return values
array<string|int, mixed>

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<string|int, mixed>

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<string|int, mixed>

getDropTableUpdateSuggestions()

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

protected getDropTableUpdateSuggestions(SchemaDiff $schemaDiff) : array<string|int, mixed>

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<string|int, mixed>

getNewFieldUpdateSuggestions()

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

protected getNewFieldUpdateSuggestions(SchemaDiff $schemaDiff) : array<string|int, mixed>
Parameters
$schemaDiff : SchemaDiff
Tags
throws
SchemaException
throws
InvalidArgumentException
Return values
array<string|int, mixed>

getNewTableUpdateSuggestions()

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

protected getNewTableUpdateSuggestions(SchemaDiff $schemaDiff) : array<string|int, mixed>
Parameters
$schemaDiff : SchemaDiff
Tags
throws
InvalidArgumentException
Return values
array<string|int, mixed>

getSchemaTableNames()

protected getSchemaTableNames(Schema $schema) : mixed
Parameters
$schema : Schema

getTableOptions()

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

protected getTableOptions(array<string|int, string> $tableNames) : array<string|int, array<string|int, mixed>>
Parameters
$tableNames : array<string|int, string>
Tags
throws
InvalidArgumentException
Return values
array<string|int, array<string|int, mixed>>

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<string|int, mixed>

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<string|int, mixed>

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<string|int, mixed>

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<string|int, mixed>

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, array<string|int, Column> $columns) : array<string|int, Column>
Parameters
$platform : AbstractPlatform
$columns : array<string|int, Column>
Return values
array<string|int, Column>

normalizeTableForeignKeyConstraints()

protected normalizeTableForeignKeyConstraints(AbstractPlatform $platform, array<string|int, ForeignKeyConstraint> $foreignKeyConstraints) : array<string|int, ForeignKeyConstraint>
Parameters
$platform : AbstractPlatform
$foreignKeyConstraints : array<string|int, ForeignKeyConstraint>
Return values
array<string|int, 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, array<string|int, Index> $indexes) : array<string|int, Index>
Parameters
$platform : AbstractPlatform
$indexes : array<string|int, Index>
Return values
array<string|int, 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, array<string|int, Table> $tables) : array<string|int, 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 : array<string|int, 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
array<string|int, Table>

normalizeTableUniqueConstraintIdentifiers()

Ensure correct initialized identifier names for table unique constraints.

protected normalizeTableUniqueConstraintIdentifiers(AbstractPlatform $platform, array<string|int, UniqueConstraint> $uniqueConstraints) : array<string|int, UniqueConstraint>
Parameters
$platform : AbstractPlatform
$uniqueConstraints : array<string|int, UniqueConstraint>
Return values
array<string|int, UniqueConstraint>

prepareColumnOptions()

protected prepareColumnOptions(Column $column) : array<string|int, mixed>
Parameters
$column : Column
Return values
array<string|int, mixed>

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, array<string|int, string> $validTableNames) : array<non-empty-string, TableDiff|Table>
Parameters
$tableDiffs : array<non-empty-string, TableDiff|TableDiff|Table>
$validTableNames : array<string|int, string>
Tags
throws
InvalidArgumentException
Return values
array<non-empty-string, TableDiff|Table> 

        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results