How to Configure Firestore Schema Migration
You run a firestore schema migration by updating app code and rewriting old records. Because Firestore has no fixed tables, your team changes data shapes through code. Most teams start by giving a worker script broad admin rights to edit all documents. That approach works fast in testing, but broad roles create big risks in live data. A single bug in your script can wipe out collections or leak private fields. How a native firestore schema migration works Firestore stores data as documents in
Your coding agents run with your access.
Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.
You run a firestore schema migration by updating app code and rewriting old records. Because Firestore has no fixed tables, your team changes data shapes through code. Most teams start by giving a worker script broad admin rights to edit all documents. That approach works fast in testing, but broad roles create big risks in live data. A single bug in your script can wipe out collections or leak private fields.
How a native firestore schema migration works
Firestore stores data as documents inside collections, so two documents can hold different fields. When your app needs a new data shape, you cannot run one table change command. Instead, your team must manage both old and new document formats at the same time.
First, you update your app code so it can read both the old and new fields. If a record still has the old shape, the app translates it in memory during reads. Next, you turn on dual writes in your app logic. Every time a user saves data, the app writes the new format to the database.
After your app handles both formats, you run a background script to update old records. This script reads documents in small batches, transforms the fields, and writes the changes back. Once every document uses the new shape, you remove the old fallback read logic from your app.
How to set up roles and batch jobs
To run the backfill script, you set up a dedicated service account in your cloud console. You assign a database role that grants read and write permissions to that account. Many teams attach a full owner role so the script never hits a permission error.
A safer approach is to scope permissions to only the specific task. You also want to limit how many writes the batch job sends each second. High write speeds can trigger quota limits or slow down live user traffic. Breaking the job into small batches lets you pause the run if errors appear.
End-to-End Encryption + API Schema Validation: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What native roles solve and where gaps remain
Cloud roles and database security rules decide which user or service can log in. They do a great job of blocking outside attackers from reading your database collections. They also help you separate test projects from live production data.
Still, native roles only check who logs in at the start of a session. They do not inspect what individual batch writes or queries do in flight. Once an engineer or script holds a valid role, the database allows every write command.
If an engineer runs a backfill script from a laptop, raw user records pass through that machine. Native roles will not rewrite emails, phone numbers, card numbers, or national IDs in results. Also, standard cloud logs often miss which human ran a shared migration script. Teams need a way to review write jobs before they run and mask sensitive fields in results.
Check database and API queries on the wire
Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev sits inline in the wire protocol beside those services as an open-source proxy, a sidecar for your Postgres or API. On every query an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.
Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run, and hoop.dev data masking rewrites matched sensitive values in responses in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.
Frequently asked questions
Why does a schemaless database need a schema migration?
Your app code still expects specific field names and data types to work right. When product features change, you must update old documents so your code stays clean and fast.
Should we update all Firestore documents at once or on read?
Updating on read works well for small apps where users log in often. For analytics or full search changes, run a batch backfill so every document shares the same shape.
How do we test a Firestore migration script before production?
Export a small sample of data into a staging project or local emulator first. Run your batch script there and check the updated document fields before touching live data.
Related guides
In this post