Learning center

How long the old column has to stay

The old shape of the data can go only when nothing that uses it can run or be read again. That moment is set by the longest of several clocks: the rollout, the rollback window, the longest job, the queue's retention, the cache's lifetime and the backups you might restore. Write each one down with its source, add them where they run in sequence, and take the longest where they run side by side. The result is a date, and it is usually later than the next release.

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.

ClockWho uses the old shapeExampleSource
RolloutPods of the previous release30 minutesDeploy history
Rollback windowThe previous release as a rollback target7 daysRelease policy
Longest jobA job that started under the old release6 hoursLongest run in 90 days
Job intervalA job that runs rarely and reads or writes the old column30 daysScheduler
Queue retentionMessages produced in the old shape4 daysRetention setting
Cache lifetimeCached objects built from the old shape1 hourTTL in the code
Other servicesReaders in other servicesuntil they shipTheir teams
Restore pointA backup restored into staging or production35 daysBackup retention

Combine them#

The clocks start at different events. Sequence them by the step each one blocks:

  1. 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.
  2. 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.

One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. Eligibility and fair-use terms.

Start free with GitHub

Related reading