You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/admin/deploy/docker-compose/upgrade.mdx
+55-63Lines changed: 55 additions & 63 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -59,91 +59,83 @@ $ docker-compose up -d --remove-orphans
59
59
60
60
### Multi-version upgrades
61
61
62
-
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.
62
+
> **⚠️ Attention:** 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 [[email protected]](mailto:[email protected]) for advisement.
63
63
64
-
---
65
-
66
-
> **⚠️ 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.
67
-
68
-
To perform a **manual** multi-version upgrade on a Sourcegraph instance running on Docker compose follow the procedure below:
64
+
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:
69
65
70
66
1.**Check Upgrade Readiness**:
71
67
- Check the [upgrade notes](/admin/updates/docker_compose#docker-compose-upgrade-notes) for the version range you're passing through.
72
68
- Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
73
69
74
-
2.**Disable Connections to the Database**:
75
-
> **⚠️ 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).
76
-
-**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:
- Follow the [standard upgrade procedure](#standard-upgrades) to pull and merge upstream changes from the version you are upgrading to to your `release` branch.
80
72
81
-
- Change the `image:` in your `docker-compose.yaml` to the release of `pgsql`, `codeinsights-db`, and `codeintel-db`. **Example:**
- Stop running containers connected to the databases and the databases:
75
+
```
76
+
$ docker-compose down --remove-orphans
77
+
```
95
78
96
-
- Run the following command in the directory containing your `docker-compose.yaml` file.
97
-
```sh
98
-
$ docker-compose stop && docker-compose up -d pgsql codeintel-db codeinsights-db
99
-
```
100
-
3. **Run Migrator with the `upgrade` command**:
101
-
- 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).
102
-
1. Set the migrator `image:` in your `docker-compose.yaml` to the **latest** release of `migrator`. **Example:**
79
+
4.**Run Migrator with the `upgrade` command**:
80
+
-*For more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#docker-compose).*
81
+
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:**
> *Note: you may add the `--dry-run` flag to the `command:` to test things out before altering the dbs*
114
-
3. Run migrator with `docker-compose up migrator` **Example:**
93
+
3. Run migrator with `docker-compose up migrator`
94
+
95
+
- Migrator `depends_on:` will ensure that the databases are ready before attempting to run migrator. Ensuring that database entrypoint scripts are run before migrator attempts to connect to the databases. For users upgrading from a version earliar than `5.10.0` a PostrgreSQL version is required and will be performed automatically here. For more details see [Upgradeing PostgreSQL](/admin/postgresql#upgrading-postgresql).
96
+
97
+
**Example:**
115
98
```sh
116
99
$ ~/deploy-sourcegraph-docker/docker-compose/ docker-compose up migrator
! 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
105
+
! 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
106
+
! 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
107
+
✔ Container migrator Created 0.0s
108
+
! 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
121
109
Attaching to migrator
122
-
migrator | ❗️ An error was returned when detecting the terminal size and capabilities:
123
-
migrator |
124
-
migrator | GetWinsize: inappropriate ioctl for device
125
-
migrator |
126
-
migrator | Execution will continue, but please report this, along with your operating
127
-
migrator | system, terminal, and any other details, to:
- Follow the [standard upgrade procedure](#standard-upgrades) to pull and merge upstream changes from the version you are upgrading to to your `release` branch.
144
-
- **⚠️ 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.*
145
-
146
-
5. **Start your containers again**:
138
+
6. **Start your containers again**:
147
139
- run `docker-compose up -d` in the folder containing your `docker-compose.yaml` file.
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).
4
+
5
+
> WARNING: Upgrading the PostgreSQL database requires stopping your Sourcegraph deployment which will result in **downtime**.
6
+
>
7
+
> 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.**
8
+
9
+
## Docker Compose
10
+
11
+
1. Bring down your deployments
12
+
```bash
13
+
docker-compose down --remove-orphans
14
+
```
15
+
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:**
docker-compose up -d pgsql codeintel-db codeinsights-db
32
+
```
33
+
At this point simply 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 [email protected].
Copy file name to clipboardExpand all lines: docs/admin/postgres.mdx
+33-8Lines changed: 33 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,11 +6,20 @@ Sourcegraph uses several PostgreSQL databases to support various functionality.
6
6
-`codeintel-db`: provides support for lsif data and part of the code-intelligence
7
7
-`codeinsights-db`: provides support for code insights data
8
8
9
-
## Version requirements
9
+
## Requirements
10
+
11
+
### Version requirements
10
12
11
13
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.
12
14
13
-
## Role requirements
15
+
Sourcegraph services attempting to connect to a database running Postgres 12 or less will display the following error message:
16
+
```
17
+
"new db handle: Sourcegraph requires PostgreSQL 16+. For more information about PostgreSQL requirements and upgrade guides, visit https://sourcegraph.com/docs/admin/postgres"
18
+
```
19
+
20
+
See [below](#upgrading-postgresql) for more details about how to upgrade your PostgreSQL database.
21
+
22
+
### Role requirements
14
23
15
24
The user provided to Sourcegraph must have full access to the `sg` database and be able to create the following
Sourcegraph databases come preconfigured, however admins may make custom configurations as needed. For more information see our [configuration docs](/admin/config/postgres-conf).
40
+
41
+
## Upgrading PostgreSQL
29
42
30
43
### Upgrading Built-in PostgreSQL
31
44
32
-
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.
45
+
In Sourcegraph 5.10.0, we've upgraded our builtin database images to PostgreSQL 16.
46
+
47
+
Database Image Updates:
48
+
-`postgres-12` is now `postgresql-16`
49
+
-`codeintel-db` is now `postgresql-16`
50
+
-`codeinsights-db` is now `postgresql-16-codeinsights`
51
+
52
+
These images contain an entryscript which will detect and upgrade Postgres instances at version 12 (our previous images Postgres version) to Postgres 16.
33
53
34
54
> WARNING: Upgrading the PostgreSQL database requires stopping your Sourcegraph deployment which will result in **downtime**.
35
55
>
36
-
> 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.
56
+
> 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.**
57
+
58
+
**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).**
37
59
38
-
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.
60
+
### Upgrade entrypoint script options
39
61
40
-
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.
62
+
The `PG_UPGRADE_EXTRA_ARGS` environment variable allows you to customize the `pg_upgrade` command in `postgresql-16`and `postgresql-16-codeinsights` deployments.
41
63
42
-
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.
64
+
-**Quick upgrade option:**
65
+
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 upgrade. Best used when you have reliable container scheduling and solid backups.
43
66
67
+
-**Storage requirements:**
68
+
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.
0 commit comments