Backward-Compatible Document Migrations, Dual Readers / Writers, Backfills, and Feature Flags

1. AtlasMart needs a new product price model without breaking old clients

Schema v1 stores priceCents. Schema v2 needs a structured price map with amount/currency so AtlasMart can support multi-currency display. An irreversible “rename every field, then deploy the app” migration creates a compatibility cliff: old clients cannot read v2 and new clients cannot read unbackfilled v1.

Firestore does not run a central schema migration transaction over the whole database. Safe evolution is an application protocol: expand → dual-read/write → backfill → verify → switch → contract.

2. Versioned document contract

3. Dual reader with observable mismatch

export function readPrice(doc, metrics) {  const v1 = Number.isInteger(doc.priceCents) ? doc.priceCents : null;  const v2 = Number.isInteger(doc.price?.amountCents) ? doc.price.amountCents : null;  if (v1 != null && v2 != null && v1 !== v2) {    metrics.increment("price_dual_read_mismatch");  }  if (v2 != null) return { amountCents: v2, currency: doc.price.currency ?? "USD", source: "v2" };  if (v1 != null) return { amountCents: v1, currency: "USD", source: "v1-fallback" };  throw new Error("product has no readable price");}

The mismatch counter is the migration correctness signal. A 100% v2 population is not enough if v1/v2 values disagree.

4. Dual writer: keep invariant in one trusted function

export function encodePrice({ amountCents, currency }) {  if (!Number.isInteger(amountCents) || amountCents < 0) throw new Error("invalid amount");  return {    priceCents: amountCents,               // compatibility field    price: { amountCents, currency },      // target model    schemaVersion: 2  };}

For untrusted mobile/web writes, Rules must validate both representations during the window. For trusted Admin/server writes, application validation is mandatory because Admin bypasses Rules.

5. Backfill is a long-running distributed job, not a script with hope

6. Resumable local backfill with injected failure

import fs from "node:fs";import { db } from "./admin-emulator.mjs";const CHECKPOINT = "./tmp/price-v2-checkpoint.json";const state = fs.existsSync(CHECKPOINT) ? JSON.parse(fs.readFileSync(CHECKPOINT)) : { after: null, migrated: 0 };const failOn = process.env.FAIL_ON_ID ?? "";let q = db.collection("products").orderBy("__name__").limit(50);if (state.after) q = q.startAfter(state.after);for (;;) {  const snap = await q.get();  if (snap.empty) break;  for (const doc of snap.docs) {    const d = doc.data();    if (doc.id === failOn) throw new Error(`injected failure at ${doc.id}`);    if (d.schemaVersion !== 2) {      await doc.ref.set({        price: { amountCents: d.priceCents, currency: "USD" },        schemaVersion: 2      }, { merge: true });      state.migrated++;    }    state.after = doc.id;    fs.mkdirSync("./tmp", { recursive: true });    fs.writeFileSync(CHECKPOINT, JSON.stringify(state));  }  q = db.collection("products").orderBy("__name__").startAfter(state.after).limit(50);}console.log(state);

Production should use an appropriate bulk mechanism and pacing policy, not this tiny per-document example. The mechanism—idempotency, checkpointing, observability, bounded rate—remains the same.

7. Migration dashboard: percentage is not enough

const snap = await db.collection("products").get();const out = { total:0, v1:0, v2:0, mismatches:0, unreadable:0 };for (const doc of snap.docs) {  out.total++;  const d = doc.data();  if (d.schemaVersion === 2) out.v2++; else out.v1++;  const a = d.priceCents;  const b = d.price?.amountCents;  if (Number.isInteger(a) && Number.isInteger(b) && a !== b) out.mismatches++;  if (!Number.isInteger(a) && !Number.isInteger(b)) out.unreadable++;}console.log(out);

Also track backfill error IDs and old-client traffic. The “contract” step is allowed only when mismatches/unreadable documents are zero under your data-quality policy and legacy-reader usage is below the explicitly accepted threshold.

8. Feature flag controls behavior, not data truth

export function priceMode(flags) {  if (flags.forceV1) return "v1";  if (flags.v2CanaryPercent === 0) return "dual-read";  return "v2-preferred";}

If canary metrics degrade, switch readers back to v1/dual-read. This rollback does not delete v2 fields. Keeping additive data is safer than attempting a mass destructive reverse migration during an incident.

9. Controlled failure: irreversible rename

Wrong: backfill deletes priceCents as soon as it writes price. A deployment rollback then restores old code that cannot read migrated products.

Repair: additive expansion, dual compatibility, observed backfill, traffic cutover, then a separately approved contract phase after the rollback window closes.

10. Mandatory lab

1. Seed 12 v1 AtlasMart products.
2. Deploy local dual-compatible Rules/readers/writers.
3. Enable v2-preferred for a deterministic 25% canary cohort.
4. Run the backfill with FAIL_ON_ID=t-red__p-007; assert a nonzero failure/checkpoint.
5. Remove injection and resume; assert no duplicate business effect.
6. Run audit and require mismatches=0, unreadable=0.
7. Exercise rollback by setting forceV1=true; all documents must remain readable without reversing v2 fields.

Production judgment and bridge

Schema migration is complete only when the compatibility window has an exit criterion and rollback has been rehearsed. Lesson 5 turns all previous chapters into one production deployment checklist with explicit evidence owners.

Knowledge check

1. Why is additive migration safer than rename-in-place?
2. What makes a backfill resumable?
3. Why track dual-read mismatches?
4. Why should rollback usually keep newly added v2 fields?
5. What determines when the contract phase may begin?

Authoritative references

• Firebase: Connect your app to the Cloud Firestore Emulator — demo projects, edition selection, Admin SDK environment variables, reset/import/export, Rules reports, and production differences.
• Firebase: Install, configure and integrate Local Emulator Suite — emulators:exec, import/export and CI workflow.
• Firebase: Test Cloud Firestore Security Rules — emulator rules testing and CI execution.
• Firebase: Build Security Rules unit tests — @firebase/rules-unit-testing, mocked auth, clearing state and disabled-rules fixture setup.
• Firebase: Manage and deploy Security Rules — source control, local testing and selective deployment.
• Firebase: Manage indexes in Cloud Firestore — source-controlled index definitions and CLI deployment.
• Firebase: Cloud Firestore index definition reference — composite, field override and vector index JSON shapes.
• Firebase CLI reference — configured multi-database rules/indexes and deployment selectors.