# Management Operations

---

The Sourcegraph Docker Compose yaml file uses [Docker volumes](https://docs.docker.com/storage/volumes/) to store its data. These volumes are stored at `/var/lib/docker/volumes` by [default on Linux](https://docs.docker.com/storage/#choose-the-right-type-of-mount).

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

-   [Storage and backups for Amazon Web Services](/self-hosted/deploy/docker-compose/aws#storage-and-backups)
-   [Storage and backups for Azure](/self-hosted/deploy/docker-compose/aws#storage-and-backups)
-   [Storage and backups for Google Cloud](/self-hosted/deploy/docker-compose/google-cloud#storage-and-backups)
-   [Storage and backups for Digital Ocean](/self-hosted/deploy/docker-compose/digitalocean#storage-and-backups)

## 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](/code-navigation/) database, and the [codeinsights](/code-insights/) database.

1. `ssh` from your local machine into the machine hosting the `sourcegraph` deployment

2. `cd` to the `deploy-sourcegraph-docker/docker-compose` directory on the host

3. 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)
```

4. 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
```

5. 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.

1. Copy the database dump files into the `deploy-sourcegraph-docker/docker-compose` directory, and `cd` to it.

2. If you are restoring into an existing deployment, stop it, so nothing writes to the databases during the restore

```bash
docker compose down
```

3. Start the database services

```bash
docker compose -f db-only-migrate.docker-compose.yaml up -d
```

4. 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.

5. 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
```

6. 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
```

7. Start the remaining Sourcegraph services

```bash
docker compose up -d --remove-orphans
```

8. Verify the deployment has started

```bash
docker compose ps
```

9. 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](/self-hosted/observability/), which includes dashboards and alerting for Sourcegraph services.
-   Using [`docker ps`](https://docs.docker.com/engine/reference/commandline/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.