Revision to migrator upgrade runbook to call our PG16 upgrade

docs/admin/deploy/docker-compose/upgrade-6.0.mdx

@@ -0,0 +1,90 @@
+import { CURRENT_VERSION_STRING } from 'src/components/PreCodeBlock'
+
+# Upgrade Sourcegraph on Docker Compose to v6.0 and beyond
+
+This document describes the process to update a Docker Compose Sourcegraph instance, specifically if you are targetting versions 6.0 and above, particularly if you are running in cluster databases from before v5.10. This document provides details on the steps required to also upgrade the Postgres containers to version 16.
+If you are unfamiliar with sourcegraph versioning or releases see our [general concepts documentation](/admin/updates/).
+
+> ***⚠️ Attention: Always consult the [release notes](/admin/updates/docker_compose) for the versions your upgrade will pass over and end on.***
+
+### Multi-version upgrades to the 6.0 release and beyond
+
+---
+
+> **⚠️ Attention:** please see our [cautionary note](/admin/updates/#best-practices) on upgrades, if you have any concerns about running a multiversion upgrade, please reach out to us at [[email protected]](mailto:[email protected]) for advisement.
+
+To perform a **manual** multi-version upgrade on a Sourcegraph instance running on Docker compose follow the procedure below:
+
+1. **Check Upgrade Readiness**:
+   - Check the [upgrade notes](/admin/updates/docker_compose#docker-compose-upgrade-notes) for the version range you're passing through.
+   - Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
+
+2. **Shutdown your instance of Sourcegraph**:
+   - In order to upgrade the databess, we must first shut down your instance of Sourcegraph. In particular, you should be in the directory containing your `docker-compose.yaml` file.
+   ```sh
+   $ pwd
+   /cloned/repo/location/deploy-sourcegraph-docker/docker-compose
+   $ docker-compose down
+   ```
+
+3. **Switch to the new release version**:
+   - Run the following command in local clone of your repository.
+  ```sh
+  $ git checkout v6.0.0
+  ```
+
+4. **Start up _only_ the database containers**:
+    - The database containers contain a self-executing, upgrade in place script that needs to be perfomed before starting up the remaining containers.
+    - Note that the names of the underlying images have changed in version 5.10, if you're manually changing the image references, be sure to checkout the correct version of the underlying image. This can be done by checking the official deployment repo [deploy-sourcegraph-docker](https://github.com/sourcegraph/deploy-sourcegraph-docker/)
+    ```sh
+    $ docker-compose up -d pgsql codeintel-db codeinsights-db
+    ```
+
+5. **Run Migrator with the `upgrade` command**:
+   - The following procedure describes running migrator in brief, for more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#docker-compose).
+    > *Note: Always use the latest image version of migrator for migrator commands, except the startup command `up`*
+    1. Set the migrator `image:` in your `docker-compose.yaml` to the **latest** release of `migrator`. **Example:**
+    - You may be able to skip this step if you're using the latest version of the migrator image, by upgrading to the latest version of Sourcegraph.
+    ```yaml
+    migrator:
+      container_name: migrator
+      image: 'index.docker.io/sourcegraph/migrator:6.0.0'
+    ```
+    2. Set the migrator `command:` to `upgrade` you'll need to supply a `--to=` argument. **Example:**
+    ```yaml
+    command: ['upgrade', '--from=v5.8.0', '--to=v6.0.0']
+    ```
+    > *Note: you may add the `--dry-run` flag to the `command:` to test things out before altering the dbs*
+    3. Run migrator with `docker-compose up migrator` **Example:**
+    ```sh
+    $ ~/deploy-sourcegraph-docker/docker-compose/ docker-compose up migrator
+    codeintel-db is up-to-date
+    codeinsights-db is up-to-date
+    pgsql is up-to-date
+    Recreating migrator ... done
+    Attaching to migrator
+    migrator                         | ❗️ An error was returned when detecting the terminal size and capabilities:
+    migrator                         |
+    migrator                         |    GetWinsize: inappropriate ioctl for device
+    migrator                         |
+    migrator                         |    Execution will continue, but please report this, along with your operating
+    migrator                         |    system, terminal, and any other details, to:
+    migrator                         |      https://github.com/sourcegraph/sourcegraph/issues/new
+    migrator                         |
+    migrator                         | ✱ Sourcegraph migrator 6.0.0
+    migrator                         | 👉 Migrating to v6.0 (step 1 of 2)
+    migrator                         | 👉 Running schema migrations
+    migrator                         | ✅ Schema migrations complete
+    migrator                         | 👉 Running out of band migrations [23 24]
+    ✅ Out of band migrations complete
+    migrator                         | 👉 Migrating to v6.0 (step 2 of 2)
+    migrator                         | 👉 Running schema migrations
+    migrator                         | ✅ Schema migrations complete
+    migrator                         | migrator exited with code 0
+    ```
+
+6. **Start your containers again**:
+   - run `docker-compose up -d` in the folder containing your `docker-compose.yaml` file.
+   ```sh
+   $ docker-compose up -d
+   ```

docs/admin/deploy/docker-compose/upgrade.mdx

@@ -72,6 +72,27 @@ To perform a **manual** multi-version upgrade on a Sourcegraph instance running
    - Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
 
 2. **Disable Connections to the Database**:
+   > **⚠️ Attention:** If your database is still running Postgres 12, upgrade your database to Postgres 16 in this step. For our built-in databases offerings, this can be accomplished by starting the databases using our `postgresql-16` images packaged in the deploy repos starting in version `5.10.0`. Learn more [here](/admin/postgres).
+   - **NOTE**: Names of the images have changed with the release of Sourcegraph 5.10.0. If you are using a version prior to 5.10.0, please ensure you use the following image names going forward:
+      - `postgres-12` -> `postgresql-16`
+      - `codeintel-db` -> `postgresql-16`
+      - `codeinsights-db` -> `postgresql-16-codeinsights`
+
+   - Change the `image:` in your `docker-compose.yaml` to the release of `pgsql`, `codeinsights-db`, and `codeintel-db`. **Example:**
+    ```yaml
+    pgsql:
+      container_name: pgsql
+      image: 'index.docker.io/sourcegraph/postgresql-16:6.0.0'
+    ...
+    codeintel-db:
+      container_name: codeintel-db
+      image: 'index.docker.io/sourcegraph/postgresql-16:6.0.0'
+    ...
+    codeinsights-db:
+      container_name: codeintel-db
+      image: 'index.docker.io/sourcegraph/postgresql-16-codeinsights:6.0.0'
+    ```
+
    - Run the following command in the directory containing your `docker-compose.yaml` file.
   ```sh
   $ docker-compose stop && docker-compose up -d pgsql codeintel-db codeinsights-db

docs/admin/deploy/kubernetes/index.mdx

@@ -942,6 +942,8 @@ If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perfor
 - Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
 
 **Step 2:**
+> **⚠️ Attention:** If your database is still running Postgres 12, upgrade your database to Postgres 16 in this step. For our built-in databases offerings, this can be accomplished by starting the databases using our `postgresql-16` images packaged in the deploy repos starting in version `5.10.0`. Learn more [here](/admin/postgres).
+
 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:
  - Deployments (e.g., `kubectl scale deployment <name> --replicas=0`)

docs/admin/deploy/kubernetes/upgrade.mdx

@@ -133,6 +133,31 @@ To perform a **manual** multi-version upgrade on a Sourcegraph instance running
    - Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
 
 2. **Disable Connections to the Database**:
+  > **⚠️ Attention:** If your database is still running Postgres 12, upgrade your database to Postgres 16 in this step. For our built-in databases offerings, this can be accomplished by starting the databases using our `postgresql-16` images packaged in the deploy repos starting in version `5.10.0`. Learn more [here](/admin/postgres).
+  - If you're using our built in Postgres containers, versions from 5.10 onwards contain update in place scripts than run if necessary. You will first have to update the `image` field in your `pgsql`, `codeintel-db` and `codeinsights-db` StatefulSets to `sourcegraph/postgresql-16:6.0.0`  and `sourcegraph/codeinsights-db:6.0.0` respectively.
+  - **Example:**
+  ```yaml
+  # deploy-sourcegraph-k8s/base/sourcegraph/codeinsights-db/codeinsights-db.StatefulSet.yaml 
+      containers:
+        - name: codeinsights
+          image: index.docker.io/sourcegraph/postgresql-16-codeinsights:6.0.0
+  # deploy-sourcegraph-k8s/base/sourcegraph/codeintel-db/codeintel-db.StatefulSet.yaml 
+      containers:
+        - name: pgsql
+          image: index.docker.io/sourcegraph/postgresql-16:6.0.0
+  # deploy-sourcegraph-k8s/base/sourcegraph/pgsql/pgsql.StatefulSet.yaml 
+      containers:
+        - name: pgsql
+          image: index.docker.io/sourcegraph/postgresql-16:6.0.0
+  ```
+
+  - Apply specifically these changes to your cluster:
+  ```sh
+  $ kubectl apply -f deploy-sourcegraph-k8s/base/sourcegraph/pgsql/pgsql.StatefulSet.yaml deploy-sourcegraph-k8s/base/sourcegraph/codeintel-db/codeintel-db.StatefulSet.yaml deploy-sourcegraph-k8s/base/sourcegraph/codeinsights-db/codeinsights-db.StatefulSet.yaml
+  ```
+
+  - Wait until the containers come up, and complete their migration to Postgresql 16
+
    - The following services must have their replicas scaled to 0:
      - Deployments (e.g., `kubectl scale deployment <name> --replicas=0`)
        - precise-code-intel-worker