Field notes / Startup & Product
The migration is not done when the new database is online
Explain reconciliation, cutover, late writes, and rollback boundaries.
A new database accepting connections is an infrastructure milestone. It does not establish that the migration preserved the business. The harder questions are whether the right records arrived, whether relationships still resolve, and what happened while the copy was running.
This site's public architecture moved editorial content into files and private business records into PostgreSQL. The following model discusses the architecture and the cutover decisions; it contains no customer records, private export contents, or production reconciliation totals.
Compare identities before counting rows
Two datasets can have equal counts and different records. Start with stable identifiers, then compare meaningful fields and relationships. An import that quietly generates new IDs can break access links or external references even when every visible title looks correct.
Reconcile before cutover
Reconcile stable identities and meaningful fields, capture late writes, and compare the final delta before switching traffic.
Illustrative framework · Graphic by Nick JensenRead the diagram as text
Flow from export source with stable ids, then import into destination, then compare ids and fields, then capture writes since export, then freeze source writes, then reconcile final delta, then switch reads and writes, then verify destination. Reconcile stable identities and meaningful fields, capture late writes, and compare the final delta before switching traffic.
For a fictional proposal record, compare its stable ID, customer relationship, accepted version, and external payment reference. Normalize only fields whose meaning permits it. Treating absent and empty values as equal without a contract can conceal a change in behavior.
Account for writes during the copy
Imagine exporting at one point, then receiving a new submission before traffic switches. A successful import of the earlier snapshot will still omit that submission. A cutover needs either a write freeze or a reliable way to capture and reconcile the delta, followed by a final comparison at the switch boundary.
An idempotent import keyed by stable identity makes rehearsals safer. PostgreSQL's INSERT conflict handling supplies useful primitives, but the application still decides which source owns each field. An upsert that overwrites a newer destination value is repeatable and wrong.
The rollback boundary
After destination writes or external effects, recovery requires reconciliation as well as a deployment decision.
Illustrative framework · Graphic by Nick JensenRead the diagram as text
Before destination writes: Revert routing after verifying the source remains authoritative.; After destination writes: Pause and reconcile new records. A code revert cannot move data back.; After external effects: Reconcile payments and messages. Restore must not repeat those effects. After destination writes or external effects, recovery requires reconciliation as well as a deployment decision.
Write the rollback boundary down
Before destination writes, routing back may be straightforward if the source remains authoritative and compatible. After destination writes, reverting code leaves those writes behind. Pause, identify the divergence, and reconcile before declaring the source authoritative again.
External effects make recovery stricter. Replaying a submission must not resend every message or repeat a payment action. Preserve provider references and deduplication identities, and separate data repair from side-effect delivery.
Backups should remain access controlled and outside public content. Retaining an export is useful only if an operator can explain its scope, validate it, and restore or reconcile it safely. Never publish private snapshots as proof that a migration worked.
The practical handoff is a reconciliation report, an owner, the switch decision, and an explicit recovery procedure. See duplicate-safe workflows for retry identity and the recovery guide for incident decisions. If a migration needs an accountable implementation owner, discuss a scoped build.
From the idea to the work
Make the workflow useful in a real product.
Bring a product idea, an internal tool, or an AI-assisted workflow that needs a working implementation.