docs: document upgrading an existing installation

[blaipr]

upgrade appeared in no document, while schemas/ carries two versioned migrations and there are eleven Upgrade* classes. Anyone moving a real installation onto this rewrite had to read the SQL to find out what it would do.

What it covers

What triggers an upgrade. Two recorded versions are checked against the running code — databaseVersion and appVersion — and either being behind diverts the request. Both are read because they answer different questions: stamping only the database version once left an installation that had upgraded successfully being sent back to the upgrade page, with its one-time key already spent.

The upgrade key. The page is reachable before anyone signs in, so it is gated by 16 random bytes written into config.xml, compared with hash_equals() and cleared on success — readable only by someone who already has the database credentials.

How a migration is selected, including that UpgradeDatabase derives its filename from the version, so a version with no matching file is an error rather than a silent no-op.

The part worth writing down

The text migration runs exactly once, and cannot be made idempotent. Run twice, & goes from & to &, and nothing in a value says whether it has already been decoded. What bounds it to one run is the recorded database version.

That is why the file is wrapped in a transaction: every statement is DML, so an interrupted run rolls back rather than leaving rows half decoded with no version stamped — the one state no second run could repair. UpgradeDatabase::apply() has no rollback of its own; what unwinds the work is PDO tearing down the connection.

The page also records that the ampersand is decoded last within each value, because somebody who typed < had it stored as <, and decoding the ampersand first would take that to < and quietly change what they wrote.

Counted, not recalled

The migration is described as touching 28 columns across 12 tables. The figure that has been carried around in commentary was 24 across 11 — the table count was short because CustomFieldData is updated through a join rather than a plain UPDATE … SET, which is also what excludes encrypted values (isEncrypted = 0). Parsing the file rather than trusting the note is what surfaced both.

Verified

The four-hour temporary-password default, the 16-byte upgrade key, start transaction at line 24 and commit at line 144, and the two #[UpgradeVersion] attributes on UpgradeDatabase were each read out of the source. The README table gains a row and stays alphabetical.