path: root/ops/id-unification.md

---
title: ID unification migration plan
---

**DRAFT**

A coming update to SourceHut's internal design calls for the values of the ID
columns in our databases to be made uniform. Each database (e.g. for git, hg,
builds, etc) maintained its own copy of tables with shared information, sourcing
updates from meta.sr.ht via webhooks, but each of these rows had an ID specific
to each database. This change will make these IDs uniform across all services in
preparation for linking our services more tightly together through GraphQL
Federation.

This document outlines the extra steps required to perform this upgrade for
third-party instances.

## Upgrade process

For meta.sr.ht:

1. Disable automatic migrations
1. Upgrade meta.sr.ht, restart the services, and ensure that the meta.sr.ht
   GraphQL API is online
1. Re-enable automatic migrations if desired

Then, for each service, one at a time:

1. Disable automatic migrations
1. Shut off the service
1. Run upgrades
1. Run `$service-migrate upgrade head` (e.g. gitsrht-migrate) for each service
   and monitor the migration progress
1. Turn on the service
1. Re-enable automatic migrations if desired

## Downgrade process

1. Disable automatic migrations
1. Downgrade meta.sr.ht and restart the services

Then, for each service, one at a time:

1. Shut off the service
1. Run `$service-migrate downgrade $version`, selecting $version from the list
   below, for each service
1. Downgrade the software
1. Turn on the service
1. Re-enable automatic migrations if desired

## Affected database schema revisions

Last schema revision prior to this change, for reference if downgrading:

- builds.sr.ht: *TODO*
- git.sr.ht: *TODO*
- hg.sr.ht: *TODO*
- hub.sr.ht: *TODO*
- lists.sr.ht: *TODO*
- man.sr.ht: *TODO*
- pages.sr.ht: *TODO*
- todo.sr.ht: *TODO*