Rolling back a Postgres database

If a customer downgrades their instance to a previous version, they need to downgrade their database schema in two circumstances:

1. Developer created backwards-incompatible migration: if a migration added in the successor version that was not backwards-compatible, the code of the previous version may struggle operating with the new schema. This may be an emergency situation in which the previous schema must be restored to bring the instance back to a stable state.
2. The customer is downgrading multiple versions: if a customer has downgraded their instance once, they will need to downgrade their database schema before downgrading their instance a subsequent time. This is because an instance two (or more) versions ago has no guarantee to run properly against the current database schema. Multiple instance downgrades therefore need to be performed in an alternating fashion with database downgrades.

Resolution

A database schema downgrade will not always be enough. If a newer version was running even for a small time, it could have migrated data in the background into a format that's no longer readable by the previous version of Sourcegraph.

The migrator can be used to run both schema and data migrations (in the appropriate order) so that the old version of Sourcegraph can start and run without broken features. See the command documentation for additional details.

The log output of the migrator should include INFO-level logs and successfully terminate with migrator exited with code 0. If you see an error message or any of the databases have been flagged as "dirty", please follow "How to troubleshoot a dirty database". A dirty database at this stage requires manual intervention. Please contact support at mailto:[email protected] or via your enterprise support channel for further assistance.