chore(release): pg 16 update to docs (#849)

This PR updates some of our surface information about PG upgrades as
well as cleans up some eager suggestions of the automatic upgrade
upgrade path.

It removes references of support for PG12 instead suggesting that we
currently only support 16. This was intentional to trim the docs rather
than threading out a lot of specific information about Sourcegraph
versions.

---------

Co-authored-by: Keegan Carruthers-Smith <[email protected]>
Co-authored-by: Jacob Pleiness <[email protected]>

Author: 3 people

docs/admin/external_services/postgres.mdx

@@ -2,11 +2,11 @@ import { CURRENT_VERSION_STRING_NO_V, CURRENT_VERSION_STRING } from 'src/compone
 
 # Using your own PostgreSQL server
 
-You can use your own PostgreSQL v12+ server with Sourcegraph if you wish. For example, you may prefer this if you already have existing backup infrastructure around your own PostgreSQL server, wish to use Amazon RDS, etc.
+You can use your own PostgreSQL v16+ server with Sourcegraph if you wish. For example, you may prefer this if you already have existing backup infrastructure around your own PostgreSQL server, wish to use Amazon RDS, etc.
 
 Please review the [PostgreSQL](/admin/postgres) documentation for a complete list of requirements.
 
-<Callout type="note">As of version 3.39.0, codeinsights-db no longer relies on the internal TimescaleDB and can be externalized.</Callout>
+<Callout type="note">As of version 6.0.0 The Sourcegraph application will require PostgreSQL v16+, earlier versions worked with 12 or greater.</Callout>
 
 ## General recommendations
 

docs/admin/postgres.mdx

@@ -4,12 +4,11 @@ Sourcegraph uses several PostgreSQL databases to support various functionality.
 
 - `pgsql` or `primary`: responsible for user data and account information
 - `codeintel-db`: provides support for lsif data and part of the code-intelligence
+- `codeinsights-db`: provides support for code insights data
 
 ## Version requirements
 
-We support any version **starting from 12**.
-
-> NOTE: ⚠️ Version **3.26** required only Postgres 9.6. You should check the [upgrade docs for your deployment type](/admin/updates/) as well as the [database upgrade docs](#upgrading-postgresql) below prior to upgrading to 3.27.
+We support Postgres 16 and above. Older versions of Sourcegraph supported 12 see our [Postgres 12 deprecation notice](/admin/postgres12_end_of_life_notice) for more details.
 
 ## Role requirements
 
@@ -23,19 +22,23 @@ intarray
 pg_stat_statements
 pg_trgm
 pgcrypto
+vector
 ```
 
 ## [Configuring PostgreSQL](/admin/config/postgres-conf)
 
-## Upgrading PostgreSQL
+### Upgrading Built-in PostgreSQL
 
-Sourcegraph uses PostgreSQL as its main database and this documentation describes how to upgrade PostgreSQL between major versions.
+Sourcegraph deployments come packaged with containers using the `postgresql-16` image for `pgsql` and `codeintel-db` deployments and `postgresql-16-codeinsights` for `codeinsights`. These images contain an entryscript which will detect and upgrade postgres instances at version 12 (our previous images Postgres version). See the (postgres 12 end of life notice)[/admin/prostgres12_end_of_life_notice#] for more details. 
 
 > WARNING: Upgrading the PostgreSQL database requires stopping your Sourcegraph deployment which will result in **downtime**.
+>
+> Additionally, once the upgrade process is started via the database container, interrupting the container before the upgrade is complete could result in corrupting the underlying Postgres database. We strongly advise taking a backup before the upgrade. 
 
+The `PG_UPGRADE_EXTRA_ARGS` env var can be set in the built-in `postgresql-16` and `postgresql-16-codeinsights` deployments to provide extra arguments to the `pg_upgrade` command. 
 
+Setting the env var `PG_UPGRADE_EXTRA_ARGS=--link` provides the `--link` option to the underlying `pg_update`; creating a hard links between the old and new data directories instead of copying data. This option is faster and requires less disk space, however if the database containers are interrupted during the upgrade process there is a strong possibility of data corruption. This can still be a viable choice for users who are confident in their container scheduling and backups and would like to avoid longer downtimes.
 
-> NOTE: If you running PostgreSQL externally, see [Upgrading external PostgreSQL instances](/admin/postgres#upgrading-external-postgresql-instances)
 
 ### Upgrading external PostgreSQL instances
 
@@ -52,100 +55,11 @@ When running an [external PostgreSQL instance](/admin/external_services/postgres
   - [EnterpriseDB](https://www.enterprisedb.com/docs/en/9.6/pg/upgrading.html)
   - [Citus](http://docs.citusdata.com/en/v8.1/admin_guide/upgrading_citus.html)
   - [Aiven PostgreSQL](https://help.aiven.io/postgresql/operations/how-to-perform-a-postgresql-in-place-major-version-upgrade)
-  - [Your own PostgreSQL](https://www.postgresql.org/docs/11/pgupgrade.html)
+  - [Your own PostgreSQL](https://www.postgresql.org/docs/16/pgupgrade.html)
 4. Turn Sourcegraph back on connecting to the now-upgraded database.
 
 > WARNING: **Do not allow Sourcegraph to run/connect to the new Postgres database until it has been fully populated with your data.** Doing so could result in Sourcegraph trying to create e.g. a new DB schema and partially migrating. If this happens to you, restore from the backup you previously took or contact us ([email protected])
 
-### Upgrading internal PostgreSQL instances
-
-Many of Sourcegraph's [deployment methods](/admin/deploy/) come with internal PostgreSQL instances that can be deployed as part of a Sourcegraph installation. This section outlines how to upgrade these databases.
-
-#### Sourcegraph with Docker Compose
-
-Generally, no additional steps are required to upgrade the databases shipped alongside [Sourcegraph with Docker Compose](/admin/deploy/docker-compose/).
-
-#### Sourcegraph with Kubernetes
-
-**The upgrade process is different for [Sourcegraph Kubernetes deployments](/admin/deploy/kubernetes/)** because [by default](https://github.com/sourcegraph/sourcegraph-public-snapshot/blob/main/docker-images/postgres-12/build.sh#L10), it uses `sourcegraph/postgres-12` which can be [customized with environment variables](https://github.com/sourcegraph/deploy-sourcegraph/blob/7edcadb/docs/configure#external-postgres).
-
-If you have changed `PGUSER`, `PGDATABASE` or `PGDATA`, then the `PG*OLD` and `PG*NEW` environment variables are
-required. Below are the defaults and documentation on what each variable is used for:
-
-- `POSTGRES_PASSWORD=''`: Password of `PGUSERNEW` if it is newly created (i.e when `PGUSERNEW` didn't exist in the old
-  database).
-- `PGUSEROLD=sg`: A user that exists in the old database that can be used to authenticate intermediate upgrade
-  operations.
-- `PGUSERNEW=sg`: A user that must exist in the new database after the upgrade is done (i.e. it'll be created if it
-  didn't exist already).
-- `PGDATABASEOLD=sg`: A database that exists in the old database that can be used to authenticate intermediate upgrade
-  operations. (e.g `psql -d`)
-- `PGDATABASENEW=sg`: A database that must exist in the new database after the upgrade is done (i.e. it'll be created if
-  it didn't exist already).
-- `PGDATAOLD=/data/pgdata-11`: The data directory containing the files of the old PostgreSQL database to be upgraded.
-- `PGDATANEW=/data/pgdata-12`: The data directory containing the upgraded PostgreSQL data files, used by the new version
-  of PostgreSQL.
-
-Additionally, the upgrade process assumes it can write to the parent directory of `PGDATAOLD`.
-
-##### Requirements for upgrading from Postgres 11 to 12 for Kubernetes
-
-**This guide is for the Sourcegraph 3.27 release.** The migration to Postgres 12 using the Sourcegraph provided Postgres images is largely automated.
-However, you should take some steps before the migration. For the `3.27` release, these apply to the `pgsql` & `codeintel-db` deployments.
-
-1. Inform your users prior to starting the upgrade that Sourcegraph will take downtime. This downtime scales with the
-   size and resources allocated to the Postgres database instances.
-1. Take snapshots of all Sourcegraph Postgres databases. You can find the backing disk in your cloud by describing the
-   relevant `PersistentVolumes`.
-1. Ensure that the size of the disks backing the databases are under 50% utilization. (You will need *up-to* 2x the size
-   of your current database to do the migration). In most cases Kubernetes can expand the size of the volume for you,
-   see the relevant kubernetes
-   docs [here](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#expanding-persistent-volumes-claims).
-
-   You can use `kubectl exec -it $DB_POD_NAME -- df -h`. By default, the database will be mounted under `/data/`.
-
 #### Single-container Sourcegraph
 
-When running a new version of Sourcegraph, [single-container Sourcegraph with Docker instances](/admin/deploy/kubernetes/) will check if the PostgreSQL data needs upgrading upon initialization.
-
-See the following steps to upgrade between major postgresql versions:
-
-**1.** Stop the `sourcegraph/server` container.
-
-**2.** Save this script and give it executable permissions (`chmod + x`).
-
-> NOTE: The script presumes your data is being upgraded from `11` to `12` and your Sourcegraph directory is at `~/.sourcegraph/`. Change the values in the code below if that's not the case.
-
-```bash
-#!/usr/bin/env bash
-
-set -xeuo pipefail
-
-export OLD=${OLD:-"11"}
-export NEW=${NEW:-"12"}
-export SRC_DIR=${SRC_DIR:-"$HOME/.sourcegraph"}
-
-docker run \
-  -w /tmp/upgrade \
-  -v "$SRC_DIR/data/postgres-$NEW-upgrade:/tmp/upgrade" \
-  -v "$SRC_DIR/data/postgresql:/var/lib/postgresql/$OLD/data" \
-  -v "$SRC_DIR/data/postgresql-$NEW:/var/lib/postgresql/$NEW/data" \
-  "tianon/postgres-upgrade:$OLD-to-$NEW"
-
-mv "$SRC_DIR/data/"{postgresql,postgresql-$OLD}
-mv "$SRC_DIR/data/"{postgresql-$NEW,postgresql}
-
-curl -fsSL -o "$SRC_DIR/data/postgres-$NEW-upgrade/optimize.sh" https://raw.githubusercontent.com/sourcegraph/sourcegraph/master/cmd/server/rootfs/postgres-optimize.sh
-
-docker run \
-  --entrypoint "/bin/bash" \
-  -w /tmp/upgrade \
-  -v "$SRC_DIR/data/postgres-$NEW-upgrade:/tmp/upgrade" \
-  -v "$SRC_DIR/data/postgresql:/var/lib/postgresql/data" \
-  "postgres:$NEW" \
-  -c 'chown -R postgres $PGDATA . && gosu postgres bash /admin/optimize.sh $PGDATA'
-```
-
-**3.** Execute the script.
-
-**4.** Start the `sourcegraph/server` container.
+Sourcegraph Single-container is not a supported production deployment and currently doesn't support upgrades to Postgres 16. Admins with production data in a single container deployment are advised to reach out to [email protected] for assistance.

docs/admin/updates/index.mdx

@@ -22,9 +22,9 @@ Sourcegraph releases have three digits, for example: `v5.0.3`
 | minor         | `0`     |
 | patch         | `3`     |
 
-For more details on our release cadence, refer to the [Sourcegraph handbook](https://handbook.sourcegraph.com/departments/engineering/dev/process/releases/#sourcegraph-releases).
+For more details on previous releases see [Sourcegraph Releases](/releases).
 
-Generally, we ship a new version of Sourcegraph with new features and bug fixes monthly, followed by a patch release later that month. Major and minor releases happen less frequently and contain substantial changes to Sourcegraph.
+Generally, we ship a new minor version of Sourcegraph with new features and bug fixes monthly, followed by a patch release later that month.
 
 Check the [Sourcegraph blog](https://about.sourcegraph.com/blog) for release announcements and details on the latest version.
 
@@ -78,14 +78,16 @@ It is highly recommended to:
 Sourcegraph upgrades take the following general form:
 1. Determine if your instance is ready to Upgrade (check upgrade notes)
 2. Merge the latest Sourcegraph release into your deployment manifests
-3. If updating more than a single minor version, perform an [**automatic multi-version upgrade**](/admin/updates/automatic) if targeting **Sourcegraph 5.1 or later**; [manual multi-version upgrades]/admin/updates/migrator/migrator-operations) are required if upgrading to an earlier version, which requires shutting off the instance and invoking the `migrator` container or job to perform the database rewrite and application of unfinished out-of-band migrations
+3. Select an upgrade method:
+   - If updating more than a single minor version, perform a multiversion upgrade with either the migrator [upgrade command](/admin/updates/migrator/migrator-operations#upgrade) or an [automatic upgrade](/admin/updates/automatic). *This method requires downtime.*
+   - If updating a single minor version, perform a standard upgrade with the [migrator up command](/admin/updates/migrator/migrator-operations#up) or an [automatic upgrade](/admin/updates/automatic). `up` is the default migrator entry command and runs on `frontend` startup.
 4. With upstream changes to your manifests merged, start the new instance
 
 > Note: For more explicit steps, specific to your deployment see the operations guides linked below.
 
 ### Upgrade Readiness
 
-Starting in v5.0.0, as an admin you are able to check instance upgrade readiness by navigating to the `Site admin > Updates` page. Here you'll be notified if your instance has any **schema drift** or unfinished **out of band migrations**.
+Navigate to the `Site admin > Updates` page. Here you'll be notified if your instance has any **schema drift** or unfinished **out of band migrations**.
 
 ![Screenshot 2023-05-17 at 1 37 12 PM](https://storage.googleapis.com/sourcegraph-assets/docs/239155807-185fc3e8-0706-4a23-b9fe-e262f9a9e4b3.png)
 
@@ -117,6 +119,7 @@ If your instance has schema drift or unfinished oob migrations you may need to a
 - [**Sourcegraph AWS AMI instances**](/admin/deploy/machine-images/aws-ami#upgrade)
 
 ## Other helpful links
+- [Postgres 12 End Of Life Notice](admin/postgres12_end_of_life_notice#postgres-12-end-of-life)
 - [Migrator operations](/admin/updates/migrator/migrator-operations)
 - [Upgrading Early Versions](/admin/updates/migrator/upgrading-early-versions)
 - [Troubleshooting upgrades](/admin/updates/migrator/troubleshooting-upgrades)