From b452d7074051582892e545d5d668280cbcc5abbd Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Mon, 17 Aug 2026 15:30:37 -0500 Subject: [PATCH] Add pg_upgrade safety-vs-common-case convention Correctness for any pg_upgrade-aware mechanism must assume a client can connect the instant the cluster comes back up, but design trade-offs shouldn't treat that concurrent-access window as the normal case since pg_upgrade is typically run with the application already stopped. Co-Authored-By: Claude --- CLAUDE.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index ddb059d..2502b18 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -267,6 +267,24 @@ to an extension (`ALTER EXTENSION ... UPDATE`). An extension's version-to-version scripts are "update scripts" — never "upgrade scripts." +### `pg_upgrade` safety vs. the common case + +Any lock, guard, repair mechanism, or other logic that assumes or detects +"did a `pg_upgrade` just happen" must be correct under the assumption that +a client can connect and start issuing calls the instant the upgraded +cluster starts accepting connections — nothing about `pg_upgrade` prevents +that, so it's the only assumption that's actually safe to design for. + +That correctness requirement doesn't mean concurrent access during the +upgrade window is the case to design *around*. In practice `pg_upgrade` is +run during a maintenance window with the application already stopped, so +there normally is no concurrent access at all — the immediate-access case +is the safety net, not the expected situation. This changes how a +trade-off should be weighed: a mechanism that only pays an extra-work cost +in the rare event a client connects immediately is a reasonable design; a +mechanism that pays that same cost on every upgrade because it was built +as if concurrent access were the normal case is not. + ## Session state in create/update scripts must be reverted explicitly A `CREATE EXTENSION`/`ALTER EXTENSION ... UPDATE` script can't assume