{"id":100,"date":"2026-10-29T16:00:00","date_gmt":"2026-10-29T15:00:00","guid":{"rendered":"https:\/\/hoja.in\/blog\/running-typo3-upgrade-wizards-and-schema-updates-from-the-cli\/"},"modified":"2026-10-16T14:00:12","modified_gmt":"2026-10-16T12:00:12","slug":"running-typo3-upgrade-wizards-and-schema-updates-from-the-cli","status":"publish","type":"post","link":"https:\/\/hoja.in\/blog\/running-typo3-upgrade-wizards-and-schema-updates-from-the-cli\/","title":{"rendered":"Running TYPO3 upgrade wizards and schema updates from the CLI"},"content":{"rendered":"

Clicking through the install tool works when you have one installation and one environment. With DDEV locally, a staging server and production, you click the same buttons three times and hope you clicked the same ones. On a multi-site upgrade at work that is simply not an option. Everything that touches the database during an upgrade should be a command you can put in a runbook.<\/p>\n

This post covers the core commands in TYPO3 v14 for that job, what each of them really writes, and the part that bit me most: wizards that say “done” although they migrated nothing.<\/p>\n

The commands<\/h2>\n

All of them come with the core when typo3\/cms-install<\/code> is installed (the upgrade wizard interfaces and the #[UpgradeWizard]<\/code> attribute moved to EXT:core in v14, see Deprecation #106947). In DDEV you run them with ddev exec<\/code>:<\/p>\n

# what is pending, and what was already done\nddev exec vendor\/bin\/typo3 upgrade:list\nddev exec vendor\/bin\/typo3 upgrade:list --all\n\n# run all pending wizards, or exactly one\nddev exec vendor\/bin\/typo3 upgrade:run\nddev exec vendor\/bin\/typo3 upgrade:run pageDoktypeLinkMigration\n\n# flip a wizard back to \"not done\"\nddev exec vendor\/bin\/typo3 upgrade:mark:undone pageDoktypeLinkMigration\n\n# set up extensions: schema, static data, extension configuration\nddev exec vendor\/bin\/typo3 extension:setup\nddev exec vendor\/bin\/typo3 extension:setup -e sitepackage<\/code><\/pre>\n
On hoja.in after the move to v14.3, upgrade:list<\/code> says No wizards available.<\/code>, and upgrade:list --all<\/code> shows a table with every wizard and its status, for example pageDoktypeLinkMigration<\/code> as DONE<\/code>. Keep that in mind, I come back to it.<\/p>\n
What extension:setup does to your schema<\/h2>\n
There is no separate “update schema” command in the core. Schema changes happen in extension:setup<\/code>. I read PackageSetup::updateDatabaseSchemaForAllPackages()<\/code> to be sure what it does: it compares all ext_tables.sql<\/code> definitions with the database and applies only four kinds of changes: add<\/code>, change<\/code>, create_table<\/code> and change_table<\/code>. It never drops or renames a field or table.<\/p>\n
That is a good default for a deploy. Removing old columns is the install tool’s job: Analyze Database Structure<\/em> in the Maintenance module (in v14 the top-level module formerly called “Admin Tools” is named “System”). The core renames removed fields to zzz_deleted_*<\/code> first and only drops them in a second step. If you use helhum\/typo3-console, it has a database:updateschema<\/code> command with safe and destructive selectors; check that the release you install supports your core version.<\/p>\n
Also good to know: upgrade:run<\/code> checks the prerequisites of each wizard. Many wizards require an up-to-date database, and that prerequisite adds missing tables and fields before the wizard runs. So the order is not as fragile as it looks. But it still only adds, it does not remove.<\/p>\n
Problems I faced: “done” does not mean “migrated”<\/h2>\n
The status in upgrade:list --all<\/code> is just a flag in the sys_registry<\/code> table (namespace installUpdate<\/code>, one row per wizard class). Nothing checks your data. I found three ways that flag gets set without a migration.<\/p>\n
1. A fresh installation marks every wizard as done<\/h3>\n
When you set up a new TYPO3, SetupDatabaseService::markWizardsDone()<\/code> sets the flag for all non-repeatable wizards. That makes sense for an empty database. But hoja.in was exactly the other case: a fresh v14.3 installation, then old 7.6 content imported by a script. The wizards were “done” before the old data even arrived.<\/p>\n
One of the breaking changes on that way is Breaking #17406: the field pages.url<\/code> was removed, external link pages use the typolink field pages.link<\/code> now. The wizard pageDoktypeLinkMigration<\/code> would move the values, but it was never going to run. So the import script did that mapping itself, and the smoke test confirmed that the “Blog” menu entry still pointed to \/blog\/<\/code>. If you import data into a fresh installation, read the wizards of every version you skip and do their work in the import.<\/p>\n
2. Running a wizard when the data is not there yet<\/h3>\n
If a wizard says updateNecessary()<\/code> is false, upgrade:run<\/code> marks it done and tells you: “does not need to make changes. Marking wizard as done.” That is fine if the data really does not exist. It is not fine if the data is just not there yet<\/em>, or not there any more<\/em>.<\/p>\n
The link wizard is a nice example: it only reports work when pages<\/code> still has the columns url<\/code>, target<\/code> and link<\/code>. Remove url<\/code> in the install tool before running wizards and the wizard sees nothing to do, gets marked done, and your external links are empty. Order: wizards first, destructive cleanup last.<\/p>\n
3. Confirmable wizards with –no-interaction<\/h3>\n
Some wizards ask a question (they implement ConfirmableInterface<\/code>). In a deploy script you add -n<\/code>, so Symfony takes the default answer. If the default is “no” and the confirmation is not required, the command prints “No changes applied, marking wizard as done.” and exits successfully. Green pipeline, nothing migrated.<\/p>\n
Solution: check the data, not the flag<\/h2>\n
Step 1: before any of this, take a database dump. In DDEV that is one command:<\/p>\n
ddev snapshot --name before-wizards<\/code><\/pre>\n
On hoja.in the AI agent that did the legwork ran with a guard hook that refused extension:setup<\/code> and upgrade:run<\/code> unless a dump younger than 24 hours existed. That rule is worth keeping even without an agent.<\/p>\n
Step 2: list what is flagged as done, straight from the registry:<\/p>\n
ddev mysql -e \"SELECT entry_key FROM sys_registry WHERE entry_namespace = 'installUpdate'\"<\/code><\/pre>\n
Step 3: for each wizard that matters for your data, write one query that shows whether the old shape is still present. For the link wizard:<\/p>\n
-- external link pages without a link: either migrated wrong, or not at all\nSELECT uid, title FROM pages WHERE doktype = 3 AND deleted = 0 AND link = '';<\/code><\/pre>\n
Step 4: if a wizard was flagged too early and the source columns still exist, run upgrade:mark:undone <identifier><\/code> and then upgrade:run <identifier><\/code>. If the columns are already gone, restore the dump. That is why step 1 exists.<\/p>\n
A deploy script snippet<\/h2>\n
On production I do not want to run wizards blindly. They are rehearsed on a copy of the production database, one by one, with the checks above. The deploy only applies the safe schema part and then refuses to continue if anything is still pending:<\/p>\n
#!\/usr\/bin\/env bash\nset -euo pipefail\n\ncomposer install --no-dev --optimize-autoloader --no-interaction\nvendor\/bin\/typo3 extension:setup --no-interaction\n\npending=\"$(vendor\/bin\/typo3 upgrade:list --no-ansi)\"\nif ! grep -q 'No wizards available' <<<\"$pending\"; then\n    echo \"Pending upgrade wizards, run them on staging first:\" >&2\n    echo \"$pending\" >&2\n    exit 1\nfi\n\nvendor\/bin\/typo3 cache:flush<\/code><\/pre>\n
This is close to step 3 of the hoja.in runbook (composer install --no-dev<\/code>, extension:setup<\/code>, upgrade:list<\/code> expecting “No wizards available”, cache:flush<\/code>), just with the expectation turned into an exit code.<\/p>\n
Feedbacks are the champion’s breakfast. If you know another way a wizard gets marked done too early, drop a comment.<\/p>\n
Further reading<\/h2>\n