Management Operations

The Sourcegraph Docker Compose yaml file uses Docker volumes to store its data. These volumes are stored at /var/lib/docker/volumes by default on Linux.

Guides for managing cloud storage and backups are available in our cloud-specific installation guides:

Access the database

To open a psql session on one of the databases, run the command for its container:

BASH
docker exec -it pgsql psql -U sg
docker exec -it codeintel-db psql -U sg
docker exec -it codeinsights-db psql -U postgres

Backup and restore

The following instructions are specific to backing up and restoring the Sourcegraph databases in a Docker Compose deployment. These do not apply to other deployment types.

WARNING: Only core data will be backed up.

These instructions will only back up core data including user accounts, configuration, repository-metadata, etc. Other data will be regenerated automatically:

Repositories will be re-cloned

Search indexes will be rebuilt from scratch

The above may take a while if you have a lot of repositories. In the meantime, searches may be slow or return incomplete results. This process rarely takes longer than 6 hours and is usually much faster.

Back up Sourcegraph databases

These instructions will back up the primary sourcegraph database, the codeintel database, and the codeinsights database.

ssh from your local machine into the machine hosting the sourcegraph deployment
cd to the deploy-sourcegraph-docker/docker-compose directory on the host
Verify the deployment is running:

BASH
docker compose ps --format 'table {{.Name}}\t{{.Status}}'
NAME                            STATUS
blobstore                       Up About a minute (healthy)
caddy                           Up About a minute
cadvisor                        Up About a minute
codeinsights-db                 Up About a minute (healthy)
codeinsights-db-exporter        Up About a minute
codeintel-db                    Up About a minute (healthy)
codeintel-db-exporter           Up About a minute
executor                        Up About a minute
gitserver-0                     Up About a minute
grafana                         Up About a minute
jaeger                          Up About a minute
node-exporter                   Up About a minute
otel-collector                  Up About a minute
pgsql                           Up About a minute (healthy)
pgsql-exporter                  Up About a minute
precise-code-intel-worker       Up About a minute (healthy)
prometheus                      Up About a minute
redis-cache                     Up About a minute
redis-store                     Up About a minute
searcher-0                      Up About a minute (healthy)
sourcegraph-frontend-0          Up About a minute (healthy)
sourcegraph-frontend-internal   Up About a minute (healthy)
syntactic-code-intel-worker     Up About a minute (healthy)
syntect-server                  Up About a minute (healthy)
worker                          Up About a minute
zoekt-indexserver-0             Up About a minute
zoekt-webserver-0               Up About a minute (healthy)

Generate the database dumps

BASH
docker exec pgsql \
    pg_dump -C --clean --if-exists --username sg sg \
    > sourcegraph_db.out
 
docker exec codeintel-db \
    pg_dump -C --clean --if-exists --username sg sg \
    > codeintel_db.out
 
docker exec codeinsights-db \
    pg_dump -C --clean --if-exists --username postgres postgres \
    > codeinsights_db.out

Ensure the sourcegraph_db.out, codeintel_db.out and codeinsights_db.out files are moved to a safe and secure location.

Restore Sourcegraph databases

These instructions apply to both a new deployment and an existing one. You don't need to delete the database volumes: the restore drops and recreates each database.

If you started Sourcegraph with more Compose files, such as jaeger/docker-compose.yaml or executors/executor.docker-compose.yaml, pass the same -f options to docker compose down and docker compose up -d. Otherwise those containers keep running during the restore, and Sourcegraph restarts without their settings.

Copy the database dump files into the deploy-sourcegraph-docker/docker-compose directory, and cd to it.
If you are restoring into an existing deployment, stop it, so nothing writes to the databases during the restore

BASH
docker compose down

Start the database services

BASH
docker compose -f db-only-migrate.docker-compose.yaml up -d

Copy the database files into the containers

BASH
docker cp sourcegraph_db.out pgsql:/data/sourcegraph_db.out
docker cp codeintel_db.out codeintel-db:/data/codeintel_db.out
docker cp codeinsights_db.out \
    codeinsights-db:/var/lib/postgresql/data/codeinsights_db.out

The database containers have a read-only root filesystem, so copy the files into the database volumes. Step 6 deletes them after the restore.

Restore the databases

BASH
docker exec pgsql \
    psql -v ON_ERROR_STOP=1 --username sg \
    -f /data/sourcegraph_db.out postgres
 
docker exec codeintel-db \
    psql -v ON_ERROR_STOP=1 --username sg \
    -f /data/codeintel_db.out postgres
 
docker exec codeinsights-db \
    psql -v ON_ERROR_STOP=1 --username postgres \
    -f /var/lib/postgresql/data/codeinsights_db.out template1

After all three restores succeed, delete the backup files from the containers

BASH
docker exec pgsql rm /data/sourcegraph_db.out
docker exec codeintel-db rm /data/codeintel_db.out
docker exec codeinsights-db \
    rm /var/lib/postgresql/data/codeinsights_db.out

Start the remaining Sourcegraph services

BASH
docker compose up -d --remove-orphans

Verify the deployment has started

BASH
docker compose ps

Browse to your Sourcegraph deployment, login and verify your existing configuration has been restored

Monitoring

You can monitor the health of a deployment in several ways:

Using Sourcegraph's built-in observability suite, which includes dashboards and alerting for Sourcegraph services.
Using docker ps to check on the status of containers within the deployment (any tooling designed to work with Docker containers and/or Docker Compose will work too).
- This requires direct access to your instance's host machine.