Firetool

Home / Docs / Compare and migrate

Docs

Compare and migrate Firestore environments

Put staging and production side by side: whole databases, a collection's fields, security rules and Authentication settings. Then bring what staging has into production with a preview first. Comparing only reads and works in the Free edition; migrating writes and needs Pro.

Compare databases

  1. Choose Tools → Compare databases…, or right-click a database in the sidebar and choose Compare with another database….
  2. Pick the project and database for A and for B, for example staging and production.
  3. Choose Count collections. Every top-level collection is listed with its number of documents in A and in B, and the ones only on one side are marked. This takes few reads.
  4. Tick the collections to look at closely and choose Compare documents. Both sides are read 1,000 documents a page, with their subcollections (untick that to leave them out), and each collection gets its documents only in A, only in B, different and the same. Large comparisons say how many reads they take first.
  5. Show differences lists the first 500 of a collection; each one opens both versions side by side. Compare collections opens that collection in Compare collections with A and B filled in, where you can copy chosen differences (copying needs Pro).

The comparison runs as a job in Tasks, with Pause, Resume and Cancel. It holds only a page of each side at a time, so big databases don't fill your computer's memory, and it never writes.

Compare a collection's fields

In the Schema tab, Compare with… reads the same collection in another project or database, with the same sample size (the reads are confirmed when they're many). Every field is listed side by side: only here, only there, stored with other types, or in every document on one side only. Matching fields are hidden unless you ask for them, and Close comparison goes back to the collection's own fields. It only reads.

Compare and promote security rules

  1. Open Security rules (right-click a database, or Tools) and switch to the Compare view.
  2. Choose another project and database, or for Storage rules, another bucket. Its live rules are shown against the editor here: only the lines that differ, with a few around them.
  3. Put theirs in this editor copies their rules into the editor here. Open … with these rules opens the other side's rules in a new tab with this editor's text, to promote them there.
  4. Nothing goes live until you press Deploy in that editor. Deploy reads the live rules again and shows what changes, refuses when someone deployed in the meantime, asks for the project ID on production, and keeps the replaced rules in the audit log.

Compare Authentication settings

In a project's Authentication tab, Compare settings… (also in the command palette) lists two projects' sign-in providers, authorised domains, password policy and account settings side by side, the differences first: one account per email, two-step sign-in, email enumeration protection and blocking functions. Each project's own domains (project.firebaseapp.com, project.web.app) count as the same. It only reads, and client secrets and password hash keys never leave Firetool's main process, so they aren't shown.

Migrate environments

Tools → Migrate environments… brings documents (with their subcollections, references pointed at the new place), composite indexes, Firestore security rules and Authentication users from one database into another.

  1. Choose the project and database for From and for To, and tick the parts to bring: Documents, Composite indexes, Security rules, Authentication users.
  2. Choose Preview. This is the dry run: it only reads both sides, and lists per collection the documents to create, the documents to replace and those only in To, which are left as they are; then the indexes and users to create, and whether the rules change.
  3. Choose Run migration. It writes exactly what the preview listed, as one job in Tasks you can pause and cancel: indexes first, then documents, users, and the rules last. A production target asks for its project ID once.
  4. When it's done, choose Preview again to see what's left. Each preview can be run once: after a run, preview again before running again.
  • Never overwrites newer work: a document changed in To since the preview is skipped and reported, never overwritten.
  • Never deletes: nothing in To is deleted, including documents only To has.
  • Can be undone: the whole migration is one operation in the audit log, so Undo this operation takes it back.
  • Masked when the rules say so: if an environment rule masks copies out of From's label, documents are compared and written with email addresses and phone numbers masked, and the preview says so. Users can't be masked, so they aren't migrated into another environment then.

Migrate environments needs Pro, and your role and the To project's rules apply to every write. Users already in To are kept as they are.

From the terminal

# What differs between two databases (reads only; exit code 6 when they differ)
firetool compare shop-staging shop-production
firetool indexes diff shop-staging shop-production

# Copy what's missing or different into B (Pro); list it first
firetool transfer shop-staging shop-production --dry-run
firetool transfer shop-staging shop-production --confirm shop-production

Each side is a project, or project/database. transfer never deletes in B, writes a document only while B's copy is still the one it read, and is one operation you can undo in the window; its --dry-run only reads, so it works in the Free edition. More in the firetool command.

Questions

How much does comparing two databases cost?

Count collections uses count queries, which cost little. Compare documents reads every document of the ticked collections on both sides, one read each, and says how many first when it's a lot.

Does Migrate environments delete documents that are only in production?

No. Documents only in To are listed and left as they are. Migrate only creates and replaces.