The clocks#
Each item is the time after which one kind of old-shape user is gone. The example values are for a hypothetical orders service; replace them with yours and name where each figure comes from.
| Clock | Who uses the old shape | Example | Source |
|---|---|---|---|
| Rollout | Pods of the previous release | 30 minutes | Deploy history |
| Rollback window | The previous release as a rollback target | 7 days | Release policy |
| Longest job | A job that started under the old release | 6 hours | Longest run in 90 days |
| Job interval | A job that runs rarely and reads or writes the old column | 30 days | Scheduler |
| Queue retention | Messages produced in the old shape | 4 days | Retention setting |
| Cache lifetime | Cached objects built from the old shape | 1 hour | TTL in the code |
| Other services | Readers in other services | until they ship | Their teams |
| Restore point | A backup restored into staging or production | 35 days | Backup retention |
Combine them#
The clocks start at different events. Sequence them by the step each one blocks:
- Stop writing the old column when no release that reads it can run or be rolled back to. The release that switched readers to the new column has to finish its rollout and then outlast the rollback window, so its predecessor is no longer a target: 30 minutes plus 7 days. The queue, cache and longest-job clocks run in parallel inside that week, so they matter only if one is longer. In the example none is.
- Drop the old column when nothing can read it again. After writes stop, the remaining clocks are the job interval (30 days), and any other service. A restore point of 35 days means a backup taken before the switch can still be restored; dropping the column does not affect a restore, but code that reads a restored database has to handle whichever shape the backup holds.
For the example, the old column stops receiving writes about one week after the switch, and can be dropped about 30 days after that, provided no other service still reads it. A plan that drops it in the next release, a week after the switch, breaks the monthly job's next run.
What to do with the result#
Put the date and its sources in the pull request that stops the writes and in the one that drops the column. A reviewer can then check each clock against the record it names, instead of trusting the date. When a clock has no source, such as an unknown job interval, the evidence is missing, and the date cannot be set until someone finds it: tag PostgreSQL connections with the release that opened them and find every query that still reads the old column produce the job and reader evidence.
The steps these dates gate are in decide when to stop writing the old column. The queue clock is shown in new-format messages still in the queue after a rollback, and the cache clock in keep old and new cache entries consistent when both releases write.