diff --git a/docs/admin/deploy/docker-compose/upgrade.mdx b/docs/admin/deploy/docker-compose/upgrade.mdx index 40adfc660..19f454d66 100644 --- a/docs/admin/deploy/docker-compose/upgrade.mdx +++ b/docs/admin/deploy/docker-compose/upgrade.mdx @@ -4,7 +4,7 @@ import { CURRENT_VERSION_STRING } from 'src/components/PreCodeBlock' This document describes the process to update a Docker Compose Sourcegraph instance. 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.*** +> Always consult the [release notes](/admin/updates/docker_compose) for the versions your upgrade will pass over and end on. ### Standard upgrades @@ -59,70 +59,84 @@ $ docker-compose up -d --remove-orphans ### Multi-version upgrades -If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perform an [**automatic multi-version upgrade**](/admin/updates/automatic). The following procedure has been automated, but is still applicable should errors occur in an automated upgrade. +> Multiversion upgrades **require downtime**, 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 [support@sourcegraph.com](mailto:support@sourcegraph.com) for advisement. ---- - -> **⚠️ 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 [support@sourcegraph.com](mailto:support@sourcegraph.com) for advisement. - -To perform a **manual** multi-version upgrade on a Sourcegraph instance running on Docker compose follow the procedure below: +To perform a multi-version upgrade via migrators [upgrade](/admin/updates/migrator/migrator-operations#upgrade) command 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. **Disable Connections to the Database**: - - 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 - ``` -3. **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). - 1. Set the migrator `image:` in your `docker-compose.yaml` to the **latest** release of `migrator`. **Example:** +2. **Pull and merge upstream changes**: + - Follow the [standard upgrade procedure](#standard-upgrades) to pull and merge upstream changes from the version you are upgrading to your `release` branch. + +3. **Disable Connections to the Database**: + - Stop running containers connected to the databases and the databases: + ``` + $ docker-compose down --remove-orphans + ``` + +4. **Run Migrator with the `upgrade` command**: + - *For more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#upgrade).* + 1. If the migrator `image:` in your `docker-compose.yaml` wasn't updated to in the **latest** release of `migrator` in step 2 set migrator's image to the latest release. + **Example:** ```yaml migrator: container_name: migrator - image: 'index.docker.io/sourcegraph/migrator:5.0.4' + image: 'index.docker.io/sourcegraph/migrator:6.0.0' ``` - > *Note: Always use the latest image version of migrator for migrator commands, except the startup command `up`* - 2. Set the migrator `command:` to `upgrade` you'll need to supply a `--to=` argument. **Example:** + 2. Set the migrator `command:` to `upgrade` you'll need to supply a `--to=` argument to the version you're upgrading to. + **Example:** ```yaml - command: ['upgrade', '--from=v4.1.2', '--to=v4.4.0'] + command: ['upgrade', '--from=v5.9.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:** + 3. Run migrator with `docker-compose up migrator` + + - Migrator `depends_on:` will ensure the databases are ready before attempting to run the migrator. Ensuring that database entry point scripts are run before the migrator attempts to connect to the databases. For users upgrading from a version earlier than `5.10.0`, a PostgreSQL version is required and will be performed automatically here. For more details, see [Upgradeing PostgreSQL](/admin/postgresql#upgrading-postgresql). + + **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 + ✔ Network docker-compose_sourcegraph Create... 0.1s + ✔ Container pgsql Created 0.1s + ✔ Container codeinsights-db Created 0.1s + ✔ Container codeintel-db Created 0.1s + ! codeinsights-db The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s + ! pgsql The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s + ! codeintel-db The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s + ✔ Container migrator Created 0.0s + ! migrator The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s 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 4.4.0 - migrator | 👉 Migrating to v4.3 (step 1 of 2) - migrator | 👉 Running schema migrations - migrator | ✅ Schema migrations complete - migrator | 👉 Running out of band migrations [17 18] - ✅ Out of band migrations complete - migrator | 👉 Migrating to v4.4 (step 2 of 2) - migrator | 👉 Running schema migrations - migrator | ✅ Schema migrations complete - migrator | migrator exited with code 0 + migrator | ✱ Sourcegraph migrator 6.0.0 + migrator | ⚠️ Failed to check for migrator update: unexpected status code 404. Continuing... + migrator | Attempting connection to frontend... + migrator | ✅ Connection to frontend succeeded + migrator | Attempting connection to frontend... + migrator | ✅ Connection to frontend succeeded + migrator | Attempting connection to codeintel... + migrator | ✅ Connection to codeintel succeeded + migrator | Attempting connection to codeinsights... + migrator | ✅ Connection to codeinsights succeeded + migrator | 👉 Migrating to v6.0 (step 1 of 1) + migrator | 👉 Running schema migrations + migrator | ✅ Schema migrations complete + migrator exited with code 0 ``` +5. **Run Migrator with the `up` command** + - Set your migrator `command:` to `up` + > *Note: If you aren't upgrading to the latest release remember to set the migrator image back to the version you are upgrading to.* + **Example:** + ```yaml + migrator: + container_name: migrator + image: 'index.docker.io/sourcegraph/migrator:6.0.0@sha256:ec295eb0b743da6bf56777ca6524972267a5c442b0288095e2fe12fce38ebacc' + cpus: 0.5 + mem_limit: '500m' + command: ['up'] + ``` -4. **Pull and merge upstream changes**: - - Follow the [standard upgrade procedure](#standard-upgrades) to pull and merge upstream changes from the version you are upgrading to to your `release` branch. - - **⚠️ Attention:** *merging upstream changes should set the migrator `image:` version back to the release you are upgrading to, and the `command:` should be set back to `up`, this is necessary to start your instance again.* - -5. **Start your containers again**: +6. **Start your containers again**: - run `docker-compose up -d` in the folder containing your `docker-compose.yaml` file. ```sh $ docker-compose up -d diff --git a/docs/admin/deploy/kubernetes/index.mdx b/docs/admin/deploy/kubernetes/index.mdx index 2ac9f5a27..0f70d4468 100644 --- a/docs/admin/deploy/kubernetes/index.mdx +++ b/docs/admin/deploy/kubernetes/index.mdx @@ -928,10 +928,6 @@ When all pods have restarted and show as Running, you can browse to your Sourceg ### Multi-version upgrades -If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perform an [**automatic multi-version upgrade**](/admin/updates/automatic). The following instructions are still applicable, just the manual version of what automatic multi-version upgrade do for you now (and therefore is valuable information during a bumpy upgrade). - ---- - Please see our [cautionary note](/admin/updates/#best-practices) on upgrades, if you have any concerns about running a multi-version upgrade, please reach out to us at [support@sourcegraph.com](mailto:support@sourcegraph.com) for advisement. ### Multi-version upgrade procedure @@ -942,6 +938,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:** +> 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). + 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 --replicas=0`) diff --git a/docs/admin/deploy/kubernetes/upgrade.mdx b/docs/admin/deploy/kubernetes/upgrade.mdx index ceb4f9bc5..24dfd4396 100644 --- a/docs/admin/deploy/kubernetes/upgrade.mdx +++ b/docs/admin/deploy/kubernetes/upgrade.mdx @@ -120,46 +120,41 @@ For example, if you use [overlays to make changes to the manifests](https://gith ## Multi-version upgrades -If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perform an [**automatic multi-version upgrade**](/admin/updates/automatic). The following procedure has been automated, but is still applicable should errors occur in an automated upgrade. - ---- - > **⚠️ 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 [support@sourcegraph.com](mailto:support@sourcegraph.com) for advisement. -To perform a **manual** multi-version upgrade on a Sourcegraph instance running on our **kubernetes** repo follow the procedure below: +To perform a multi-version upgrade via migrators [upgrade](/admin/updates/migrator/migrator-operations#upgrade) command on a Sourcegraph instance deployed with our [kustomize repo](https://github.com/sourcegraph/deploy-sourcegraph-k8s) follow the procedure below: 1. **Check Upgrade Readiness**: - Check the [upgrade notes](/admin/updates/kubernetes#kubernetes-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. **Disable Connections to the Database**: - - The following services must have their replicas scaled to 0: - - Deployments (e.g., `kubectl scale deployment --replicas=0`) - - precise-code-intel-worker - - repo-updater - - searcher - - sourcegraph-frontend - - sourcegraph-frontend-internal - - symbols - - worker - - Stateful sets (e.g., `kubectl scale sts --replicas=0`): - - gitserver - - indexed-search - - *convenience command:* - ```sh - $ kubectl scale deployment precise-code-intel-worker repo-updater searcher sourcegraph-frontend sourcegraph-frontend-internal symbols worker --replicas=0 && kubectl scale sts gitserver indexed-search --replicas=0 - ``` - -3. **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#kubernetes-kustomize). - 1. In the `configure/migrator/migrator.Job.yaml` manifest ([kustomize](https://github.com/sourcegraph/deploy-sourcegraph/blob/master/configure/migrator/migrator.Job.yaml) or [legacy](https://github.com/sourcegraph/deploy-sourcegraph/blob/master/configure/migrator/migrator.Job.yaml)): +2. **Pull and merge upstream changes**: + - Follow the [standard legacy upgrade procedure](#upgrade-with-legacy-kubernetes) to pull and merge upstream changes from the version you are upgrading to to your `release` branch. + +3. **Update cluster.yaml and scale down non-database deployments and replicas**: + - In your cluster kustomization file (`instances/my-sourcegraph/kustomize.yaml`), uncomment the [multi-version-upgrade util](https://github.com/sourcegraph/deploy-sourcegraph-k8s/blob/main/instances/template/kustomization.template.yaml#L155). This will scale down all non-database deployments and statefulSets replicas to 0. + ```yaml + # - ../../components/utils/uid # -- Run all Postgres database with valid users on host + - ../../components/utils/multi-version-upgrade # -- Scale down non-database pods to 0 for multi-version upgrade + # - ../../components/utils/migrate-to-nonprivileged # -- Component for migrating from privileged to non-privileged + # + ``` + - Generate and apply a new cluster.yaml file. + ```sh + kubectl kustomize instances/my-sourcegraph -o cluster.yaml + kubectl apply --prune -l deploy=sourcegraph -f cluster.yaml + ``` + > Note: This step will ensure that any PostgreSQL upgrade performed as an entrypoint script will have a chance to execute before the migrator is run. For more information see [Upgradeing PostgreSQL](/admin/postgres#upgrading-postgresql). + +4. **Run Migrator with the `upgrade` command**: + - *For more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#upgrade).* + 1. In the `configure/migrator/migrator.Job.yaml` [manifest](https://github.com/sourcegraph/deploy-sourcegraph-k8s/blob/main/components/utils/migrator/resources/migrator.Job.yaml): - set the `image:` to the **latest** release of `migrator` - set the `args:` value to `upgrade`. **Example:** ```yaml - - name: migrator - image: "index.docker.io/sourcegraph/migrator:5.0.3" - args: ["upgrade", "--from=v3.41.0", "--to=v4.5.1"] + - name: migrator + image: "index.docker.io/sourcegraph/migrator:6.0.0" // here we use a later version of migrator than the version we're upgrading too. + args: ["upgrade", "--from=v5.9.0", "--to=5.11.0"] env: ``` > *Note:* @@ -168,11 +163,11 @@ To perform a **manual** multi-version upgrade on a Sourcegraph instance running 2. Run the following commands to schedule the migrator job with the upgrade command and monitor its progress: ```sh # To ensure no previous job invocations will conflict with our current invocation - kubectl delete -f configure/migrator/migrator.Job.yaml + kubectl delete job migrator # Start the migrator job - kubectl apply -f configure/migrator/migrator.Job.yaml + kubectl apply -f components/utils/migrator/resources/migrator.Job.yaml # Stream the migrator's stdout logs for progress - kubectl logs job.batch/migrator -f + kubectl logs job/migrator -f ``` **Example:** ```sh @@ -209,14 +204,19 @@ To perform a **manual** multi-version upgrade on a Sourcegraph instance running migrator 1/1 9s 35s ``` -4. **Pull and merge upstream changes**: - - Follow the [standard legacy upgrade procedure](#upgrade-with-legacy-kubernetes) to pull and merge upstream changes from the version you are upgrading to to your `release` branch. - -5. **Scale your replicas back up and apply new manifests**: - - The [legacy kubernetes upgrade procedure](#upgrade-with-legacy-kubernetes) describes this step in more detail. - - Ensure that the replica counts adjusted in the previous steps are turned back up. - - Run `./kubectl-apply-all.sh` to deploy the new pods to the Kubernetes cluster. - - Monitor the status of the deployment via `kubectl get pods -o wide --watch`. +5. **Generate and apply a new cluster.yaml file**: + 1. Comment out the [multi-version-upgrade util](https://github.com/sourcegraph/deploy-sourcegraph-k8s/blob/main/instances/template/kustomization.template.yaml#L155) in your cluster kustomization file (`instances/my-sourcegraph/kustomize.yaml`). + ```yaml + # - ../../components/utils/uid # -- Run all Postgres database with valid users on host + # - ../../components/utils/multi-version-upgrade # -- Scale down non-database pods to 0 for multi-version upgrade + # - ../../components/utils/migrate-to-nonprivileged # -- Component for migrating from privileged to non-privileged + ``` + 2. Generate and apply a new cluster.yaml with the new images from Step 2. + ```sh + kubectl kustomize instances/my-sourcegraph -o cluster.yaml + kubectl apply --prune -l deploy=sourcegraph -f cluster.yaml + ``` + Your instance should now be up and running in the new version! --- diff --git a/docs/admin/how-to/upgrade-postgres-12-16-builtin-dbs.mdx b/docs/admin/how-to/upgrade-postgres-12-16-builtin-dbs.mdx new file mode 100644 index 000000000..ba60d24ec --- /dev/null +++ b/docs/admin/how-to/upgrade-postgres-12-16-builtin-dbs.mdx @@ -0,0 +1,87 @@ +# Upgrading Built-in PostgreSQL + +The following doc contains detailed instructions for upgrading the built-in PostgreSQL databases. Via our `postgresql-16` and `postgresql-16-codeinsights` image entrypoint script. This doc assumes an admin is attempting to upgrade to Sourcegraph `6.0.0` from an older version (usually pre `5.10.0`) using one of our "deploy" repos. For more general info see [Upgrading PostgreSQL](/admin/postgres#upgrading-postgresql). + +> 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.** + +## Docker Compose + +Docker compose supports [standard](/admin/deploy/docker-compose/upgrade#standard-upgrades) and [multi-version](/admin/deploy/docker-compose/upgrade#multi-version-upgrades) upgrades to Postgres 16 versions! However, if you prefer to upgrade your DBs independent of a Sourcegraph version upgrade see the following procedure. + +1. **Bring down your containers** +```bash +docker-compose down --remove-orphans +``` +2. Change the `image:` in your `docker-compose.yaml` to the release of `pgsql`, `codeinsights-db`, and `codeintel-db`. Or [merge in changes](/admin/deploy/docker-compose/upgrade#standard-upgrades) from the tagged sourcegraph release you're planning to upgrade to. **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' +``` +3. Bring up your deployments +```bash +docker-compose up -d pgsql codeintel-db codeinsights-db +``` +Wait for the database containers to come up healthy. If for some reason the database containers fail to come up healthy, please check their logs and reach out to us for support at support@sourcegraph.com. + +## Kubernetes Kustomize + +Kubernetes Kustomize supports [standard](/admin/deploy/kubernetes/upgrade#standard-upgrades) and [multi-version](/deploy/kubernetes/upgrade#multi-version-upgrades) upgrades to Postgres 16 versions! However, if you prefer to upgrade your DBs independent of a Sourcegraph version upgrade see the following procedure. + +1. **Disable Connections to the Database**: + - The following services must have their replicas scaled to 0: + - Deployments (e.g., `kubectl scale deployment --replicas=0`) + - precise-code-intel-worker + - repo-updater + - searcher + - sourcegraph-frontend + - sourcegraph-frontend-internal + - symbols + - worker + - Stateful sets (e.g., `kubectl scale sts --replicas=0`): + - gitserver + - indexed-search +*convenience command:* +```sh +$ kubectl scale deployment precise-code-intel-worker repo-updater searcher sourcegraph-frontend sourcegraph-frontend-internal symbols worker --replicas=0 && kubectl scale sts gitserver indexed-search --replicas=0 +``` +2. **Update base files for the database statefulSets**: + - 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 + ``` + +3. Apply the new container images to the database statefulsets: +```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 + + +## 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. + + 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. \ No newline at end of file diff --git a/docs/admin/postgres.mdx b/docs/admin/postgres.mdx index b47510f58..2041809a7 100644 --- a/docs/admin/postgres.mdx +++ b/docs/admin/postgres.mdx @@ -6,9 +6,11 @@ Sourcegraph uses several PostgreSQL databases to support various functionality. - `codeintel-db`: provides support for lsif data and part of the code-intelligence - `codeinsights-db`: provides support for code insights data -## Version requirements +## Requirements -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. Starting in Sourcegraph 6.0.0, sourcegraph services will no longer connect to a PostgreSQL 12 or lower database. Instead displaying an error message in container logs for services attempting to connect to a PostgreSQL database below version 16. +### Version requirements + +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. Starting in Sourcegraph 6.0.0, sourcegraph services will no longer connect to a PostgreSQL 12 or lower database. Instead, it will display an error message in container logs for services attempting to connect to a PostgreSQL database below version 16. ``` migrator | ✱ Sourcegraph migrator 6.0.0 migrator | ⚠️ Failed to check for migrator update: unexpected status code 404. Continuing... @@ -17,7 +19,14 @@ migrator | {"SeverityText":"FATAL","Timestamp":1738107940979396426,"Instrumenta migrator exited with code 1 ``` -## Role requirements +Sourcegraph services attempting to connect to a database running Postgres 12 or less will display the following error message: +``` +"new db handle: Sourcegraph requires PostgreSQL 16+. For more information about PostgreSQL requirements and upgrade guides, visit https://sourcegraph.com/docs/admin/postgres" +``` + +See [below](#upgrading-postgresql) for more details about how to upgrade your PostgreSQL database. + +### Role requirements The user provided to Sourcegraph must have full access to the `sg` database and be able to create the following extensions: @@ -32,23 +41,28 @@ pgcrypto vector ``` -## [Configuring PostgreSQL](/admin/config/postgres-conf) +## Configuring PostgreSQL -### Upgrading Built-in PostgreSQL +Sourcegraph databases come preconfigured, however admins may make custom configurations as needed. For more information see our [configuration docs](/admin/config/postgres-conf). + +## Upgrading PostgreSQL -Starting in version `5.10.0`, Sourcegraph begins supporting PostgreSQL 16. For admins deploying our built-in PostgreSQL, we facilitate the upgrade of PostgreSQL using entrypoint scripts packaged in the new `postgresql-16` and `postgresql-16-codeinsights` container images which become standard in our deployment repos in `5.10.0`. The database container images are renamed as follows: +### Upgrading Built-in PostgreSQL -**postgres-12-alpine → postgresql-16** +In Sourcegraph 5.10.0, we've upgraded our builtin database images to PostgreSQL 16. -**codeintel-db → postgresql-16** +Database Image Updates: +- `postgres-12` is now `postgresql-16` +- `codeintel-db` is now `postgresql-16` +- `codeinsights-db` is now `postgresql-16-codeinsights` -**codeinsights-db → postgresql-16-codeinsights** +These images contain an entry script that will detect and upgrade Postgres instances from version 12 (the version in our previous images) to Postgres 16. > WARNING: Upgrading the PostgreSQL database requires stopping your Sourcegraph deployment which will result in **downtime**. > -> Once the database upgrade process is started, containers running the upgrade should not be stopped or restarted. +> 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.** -When our `postgresql-16` images start, if they detect a PostgresSQL 12 database in their attached volume, they will automatically attempt to upgrade the database to PostgreSQL 16. +**For instance specfic instructions on how to upgrade a builtin Postgres database via the image entrypoint script, see [our instance specific operational instructions](/admin/how-to/upgrade-postgres-12-16-builtin-dbs).** We have the following advisements to admins: - Container orchestration management systems (e.g. Kubernetes) may restart containers at any time, **it is recommended that you take a backup of your database before starting the upgrade process.** @@ -56,14 +70,15 @@ We have the following advisements to admins: For additional assistance with PostgreSQL upgrades, please contact support@sourcegraph.com. -#### Upgrade entryscript `--link` option - -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. +### Upgrade entrypoint script options -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. +The `PG_UPGRADE_EXTRA_ARGS` environment variable allows you to customize the `pg_upgrade` command in `postgresql-16` and `postgresql-16-codeinsights` deployments. -If not using the `--link` option, you will need enough disk space available for Postgres to make a copy of the existing data. For example, if your database is currently using 100GiB of storage, you will need an additional 100GiB free space in order for the upgrade process to succeed. +- **Quick upgrade option:** +Setting `PG_UPGRADE_EXTRA_ARGS=--link` creates hard links between old and new data directories instead of copying data. While faster and space-efficient, this method risks data corruption if containers are interrupted during an upgrade. It is best used when you have reliable container scheduling and solid backups. +- **Storage requirements:** +Without `--link`, you'll need double the current database size in free disk space. For example, a 100GiB database requires an additional 100GiB free space for the upgrade. ### Upgrading external PostgreSQL instances diff --git a/docs/admin/updates/kubernetes.mdx b/docs/admin/updates/kubernetes.mdx index 814736b3c..4a33ec6ba 100644 --- a/docs/admin/updates/kubernetes.mdx +++ b/docs/admin/updates/kubernetes.mdx @@ -15,6 +15,7 @@ For upgrade procedures or general info about sourcegraph versioning see the link ## v6.0.0 - Sourcegraph 6.0.0 no longer supports PostgreSQL 12, admins must upgrade to PostgreSQL 16. See our [postgres 12 end of life](/admin/postgres12_end_of_life_notice) notice! As well as [supporting documentation](/admin/postgres) and advisements on how to upgrade. +- The Kuberentes 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.11.6271` 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). ## v5.9.0 ➔ v5.10.1164