Issue Epic New Stale

#110420Rework the database analyzer stack

Stefan Bürk 08/11/26, 01:20 updated 09/02/26, 12:20

Description

Problem

The database analyzer describes a schema change as an SQL statement, grouped by the kind of operation and keyed by the md5 hash of the statement itself. What a change does, whether it removes anything, and which statements belong together can only be re-derived from those array keys, and every consumer does that on its own – usually with a hardcoded list such as ['add', 'change', 'create_table', 'change_table'].

Statements of one table depend on each other, so offering each of them for selection allows a table to be left in a state it cannot be left in: an index can be selected without the column it needs, and on a platform that rebuilds a table to alter it, half of a copy, drop, create and copy-back sequence can be applied.

On top of that the stack carries mutable copies of doctrine classes that doctrine marks as final (TableDiff, SchemaDiff, Comparator), extends the doctrine platforms for a type comment that only MySQL needs, and introspects through an API doctrine has deprecated.

Scope

This epic collects the rework: the table becomes the unit of analysis and application, the result becomes a set of immutable objects, the doctrine extensions go away, and the install tool and the command line are built on the new API. It also collects the bugs found while doing it – two of which can destroy a database.

The whole analyzer stack is annotated internal@ and is not part of the public core API. The changes are still documented, because extensions do reach into it.

Sub-tasks

The sub-tasks are listed below and are meant to be reviewed and merged in the order of the Gerrit relation chain:

  1. #110421 – Install tool answers with an empty response when an exception is handled – Gerrit 95186
  2. #110422 – An index over a column that does not exist destroys a SQLite database – Gerrit 95187
  3. #110423 – ALTER TABLE ADD COLUMN fails on SQLite for json and uuid columns – Gerrit 95188
  4. #110424 – Introspect the schema through the non-deprecated doctrine API – Gerrit 95189
  5. #110425 – Reduce column type comment handling to MySQL – Gerrit 95190
  6. #110426 – Generate table option changes without platform hooks – Gerrit 95191
  7. #110427 – Rework the database analyzer stack onto objects – Gerrit 95192
  8. #110428 – Console command for database schema updates – Gerrit 95193
  9. #110429 – Remove the array shaped schema migrator API – Gerrit 95194
  10. #110430 – Remove SchemaMigrator::install() – Gerrit 95195

Between sub-task 3 and sub-task 4 the relation chain carries one more change that is not a sub-task of this epic – see the next section.

The one change of the series that gets no sub-task

Stack position 4, Gerrit 95240, [BUGFIX] Ignore tables that exist as views, Releases: main, 14.3, 13.4.

It resolves the already existing, already reported bug #106546 – TYPO3 Database Analyzer should ignore tables that exist as views – and carries Resolves: #106546 in its commit message. No new issue is created for it.

It sits below the rework on purpose and is implemented in the old ConnectionMigrator, which is what makes it backportable to 14.3 and 13.4. The rework (sub-task 7, Gerrit 95192) carries the same behaviour into DatabaseSchemaAnalyzer as part of itself, with no separate mention, and sub-task 9 (Gerrit 95194) deletes the old path together with its test.

That change takes views out of the comparison and nothing else. Making what is compared configurable in general belongs to #101235 and is not claimed here.

Not in scope, on purpose

  • A SQLite database that already contains an index over a missing column cannot be repaired by TYPO3. The TypeError comes out of the doctrine generator before TYPO3 sees anything, and the metadata provider cannot be decorated – platforms narrow the return type of createMetadataProvider() to final readonly classes. Sub-task 2 prevents the state; an existing one needs a manual DROP INDEX.
  • Making the comparison scope configurable in general – which tables and which connections are compared at all – belongs to #101235 and is not part of this series. The view fix at stack position 4 is the view case only.
  • The extension point for ColumnDataMigration. The rework prepares for it and marks the places with @todo markers, but whether it becomes a PSR-14 event or an interface with registered migrations is deliberately not decided in this series. See sub-task 7.

Patches

All changes are pushed to Gerrit under the topic database-analyzer.

Related, not claimed

#101235, #93643, #106719, #108028.

Reviews 23

Subtasks 11