Migration guides

Out of band migrations

Sourcegraph runs data migrations in the background while the instance is active instead of requiring a blocking migration during startup or manual migrations requiring downtime.

Migrations are introduced at a particular version with an expected lifetime (a course of several versions). At the end of this lifetime, the migration will be marked as deprecated and the instance will no longer be able to read the old data. This requires that migrations finish prior to an upgrade to a version that no longer understands your instance's data.

The Site Admin > Maintenance > Migrations page shows the progress of all active migrations. This page will also display a prominent warning if when upgrade (or downgrade) would result in an instance that refuses to start due to an illegal migration state.

Unfinished migration warning

In this situation, upgrading to the next version will not result in any data loss, but all new instances will detect the illegal migration state and refuse to start up with a fatal message (Unfinished migrations).

See How to troubleshoot an unfinished migration for more information.

Legacy guides