Issue Task Under Review Stale

#110427Rework the database analyzer stack onto objects

Stefan Bürk 08/11/26, 01:25 updated 09/02/26, 13:16

Description

The core of the epic. See the epic description for the problem statement. The stack is reworked around objects, and the table becomes the unit of both analysis and application.

This is one change on purpose – the intermediate steps carry little value on their own and mostly confuse.

The analyzer

  • The comparison is built in one pass and returned as an immutable Dto\SchemaComparison, instead of being assembled by rewriting a doctrine SchemaDiff in place. The doctrine diff is used as it is, and what TYPO3 needs on top of it lives next to it: TableRename names the target of a table renamed to the deletion prefix, and the changed table options are a map next to the altered tables. The three in place migrate methods collapse into one rebuildTableDiff(), which undoes the rename doctrine guesses for an added and a dropped column that only differ by name – with partial ext_tables.sql files that guess is wrong far more often than it is right – and turns a dropped column without the deletion prefix into a rename to it.
  • ChangeType and ChangeSafety replace the operation key strings and are the single source of truth for the safe and destructive classification. RemovalMode names the two steps a removal takes: what is no longer expected is first renamed to the zzz_deleted_ prefix, which keeps its data, and only what already carries that prefix is dropped.
  • Dto\SchemaChange, Dto\TableChangeSet, Dto\SchemaChangeSet, Dto\SchemaOperation and Dto\ApplyResult describe what a change does. A change carries a list of statements, because a platform that cannot alter a table in place expresses one change as a copy, drop, create and copy-back sequence. TableChangeSet enforces in its constructor that a set is either entirely safe or entirely destructive.
  • SchemaMigrator::analyze(), apply() and applySafe() are the counterpart. A change set is applied as one unit – if a statement fails, the remaining statements of that set are skipped and the set is reported as failed, instead of being left half applied.
  • The security measure of the install tool now holds by construction rather than by convention: apply() re-derives the change sets and only intersects them with the given hashes, so statements are never taken from a request.
  • AlterTableStatementAggregator folds a table’s changes into a single ALTER TABLE wherever the platform accepts a list of actions. MySQL and MariaDB already render one combined statement, PostgreSQL renders one per action and is folded afterwards, and SQLite accepts exactly one action per ALTER TABLE and cannot be folded at all.
  • ColumnDataMigration carries the two column changes that lose data without an accompanying statement: the EXT:indexed_search hash columns, which changed from an integer to a string and cannot be converted, so the table is emptied first; and the PostgreSQL auto increment column, which doctrine/dbal 4 implements as an identity column instead of as a serial, so the sequence is converted in place rather than dropped and recreated with a reset value.
  • Tables that exist as a view are skipped here as well – the same behaviour the backportable fix at stack position 4 adds to ConnectionMigrator, carried into DatabaseSchemaAnalyzer as part of this change. It needs no separate mention and resolves nothing on its own.
  • PackageSetup uses applySafe() and no longer computes the whole comparison twice just to apply it. DatabaseUpgradeWizardsService reads the detected operations instead of walking raw doctrine diffs, which is what SchemaMigrator::getSchemaDiffs() existed for – it had no other consumer and is removed.
  • The array shaped suggestion API keeps building its own comparison for now, together with the mutable diff copies it needs. Both go in sub-task 9.

The install tool

The module follows the same unit and is presented as a wizard: the groups are offered one at a time, and the schema is re-analyzed after every applied step, so the next step is built from what the previous one left rather than from the analysis the module started with. The steps are whatever the analysis returns; a step with nothing in it is neither shown nor counted.

  • One card per table. The headline states what happens to the table itself – add, modify, rename, drop – and that kind is decided server side, not reconstructed in the browser from an operation list. A destructive card carries an inline badge reading Destructive - read carefully next to the table name.
  • A tab strip per card, Changes and SQL, so nothing is a control that reveals something once and is then spent.
  • A detail table per kind of change below the headline – added fields, modified fields, added indexes, modified indexes, renamed fields, dropped fields, dropped indexes, changed table options – each shown only where there is something to show. A change shows both declarations, because knowing only the new one says nothing about whether the change is wanted. The second column is headed by what it actually holds: Type for fields, Definition for indexes, New name for a rename.
  • The statements are one block to copy out, terminated for the reader; the hash is built from the statements as the analysis produced them, so that terminator never reaches what is sent back. Copying reports inline next to the control that was used – a green Copied – instead of through a notification, which renders behind the modal backdrop and is gone before it can be read.
  • A permanent card at the end of each step shows all statements of the selected tables. What a step executed can be shown after it ran, off by default, since it is a review aid rather than part of getting through the wizard.
  • Operations carry their type next to their label, so the display no longer has to recognise English wording to know what it is showing. The mapping from an analysis to what is displayed moved into DatabaseAnalyzerSuggestionService, so the structure the JavaScript reads is covered by a test built from a real analysis.

The install tool part is deliberately a first iteration and is expected to change further as the remaining features and fixes of this series land. A full redesign of that module is on the table – either together with UX experts once the feature set has settled, or as part of the install tool modal rework. That has been discussed and is not decided yet, and it is explicitly not a reason to hold this change back.

ColumnDataMigration is prepared, the extension point is not decided

Both migrations are wired into the class directly for now, and the class is shaped for taking them out again rather than for keeping them:

  • it is a stateless service, process() takes a Dto\ColumnDataMigrationRequest and returns a Dto\ColumnDataMigrationResult,
  • the request already carries more than the two implementations read – the connection name next to the connection, and a ColumnDataMigrationStage naming which part of a change is being rendered,
  • every stage asks, including the ones nothing reacts to today: renaming and dropping whole tables go through the same seam. A stage nothing matches returns its statements unchanged, which is what makes each of them a place where something can be plugged in without moving the call,
  • todo markers sit where a dispatch would go.

Whether this becomes a PSR-14 event or an interface with registered migrations is explicitly open and not part of this series. The preparation is deliberately neutral between the two – both would receive exactly the request object that exists now – and nothing here should be read as a promise of either. The consumer builds the service with GeneralUtility::makeInstance() for the same reason: it has no dependency of its own yet, so there is nothing to inject, and the call site moves to constructor injection in the change that gives it one.

Everything in the analyzer stack is annotated internal@ and is not part of the public core API.

Patch

Gerrit 95192, topic database-analyzer.

Releases: main

Reviews 1

History 010