Updating sourcegraph

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.

General concepts

Upgrading

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: v5.0.3

DescriptionVersion
major5
minor0
patch3

For more details on our release candence, refer to the Sourcegraph handbook.

Generally, we ship a new version of Sourcegraph with new features and bug fixes monthly, followed by a patch release later that month. Major and minor releases happen less frequently and contain substantial changes to Sourcegraph.

Check the Sourcegraph blog for release announcements and details on the latest version.

Upgrade types

Sourcegraph has two upgrade types. Standard upgrades and Multiversion upgrades.

Standard

  • Moves Sourcegraph one version forward (v5.0.0 to 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.

Multiversion

  • Moves Sourcegraph multiple versions forward (v5.0.0 to v5.2.0).
  • Requires downtime while the database schemas and rewritten and unfinished out-of-band migrations are applied
  • We currently support jumping from version v3.20 or 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 VersionTo VersionUpgrade TypeNotes
v5.0.0v5.1.0StandardA minor version
v5.0.0v5.2.0MultiversionTwo minor versions
v3.41.0v3.42.2StandardA minor version and patch version
v5.1.0v5.1.3StandardMultiple patch versions
v3.43.0v4.0.0StandardA major version change but only one absolute version
v5.0.0v5.2.2MultiversionTwo minor versions and patch
v3.33.0v5.2.0MultiversionMajor and minor
v4.5.0v5.0.0StandardThis is a major version but only one version change
v4.4.2v5.0.3MultiversionMajor, minor, and patch

Note:

  • 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 service. 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.

Best Practices

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:

  1. Determine if your instance is ready to Upgrade (check upgrade notes)
  2. Merge the latest Sourcegraph release into your deployment manifests
  3. If updating more than a single minor version, perform an [automatic multi-version upgrade]/admin/updates/automatic) if targeting Sourcegraph 5.1 or later; [manual multi-verison upgrades]/admin/updates/migrator/migrator-operations) are required if upgrading to an earlier version, which requires shutting off the instance and invoking the migrator container or job to perform the database rewrite and application of unfinished out-of-band migrations
  4. 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.

Upgrade Readiness

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.

Screenshot 2023-05-17 at 1 37 12 PM

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

Upgrades index

Previous
Deploy
Next
Configuration