[LeeroyHannigan]

What

The upgrade manual's General Upgrade Procedure, its version-history blocks (catalog 0.0.4 for PostgreSQL, SQLite and Cassandra, and catalog 0.0.3) and its rollback steps began with extenddb stop --config extenddb.toml and carried on with whatever it returned. Each now confirms the server is down before any backup, migrate or file step.

• The General Upgrade Procedure's step 1 is now "Stop the server, and confirm it is down". It explains that extenddb stop finds the server through the PID file the daemon writes, so it stops nothing and exits 1 for a serve --foreground server (no PID file), a container, a --config path that does not name the server's file, or a different user; it says to stop through whatever runs the server (sudo systemctl stop extenddb, the container runtime, or extenddb stop) and to start it again the same way; and it notes that extenddb status only checks 127.0.0.1 on the configured port, so a server on another address or host must be confirmed through its runner.
• Each version-history block now runs in a subshell and, after extenddb stop, runs { extenddb status --config extenddb.toml || true; } | grep -q 'is not running' and stops the block if the server still answers. The subshell means a copied recipe halts the upgrade without closing the operator's shell, and the || true means it behaves the same under set -o pipefail.
• The Rollback Procedure's "Stop the server" step and the SQLite rollback sentence now point at step 1's confirmed stop, because they also stop the server and then drop, restore or replace data.

Why

extenddb stop signals the process named in the PID file. A server started with serve --foreground, or a container, writes no PID file, so extenddb stop exits 1 and the server keeps running; extenddb stop also stops nothing when run with another --config or as another user. Its exit status does not show whether the server is down. The steps that follow then act against a live old server: the SQLite blocks copy or replace the database file while it is open (a cause of corruption in the SQLite documentation), and the PostgreSQL and Cassandra blocks run migrate and serve. Confirming extenddb status reports the server is not running before those steps stops that.

The Admin Guide's backup and restore section, open PR #737, uses the same guard and subshell form for the same reason. On main today the PostgreSQL migrate advisory lock only orders migrations, so a migrate run under a live old server is possible; open PR #741 adds a lock that makes migrate wait for a running server, which would narrow the exposure to the dump and copy steps.

Testing done

Text change only, to docs/manuals/07-upgrade-manual.md. The guard was exercised with the exact strings and exit codes of extenddb status (crates/app/src/cmd_status.rs prints ... is not running ... and exits 1 when nothing listens on 127.0.0.1 at the configured port): under bash, under bash with set -o pipefail, and under zsh, it continues when the server is down and ends the block, without closing the outer shell, when the server is up. The edited blocks were not run as a full upgrade rehearsal across the four backends. bash -n and zsh -n parse step 1, the SQLite and the 0.0.3 blocks; the PostgreSQL and Cassandra blocks carry the manual's existing <host>/<admin> placeholders, which are not valid shell until replaced, on main as here. The upgrade manual is in the exempt list of crates/storage-postgres/tests/doc_version_literals.rs, so that test does not read the file; no CI job runs the manual's code blocks.

Checklist

• I have read CONTRIBUTING.md
• All tests pass (cargo test --workspace)
• Code is formatted (cargo fmt --check)
• Clippy is clean (cargo clippy -- -W clippy::pedantic)
• I have added or updated tests for new functionality
• I have updated documentation if behavior changed
• Breaking changes are noted below (if any)
• If this changes the wire protocol, Storage trait, auth model, on-disk
  format, or public CLI surface, an RFC has been accepted or is linked
  below. Otherwise, an ADR captures the decision (link below).

No breaking changes. No Rust file changes, so the formatting and clippy boxes are left unchecked. CI runs the workspace tests on this PR and they pass.

ADR / RFC: n/a

---

By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache License 2.0 and I agree to the Developer Certificate of
Origin (DCO). See CONTRIBUTING.md for details.