This page is intended as an entry point into Sourcegraph versioning, upgrades, and the
migrator service which manages our database schemas. Here we'll cover general concepts and direct you toward relevant operations pages.
If you are already familiar with Sourcegraph upgrades skip to instance specific procedures.
Note: For product update notes, please refer to the changelog.
A new Sourcegraph release consists of updated images that incorporate code changes from our main repository. It also includes modifications to deployment manifests in our supporting deployment repositories, such as our k8s helm repo.
When upgrading Sourcegraph, it is necessary to update and apply the deployment manifests. However, in addition to the manifest updates, it is crucial to ensure that all underlying database schemas of Sourcegraph are also updated.
Release Schedule and versioning
Sourcegraph releases use semantic versioning, for example:
To learn more about our release schedule see our handbook. In general a new minor version of Sourcegraph is released every month, accompanied by weekly patch releases. Major releases are less frequent and represent significant changes in Sourcegraph.You can also check the Sourcegraph blog for more information about the latest release.
Sourcegraph has two upgrade types. Standard upgrades and Multiversion upgrades.
- Moves Sourcegraph one version forward (
v5.1.0), this is usually one minor version unless the next version released is a major version.
- Requires minor downtime in deployments except kubernetes where rolling updates are possible.
- Moves Sourcegraph multiple versions forward (
- Requires downtime while the database schemas and rewritten and unfinished out-of-band migrations are applied
- We currently support jumping from version
v3.20or later to any future version.
- AMIs do not yet support multiversion upgrades. We hope to improve this soon.
Note: Patch versions don't determine upgrade type -- you should always upgrade to the latest patch.
|From Version||To Version||Upgrade Type||Notes|
||Standard||A minor version|
||Multiversion||Two minor versions|
||Standard||A minor version and patch version|
||Standard||Multiple patch versions|
||Standard||A major version change but only one absolute version|
||Multiversion||Two minor versions and patch|
||Multiversion||Major and minor|
||Standard||This is a major version but only one version change|
||Multiversion||Major, minor, and patch|
- Our major releases do not occur on a consistent interval, so make sure to check our changelog if you aren't certain about whether a major version is multiple minor versions away from your current version. You can also reach out to our support team [email protected]
- Sourcegraph guarantees database backward compatibility to the most recent minor version.
Sourcegraph databases & migrator
To facilitate the management of Sourcegraph's databases, we have created the
migrator is usually triggered automatically on Sourcegraph startup but can also be interacted with like a cli tool. Migrator's primary purpose is to manage and apply schema migrations.
- To learn more about migrations see our developer docs.
- For a full listing of migrator's command arguments see its usage docs.
Caution: The upgrade process aggressively mutates the shape and contents of your database, and undiscovered errors in the migration process or unexpected environmental differences may cause an unusable instance or data loss.
It is highly recommended to:
- Take an up-to-date snapshot of your databases prior to starting a multi-version upgrade.
- Perform the entire upgrade procedure on an idle clone of the production instance and switch traffic over on success, if possible.
General upgrade procedure
Sourcegraph upgrades take the following general form:
- Determine if your instance is ready to Upgrade (check upgrade notes)
- Merge the latest Sourcegraph release into your deployment manifests
- If updating more than a single minor version, perform an automatic multi-version upgrade if targeting Sourcegraph 5.1 or later; manual multi-verison upgrades are required if upgrading to an earlier version, which requires shutting off the instance and invoking the
migratorcontainer or job to perform the database rewrite and application of unfinished out-of-band migrations
- With upstream changes to your manifests merged, start the new instance
Note: For more explicit steps, specific to your deployment see the operations guides linked below.
Starting in v5.0.0, as an admin you are able to check instance upgrade readiness by navigating to the
Site admin > Updates page. Here you'll be notified if your instance has any schema drift or unfinished out of band migrations.
If your instance has schema drift or unfinished oob migrations you may need to address these issues before upgrading. Feel free to reach out to us at [email protected].
Instance Specific Procedures
- Sourcegraph with Docker Compose
- Sourcegraph with Kubernetes
- Single-container Sourcegraph with Docker
- Pure-docker custom deployments