Migrating to Sourcegraph 5.1.x
NOTE: The following applies only deployments that use our Docker Single Container Deployment with the default built-in database. Deployments that use the Single Container Deployment with external databases (e.g. Amazon RDS, Google Cloud SQL, etc.), and users of other deployment methods (Docker Compose, Kubernetes, Machine Images, Sourcegraph Cloud) are not affected, and can ignore this page.
In Sourcegraph 5.1.x, the container image used for Docker Single Container Deployments has switched from an Alpine-based image to a Wolfi-base image in order to provide a more secure container. Upon upgrading, Sourcegraph will need to re-index the entire database. This process is automatic but requires user interation to start as it can take up to several hours to complete. It is strongly recommended to review and follow the instructions on this page prior to upgrading.
Determine whether you are affected
Only instances which fit the following criteria are affected:
- Using the Docker Single Container Deployment
- Using the default built-in database (i.e. not connecting to an external database like Amazon RDS, Google Cloud SQL, etc.)
- Upgrading from any release prior to Sourcegraph 5.1
If you are unsure whether you are affected by this migration, please contact either customer support or your Customer Engineer for further advice.
Preparations
Determine how long the migration will take
You can estimate the duration of the migration by looking at the size of the instance's Postgres directory, which can be found under data/postgresql on the host, or mounted as /var/opt/sourcegraph/postgresql on the instance.
Based on Sourcegraph's testing, you should allow 15-20 minutes per 100GB of data in this directory.
Provision additional resources for the server instance
Ensure that the instance has sufficient free disk space, as reindexing can temporarily require up to 25% additional disk space beyond the size of the existing Postgres data directory.
The following is an optional step, but can help reduce the downtime needed during the migration.
Postgres reindexing speed is primarily affected by:
- The amount of RAM available
- The speed of the underlying storage (SSD recommended)
Temporarily provisioning additional RAM and faster storage can help reduce the time needed for reindexing.
As the Postgres reindexing process is single-threaded, provisioning more CPU cores beyond 2 will not significantly help speed up reindexing.
Back up data volumes
As with all migrations, you should take the precaution of backing up both the data and config volumes from the existing instance prior to upgrading.
Ensure that the instance will not be terminated during the migration
As the migration process can take up to several hours, ensure that any health check systems which may terminate unavailable instances are disabled for the duration of the migration.
Migrating
Once the preceded preparation steps have been followed, start up the instance using a 5.1 or later container image, with the following environment variable set:
SOURCEGRAPH_5_1_DB_MIGRATION=true
If you start up the instance without this variable set, the instance will not start and instead display a message referring to this migration guide.
The migration will then run automatically. During this time, information about the reindexing process will be written to the container's log.
Once the migration has completed, you can start up the instance as usual without this environment variable set.
If the migration fails to complete due to an error or takes significantly longer than estimated, please contact either customer support or your Customer Engineer with this information and we'll advise further.
Rolling back to Sourcegraph 5.0 (or earlier) prior to running the migration
If you have not performed the "Migrating" step above, you can roll back to Sourcegraph 5.0 (or earlier) by switching back to the previously-used image.
Rolling back to Sourcegraph 5.0 (or earlier) after running the migration
If you have performed the "Migrating" step above but need to roll back to Sourcegraph 5.0 (or earlier), you should restore a backup of the data volume taken prior to the migration step.
If you did not take a backup of this volume prior to migrating, please contact either customer support or your Customer Engineer and we'll advise further.