Add pg_upgrade safety-vs-common-case convention

[jnasbyupgrade]

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, though. In practice pg_upgrade runs during a maintenance window with the application already stopped, so there's normally no concurrent access at all. This changes how a design trade-off should be weighed: a mechanism that only pays an extra-work cost in the rare event a client connects immediately is reasonable; the same mechanism paying that cost on every upgrade because it was built as if concurrent access were the normal case is not.

Added as a new subsection under "If this repo embeds pgxntool" in CLAUDE.md, next to the existing pg_upgrade-adjacent conventions (PostgreSQL version support policy, upgrade-vs-update terminology).

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: bfde0e0b-3407-48a4-a70d-d5ddbccf7717

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}