# Updating Sourcegraph

<TierCallout>
	Supported on [Enterprise](/pricing/plans/enterprise) plans.
	<user>Available via the Web app.</user>
</TierCallout>

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](#instance-specific-procedures).**

> _Note: For product update notes, please refer to the [technical changelog](https://sourcegraph.com/changelog/releases)._

## General concepts

### Upgrading

A new Sourcegraph release consists of updated images that incorporate code changes. It also includes modifications to deployment manifests in our supporting deployment repositories, such as our [k8s helm repo](https://github.com/sourcegraph/deploy-sourcegraph-helm).

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 have three digits, for example: `v5.0.3`
| Description | Version |
|---------------|---------|
| major | `5` |
| minor | `0` |
| patch | `3` |

For more details on previous releases see [Sourcegraph Releases](/releases).

Generally, we ship a new minor version of Sourcegraph with new features and bug fixes monthly, followed by a patch release later that month.

Check the [Sourcegraph blog](https://about.sourcegraph.com/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. Note: AMI deployments will be sunset in 7.0.0.**

> _Note: Patch versions don't determine upgrade type -- you should always upgrade to the latest patch._

| From Version | To Version | Upgrade Type | Notes                                                |
| ------------ | ---------- | ------------ | ---------------------------------------------------- |
| `v5.0.0`     | `v5.1.0`   | Standard     | A minor version                                      |
| `v5.0.0`     | `v5.2.0`   | Multiversion | Two minor versions                                   |
| `v3.41.0`    | `v3.42.2`  | Standard     | A minor version and patch version                    |
| `v5.1.0`     | `v5.1.3`   | Standard     | Multiple patch versions                              |
| `v3.43.0`    | `v4.0.0`   | Standard     | A major version change but only one absolute version |
| `v5.0.0`     | `v5.2.2`   | Multiversion | Two minor versions and patch                         |
| `v3.33.0`    | `v5.2.0`   | Multiversion | Major and minor                                      |
| `v4.5.0`     | `v5.0.0`   | Standard     | This is a major version but only one version change  |
| `v4.4.2`     | `v5.0.3`   | Multiversion | Major, 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 [support@sourcegraph.com](mailto:support@sourcegraph.com)_
> -   _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](https://docs-legacy.sourcegraph.com/dev/background-information/sql/migrations_overview).
-   For a full listing of migrator's command arguments see its [usage docs](/self-hosted/updates/migrator/migrator-operations).

### 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. Select an upgrade method:
    - If updating more than a single minor version, perform a multiversion upgrade with the migrator [upgrade command](/self-hosted/updates/migrator/migrator-operations#upgrade). _This method requires downtime._
    - If updating a single minor version, perform a standard upgrade with the [migrator up command](/self-hosted/updates/migrator/migrator-operations#up). `up` is the default migrator entry command and runs on `frontend` startup.
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

Navigate 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](https://storage.googleapis.com/sourcegraph-assets/docs/239155807-185fc3e8-0706-4a23-b9fe-e262f9a9e4b3.png)

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 [support@sourcegraph.com](mailto:support@sourcegraph.com).

-   [More info on OOB migrations](https://docs-legacy.sourcegraph.com/dev/background-information/sql/migrations_overview#out-of-band-migrations)
-   [More info on schema drift](/self-hosted/updates/migrator/schema-drift)

## Instance Specific Procedures

### Upgrades index

-   **Sourcegraph with Docker Compose**
    -   [Standard Upgrade Operations](/self-hosted/deploy/docker-compose/upgrade#standard-upgrades)
    -   [Multiversion Upgrade Operations](/self-hosted/deploy/docker-compose/upgrade#multi-version-upgrades)
    -   [Upgrade Notes](https://sourcegraph.com/changelog/self-hosted/docker-compose)
-   **Sourcegraph with Kubernetes**
    -   **Kustomize**
        -   [Standard Upgrade Operations](/self-hosted/deploy/kubernetes/upgrade#standard-upgrades)
        -   [Multiversion Upgrade Operations](/self-hosted/deploy/kubernetes/upgrade#multi-version-upgrades)
    -   **Helm**
        -   [Standard Upgrade Operations](/self-hosted/deploy/kubernetes#standard-upgrades)
        -   [Multiversion Upgrade Operations](/self-hosted/deploy/kubernetes#multi-version-upgrades)
    -   [Upgrade Notes](https://sourcegraph.com/changelog/self-hosted/kubernetes)
-   **Single-container Sourcegraph with Docker (removed in 7.0.0)**
    -   The single-container deployment mode has been sunset. [Migrate to Docker Compose](/self-hosted/deploy/docker-compose/migrate) or [Kubernetes](/self-hosted/deploy/kubernetes/).
    -   [Upgrade Notes](https://sourcegraph.com/changelog/self-hosted/server)
-   [**Pure-docker custom deployments**](/self-hosted/updates/pure-docker)
-   [**Sourcegraph AWS AMI instances**](/self-hosted/deploy/machine-images/aws-ami#upgrade) *(deprecated — sunset in 7.0.0)*

## Other helpful links

-   [PostgreSQL Collation Version Mismatch Resolution](/self-hosted/postgresql-collation-version-mismatch-resolution)
-   [Postgres 12 End Of Life Notice](/self-hosted/postgres12-end-of-life-notice) — **Note:** Starting in 7.0.0, the automatic PG12→PG16 upgrade entrypoint script has been removed. Users on PG12 must upgrade to a 6.x release first.
-   [Migrator operations](/self-hosted/updates/migrator/migrator-operations)
-   [Upgrading Early Versions](/self-hosted/updates/migrator/upgrading-early-versions)
-   [Troubleshooting upgrades](/self-hosted/updates/migrator/troubleshooting-upgrades)
-   [Downgrading](/self-hosted/updates/migrator/downgrading)