chore(release): Clarify helm MVU warning about postgres version upgrade procedure (#1046)

closes REL-807

https://linear.app/sourcegraph/issue/REL-807/generate-issue-for-helm-doc-update-regarding-version-targeting

## Pull Request approval

You will need to get your PR approved by at least one member of the
Sourcegraph team. For reviews of docs formatting, styles, and component
usage, please tag the docs team via the #docs Slack channel.

---------

Co-authored-by: Louis Jarvis <[email protected]>

Author: DaedalusG

docs/admin/deploy/kubernetes/index.mdx

@@ -938,7 +938,7 @@ When all pods have restarted and show as Running, you can browse to your Sourceg
 - Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
 
 **Step 2:**
-> <Callout type="warning">The Kubernetes Helm deployment type does not support MVU from Sourcegraph `v5.9.45` versions and earlier to Sourcegraph `v6.0.0`. Admins seeking to upgrade to Sourcegraph `v6.0.0` should upgrade to `v5.10.3940` or `v5.11.6271` and then use the standard upgrade procedure to get to `v6.0.0`. This is because migrator v6.0.0 will no longer connect to Postgres 12 databases. For more info see our [PostgreSQL upgrade docs](/admin/postgres#requirements).</Callout>
+> <Callout type="warning">The Kubernetes Helm deployment type does not support MVU from Sourcegraph `v5.9.45` versions and earlier to ANY version `v6.0.x` or later. Admins seeking to upgrade to any Sourcegraph version `v6.0.x` or later (including `v6.1.x`, `v6.2.x`, etc.) must first upgrade to `v5.10.3940` or `v5.11.6271` and then use the standard upgrade procedure to get to their target version. This is because migrator in all versions from `v6.0.0` onwards will no longer connect to Postgres 12 databases. For more info see our [PostgreSQL upgrade docs](/admin/postgres#requirements).</Callout>
 
 Scale down `deployments` and `statefulSets` that access the database, _this step prevents services from accessing the database while schema migrations are in process._
 The following services must have their replicas scaled to 0:

docs/admin/how-to/upgrade-postgres-12-16-builtin-dbs.mdx

@@ -82,6 +82,28 @@ $ kubectl apply -f deploy-sourcegraph-k8s/base/sourcegraph/pgsql/pgsql.StatefulS
 
 ## Helm
 
-To upgrade builtin containers in Helm admins must update their instance to v5.11.6271 via the [helm multi-version upgrade procedure](/admin/deploy/kubernetes#multi-version-upgrade-procedure) or standard upgrade procedure. This is because `helm upgrade` doesn't support just the DBs in a chart.
+When using the in-cluster PostgreSQL databases included in the Sourcegraph Helm chart, database upgrades are integrated with the overall application upgrade process and there is no mechanism to upgrade only the PostgreSQL containers independently. Therefore, the PostgreSQL upgrade must be performed as part of a full Sourcegraph version upgrade.
 
-<Callout type="warning"> In Sourcegraph version 6.0.0 Sourcegraph services will no longer be able to connect to a Postgres 12 database. This means at and after Sourcegraph 6.0.0, migrator will not be connect to older versions to execute the `upgrade` command. </Callout>
+For production deployments, we recommend using external PostgreSQL databases, which allows for more flexible database management outside the Helm deployment lifecycle.
+
+### Required Upgrade Path
+
+<Callout type="warning">Sourcegraph versions `v6.0.x` and later require PostgreSQL 16 and will not connect to PostgreSQL 12 databases. This means any direct upgrade from versions earlier than `v5.10.3940` to any version `v6.0.x` or later will fail because the migrator in `v6.0.x` and later cannot connect to PostgreSQL 12 to perform the upgrade.</Callout>
+
+To safely upgrade PostgreSQL in Helm deployments:
+
+1. **First upgrade to an intermediate version**:
+   - Upgrade to either Sourcegraph `v5.10.3940` or `v5.11.6271` using the [helm multi-version upgrade procedure](/admin/deploy/kubernetes#multi-version-upgrade-procedure) or [standard upgrade procedure](/admin/deploy/kubernetes#standard-upgrades)
+   - These specific versions include the necessary PostgreSQL upgrade scripts to safely migrate from PG12 to PG16
+
+2. **Verify the PostgreSQL upgrade** (optional):
+   - You can verify the PostgreSQL version has been successfully upgraded by connecting to the database:
+     ```bash
+     kubectl exec -it pgsql -- psql -U sg -c "SELECT version();"
+     ```
+   - The output should show PostgreSQL 16.x
+
+3. **Proceed to target version**:
+   - Once PostgreSQL has been upgraded to version 16, you can safely upgrade to your target version (`v6.0.x` or later) using the standard upgrade procedure
+
+For any issues during the PostgreSQL upgrade process, please contact [email protected].