docs: what a site needs that no page answered
Four gaps a second site hits and cannot resolve by reading. **Restoring on Windows** was one sentence - "the standard mysql < dump.sql" - with no ordering. Restoring a database under running code that expects a different schema turns a restore into a second incident, so the steps are now ordered and each says why. It also says what `.env` costs if it is lost, which is the part nobody discovers until they are already rebuilding: the dump does not contain it, and without the JWT secrets every issued token dies, so every collector and every GE-Enforce client on the fleet needs a new key. **Rolling back** had a paragraph saying downgrades are refused and a backup is the way back, but not the procedure. Rollback is restoring a matched pair, code and the schema it expects, in that order - and the doc now separates it from the case it gets confused with: a migration that failed mid-update has already been rolled back by the installer, and fixing forward is the only move. **Sizing, acquisition and support** were absent from the install guide entirely. A reader could not learn how big a server to ask for, where the .exe comes from, or where to raise a problem. The sizing is small and the reasons are stated, so a site does not over-provision a VM for a load that is a few dozen users. **Credentials** were described in three documents from three ends, so three answers existed for where a key lives. One table, both ends - server and PC - plus the two rules behind it: what a shop-floor PC holds is scoped to exactly what it does, and a credential is delivered rather than typed, because a value entered per machine is a value that is wrong on some machine.
This commit is contained in:
@@ -83,8 +83,45 @@ Installing an older build over a newer one is blocked outright. Once migrations
|
||||
have moved the schema forward, older code cannot read it, and the failures are
|
||||
difficult to unpick.
|
||||
|
||||
To go back you restore a backup taken before the update. Keep the previous
|
||||
`.exe` until you are satisfied with a release.
|
||||
Keep the previous `.exe` until you are satisfied with a release. You cannot
|
||||
download it again from the server, and it is what a rollback needs.
|
||||
|
||||
### Rolling back a release
|
||||
|
||||
Rolling back is restoring a matched pair: the code AND the database it expects.
|
||||
Doing one without the other is the state the installer refuses to create, and it
|
||||
is worth understanding why - newer code against an older schema fails at the
|
||||
first query that touches a new column, while older code against a newer schema
|
||||
often appears to work until something silently misreads a column that changed
|
||||
meaning.
|
||||
|
||||
The update takes its own backup before touching the schema, so the pair you need
|
||||
already exists.
|
||||
|
||||
```powershell
|
||||
cd C:\shopdb-flask
|
||||
.\shopdb-admin.ps1 stop
|
||||
|
||||
# 1. Database first, from the pre-upgrade dump the update took.
|
||||
mysql -u root -p shopdb_flask < C:\ProgramData\ShopDB-Flask\backups\shopdb_flask-pre-upgrade-<stamp>.sql
|
||||
|
||||
# 2. Then the code: run the PREVIOUS installer .exe. It is an install over a
|
||||
# restored older schema, which is the ordinary case, not a downgrade.
|
||||
.\ShopDBFlask_Installer_<previous-version>.exe
|
||||
|
||||
# 3. Prove the pair matches.
|
||||
.\shopdb-admin.ps1 check -Json
|
||||
```
|
||||
|
||||
If a migration failed mid-update, the installer has already restored its own
|
||||
backup and there is nothing to roll back - read the log it names and fix
|
||||
forward. Rollback is for a release that installed cleanly and then behaved
|
||||
badly, which is a different situation and the only one this procedure is for.
|
||||
|
||||
**Uploaded files are not in the dump.** If the release you are leaving behind
|
||||
accepted uploads, restore `instance\` from your own backup as well, or those
|
||||
files stay while the rows referring to them do not. See
|
||||
[BACKUP-RESTORE.md](BACKUP-RESTORE.md).
|
||||
|
||||
## Will an update affect other sites on the same IIS server?
|
||||
|
||||
|
||||
Reference in New Issue
Block a user