Issue Feature Under Review Stale

#110428Console command for database schema updates

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

Description

Bringing the database schema in line with ext_tables.sql and TCA is only possible through the install tool, or as a side effect of extension:setup, which applies the safe changes of every package without a way to look at them first.

The command

database:schema:update exposes the analyzer directly. Without options it applies only changes that do not remove anything. The removal options follow the two steps a removal takes:

  • --rename renames tables and columns that are no longer expected by moving them behind the zzz_deleted_ prefix. Their data is kept.
  • --drop removes what already carries that prefix, and unused indexes, which hold no data of their own and therefore have no first step.
  • --destructive performs both, and --all puts the safe changes in front of them.

Further options are --dry-run, --rounds, and --connection and --table to limit the scope.

Why every step runs on its own analysis

Every step runs on its own analysis, and a round runs every requested step once. Two change sets of the same table are therefore never applied from the same analysis – on a platform that cannot alter a table in place, the second alteration would be rendered from a table state the first one has already left.

Dropping runs before renaming, so a single round never removes what it has just renamed; removing something entirely takes two rounds and has to be asked for with --rounds=2, which keeps the grace period the deletion prefix exists for. When the schema has not converged after the last round, the number of pending change sets is reported rather than passing silently.

Output

--sql writes the statements of the requested steps and nothing else, terminated, so the output can be piped into a file or a database client. It applies nothing. --export writes the same statements to a file while the readable output stays on screen, which allows keeping a record of what an actual run applied.

What a change set does is described per table, the same way the install tool describes it: what happens to the table as the headline, and one section per kind of change below it listing what it affects. A change shows both declarations, stacked as a removed and an added line rather than side by side, which keeps them comparable instead of doubling the width of the column exactly where they differ. A change set that names nothing – creating, dropping or renaming the table itself – stays a single line. The --sql output is untouched by this and stays statements only.

Patch

Gerrit 95193, topic database-analyzer.

Releases: main

Reviews 1

History 010