From c1b6924a9eec0e88baf77878ce40902ccbf346d0 Mon Sep 17 00:00:00 2001
From: 3wc <3wc@doesthisthing.work>
Date: Wed, 25 Jun 2025 18:33:46 +0100
Subject: [PATCH] Add Postgres upgrade advice

---
 docs/maintainers/handbook.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/maintainers/handbook.md b/docs/maintainers/handbook.md
index b30ef2e..4526aaa 100644
--- a/docs/maintainers/handbook.md
+++ b/docs/maintainers/handbook.md
@@ -402,6 +402,25 @@ You can also add release notes for the next release into a special file `release
 
     This feature is only available in the > 0.9.x series of `abra`.
 
+## How do I know whether to accept version upgrades when running `abra recipe upgrade <something>`?
+
+### Postgres
+
+Beware major Postgres version updates!
+
+"Major" updates are ones where the first number changes, for example 14 to 15 (or 14.1 to 15.1).
+
+Postgres cannot update itself, so accepting major version upgrades can break existing app deployments.
+
+To check if a recipe can handle upgrades:
+
+1. Check whether the recipe is using the `pgautoupgrade` image.
+2. Check whether the recipe contains a custom postgres entrypoint, `entrypoint.postgres.sh`.
+
+If neither #1 nor #2 is true, **do not include a "major" postgres upgrade in a recipe upgrade**.
+
+Feel welcome to ask for help in #coopcloud-tech:matrix.autonomic.zone
+
 ## How do I generate the recipe catalogue
 
 To generate an entire new copy of the catalogue: