Upgrade Procedures¶
Applies to: All subscriptions
Purpose¶
Let a customer upgrade unassisted, prove the upgrade worked, and — critically — get back inside the same maintenance window if verification fails.
Audience¶
System administrators and implementation engineers.
Prerequisites¶
- A working installation
- A verified backup
- A maintenance window
- The release notes for every version between the current one and the target
Steps¶
| Page | Covers |
|---|---|
| Upgrade Procedure | The sequence, step by step |
| Rollback Procedure | Getting back, and the point after which you cannot |
The three properties that shape every upgrade¶
The application refuses to start against a schema it cannot use. At startup it checks a manifest of required database objects and stops if one is missing, naming the migration that creates it. This is a safety net, not an inventory — it catches an object the code needs, not every migration you may have skipped.
There is no ledger of applied migrations. Nothing records which have been run. Keep your own per-environment record; without it, "is this database up to date?" is answerable only by inspecting objects one at a time.
Schema changes are the point of no return. Application files can be swapped back in minutes. A schema change usually cannot be reversed without a restore. The upgrade sequence is built around delaying that point as long as possible.
The sequence in outline¶
1. Read the release notes for EVERY intervening version
2. Rehearse in a non-production environment, at representative volume
3. Verified backup <-- last easy point of return
4. Stop the application and worker
5. Apply migrations <-- POINT OF NO RETURN
6. Deploy application files
7. Rebuild and publish the front end
8. Start, and read the startup log to the end
9. Verify
10. Release to users, or roll back
Rehearse, and time it¶
Rehearse in a non-production environment with representative data volume. A rehearsal against an empty database proves the steps work; it predicts nothing about how long the migrations will take against real data, and migration duration is what causes windows to overrun.
Verify: The maintenance window a routine upgrade requires is not established here. Time three real upgrades and publish the measured range. Recorded as assumption C3 in the Assumptions Register.
Read every intervening release note¶
Skipping versions is normal. Skipping their release notes is not. Each may carry:
| Item | Consequence of missing it |
|---|---|
| New required configuration | The application will not start, or a feature silently does not work |
| A migration that must run | Startup refusal |
| A breaking API change | Integrations fail after the upgrade |
| A deprecation | Something stops working at a later version |
| New statutory behaviour | The product behaves differently, correctly, and unexpectedly |
Validation¶
An upgrade is complete when:
| Check | Pass condition |
|---|---|
| The application starts | No missing-object message in the startup log |
| Migrations verified | Counts cross-checked against storage metadata |
| Isolation intact | Policies exist on any new table; cross-tenant access still blocked |
| Configuration preserved | Settings survived the deployment |
| Front end updated | Users receive the new bundle without clearing caches |
| One document end to end | Ingest to registration to print, in the sandbox |
| Integrations still work | Each ERP tested, not assumed |
| Monitoring still works | Checks still passing and alerting |
| Rollback point recorded | You know whether you can still go back |
The end-to-end document is the check that matters. Everything above it can pass while the system cannot process a document.
Troubleshooting¶
| Symptom | Cause | Action |
|---|---|---|
| Application will not start, naming an object | A migration was not applied | Apply it. The guard is working |
| Application will not start after all migrations | Version mismatch between code and schema | Confirm the deployed version matches the migrations applied |
| Configuration lost | The environment file was overwritten | Keep it outside the deployed tree, or restore it as part of the procedure |
| Users on the old version | Front-end entry page cached | Set no-cache on the entry page |
| An integration broke | A breaking change, or it uses application endpoints | Check the release notes; move to contract endpoints |
| The window overran | Rehearsal against an unrepresentative volume | Rehearse at real volume and time it |
| Unsure which migrations were applied | No record kept | Compare objects against what each migration creates. Then start keeping a record |
| Verification failed after the point of no return | Schema already changed | Restore from backup. See Rollback Procedure |