The Upgrade Report

upgrade check, upgrade apply and upgrade status print a short summary. Behind it is a full report. This page explains how to read the full report, what to do with items that need a person, and the options of apply.

How to see the full report

• One part: add --show and the part's name to check or status, for example --show notes. The parts are needs-a-person, problems, notes, repairs, warnings, stores, first-start, ledger and backups.
• Everything: add --show all, or --report <file> to write it to a file.
• After apply: the full report is saved as report.txt in the backup set. apply prints its path.
• For a program: add --json.

The sections of the report

upgrade check runs the whole upgrade on a copy and builds a report. It changes none of your data (see How MaestroHub Keeps Upgrades Safe for exactly what it reads). The report has these sections. A section with nothing to say is left out.

Section	What it tells you
Config	The config file, the data folder (storage.dataDir) and the working folder the run used.
Stores (first)	Each store the upgrade works on: the database changes the upgrade runs, the ones that run when 3.0 starts, and what else it does to that store.
Kinds	Each kind of stored item (pipelines, topics, grants and so on): how many there are, and how many the upgrade converts.
Stores (second)	Every store MaestroHub keeps: where it is now, where 3.0 keeps it, and its size. A store 3.0 creates at its first start shows as not found.
Copied out of Postgres	A 2.6 UNS metadata store kept in PostgreSQL that apply copies into uns.db (see UNS metadata and the historian are separate).
Layout	Stores that apply moves from where 2.6 kept them, for example data/pipeline.db to data/engine.db. It also lists a store on another disk, which needs --copy-across-volumes.
Findings	Repairs the upgrade makes on its own, and notes about behaviour that changes. Read the notes: they include access changes per user and history the first start deletes.
Needs a person	Items the upgrade cannot decide, with a proposed rewrite for each and the command to accept them. See below.
Problems	Items that could not be read or converted.
At first start	Long database work that the first 3.0 start runs before it answers, with the table's rows, the expected time and the free disk space it needs. See The first start runs long database work.
Warnings / Notices	Anything to fix or know before apply: a folder MaestroHub cannot write to, a store that is still in use, a publicly known encryption key, or an encryption key file that apply will create.
Result	A one-line summary and the outcome. When there is work and nothing needs a person, it prints the apply command to run.

apply prints the same report after it runs, with the Layout moves done, an Encryption keys section naming each key file it created, and a Backup section with the backup set and the exact restore command. status adds a Backup sets section (see Backup sets).

check exits with 0 when there is nothing to do, 2 when there is work for apply, 3 when something needs a person, and 1 on an error. Add --json for a machine-readable report, or --report <file> to also save it to a file.

Check again after you stop

check reads a running 2.6 installation's stores including the writes SQLite still holds in each store's -wal file. 2.6 keeps writing until you stop it, so running check once more after the stop shows the report as apply will see it. apply reports At first start again from the stopped stores either way.

Large stores

check copies the stores it would change to a temporary folder. If that disk is small, point --work-dir <folder> at a folder with enough room.

Items that need a person

Some items cannot be converted without a decision. For example, a pipeline script that reads a topic path segment by its position may need a different position, because 3.0 topic paths gain the organization. Each such item:

• stays exactly as it was stored;
• is listed under Needs a person, with every field and line concerned;
• carries a proposal: the exact rewrite, shown before and after, or the reason there is none.

You have these choices:

• Accept all of them. Run apply at a terminal: it lists the items and asks whether you accept them. In a script, pass --accept-all. Each proposal is written, and anything without a proposal stays as written for you to fix in the editor after the upgrade.
• Accept only some. Pass their IDs with --accept <id> (separate several IDs with commas) and --force. The report gives each item's ID. The others are left as stored, apply exits with 3, and 3.0 does not start until each is decided. For many IDs, put one per line in a file (# starts a comment) and pass --accept-file <file>. In Docker, mount the file into the container, for example -v $PWD/accept-ids.txt:/accept-ids.txt:ro and --accept-file /accept-ids.txt. The file must exist first: Docker creates a directory in place of a missing file.
• Fix them on 2.6 first, then run check again.

To see the result before you apply it, run check with --accept-all or the same --accept. 3.0 does not start until every item is decided.

Apply options

At a terminal, apply asks for what it needs (see the guide). In a script, you give the answers as these flags.

• Stop MaestroHub first. apply refuses if it sees a running MaestroHub using the stores.
• If apply says the stores may be in use: a stop that did not close the stores cleanly leaves SQLite's -wal/-shm files next to them. This looks the same as a MaestroHub running where the tool cannot see it. Check that MaestroHub is stopped (docker compose ps, systemctl status, or your task manager). Then rerun with --data-not-in-use. A lock that the tool can see is never overridden.
• PostgreSQL stores: if the upgrade changes a store in PostgreSQL, add --db-snapshot-taken <your-snapshot-id>. check prints the command with this placeholder in it.
• Stores on another disk: a store that 2.6 kept on a different volume than where 3.0 keeps it cannot be moved by renaming. Mount that volume where 3.0 keeps its data, set storage.dataDir there, or add --copy-across-volumes. That flag copies each file, verifies it by checksum, and keeps the original next to it, renamed <name>.moved-by-upgrade. MaestroHub logs a reminder at every start until you delete the original.
• In a script, or without a terminal: apply asks you to confirm. With no terminal to answer, it refuses rather than guess: it changes nothing and names --force. Pass --force to go ahead without the question, only after you have read the check report. The commands the report prints (to accept items, or to restore) already carry --force. In Docker, run each one as docker run --rm -v maestrohub-data:/data maestrohub/context-engine:<3.0 version> upgrade ….
• All or nothing: if any step fails, every store is put back as it was, and the report says what happened. If a PostgreSQL store's database changes were already committed, you put it back from your snapshot. The error message names it.

When it finishes, apply prints the backup folder and the exact restore command. Keep both. If a 2.6 store holds secrets in plain text, apply also notes that the backup set still holds them.

apply exits with 0 when it is done, 3 when items still need a person (those items are left as stored and 3.0 will not start yet), and 1 on an error.