FireSync: Migrating Firestore Schema Between Environments

Firestore Schema Migration

The Problem

Everything works in dev. Indexes are created automatically on the first query. TTL is configured through the console. Life is good.

Then you deploy to staging or production:

FAILED_PRECONDITION: The query requires an index.

No indexes. No TTL policies. Now you need to:

• Manually open links from error logs
• Wait 5–15 minutes for each index
• Repeat for every environment
• Remember TTL (spoiler: you won’t — and the database bloats for months)

Firebase CLI doesn’t solve this:

• No concept of environments
• Doesn’t support TTL policies
• No way to compare “what’s in dev vs what’s in prod”

Solution: FireSync

https://pypi.org/project/firestore-schema-migration/0.1.1/

pip install firestore-schema-migration

The killer feature — migration between environments:

# What's different between dev and prod?
firesync plan --env-from=dev --env-to=prod

# Output:
# [+] WILL CREATE: orders COLLECTION userId:asc | createdAt:desc
# [+] WILL CREATE: users COLLECTION email:asc
# [+] WILL CREATE TTL: authTokens.expiresAt

# Apply dev schema to prod
firesync apply --env-from=dev --env-to=prod

All indexes and TTL policies from dev are transferred to prod in seconds.

Quick Start

1. Setup

firesync init
firesync env add dev --key-path=./secrets/gcp-key-dev.json
firesync env add prod --key-env=GCP_PROD_KEY

Authentication options:

--key-path — direct path to key file, best for local development:

firesync env add dev --key-path=./secrets/gcp-key-dev.json

--key-env — environment variable name, best for CI/CD. Auto-detects the format:

# Option A: JSON content directly in the variable (GitHub Secrets, GitLab CI)
export GCP_PROD_KEY='{"type":"service_account","project_id":"my-project",...}'

# Option B: Path to key file
export GCP_PROD_KEY='/path/to/service-account.json'

# Both work with the same command:
firesync env add prod --key-env=GCP_PROD_KEY

2. Export schema from dev

firesync pull --env=dev

Creates JSON files with all indexes and TTL policies.

3. Migrate to prod

firesync plan --env-from=dev --env-to=prod   # Preview
firesync apply --env-from=dev --env-to=prod  # Apply

CI/CD

# GitHub Actions
deploy:
  steps:
    - run: pip install firestore-schema-migration

    - name: Migrate schema to prod
      env:
        GCP_PROD_KEY: ${{ secrets.GCP_KEY }}
      run: |
        firesync plan --env-from=dev --env-to=prod
        firesync apply --env-from=dev --env-to=prod

Common Scenarios

New environment:

firesync apply --env-from=dev --env-to=staging

New GCP project:

firesync env add new-prod --key-path=./secrets/new-project.json
firesync apply --env-from=old-prod --env-to=new-prod

What Can FireSync Do?

✅ Composite indexes — complex indexes for multi-field queries ✅ Single-field indexes — configure indexing for individual fields ✅ TTL policies — automatic deletion of outdated documents ✅ Multiple environments — dev, staging, production ✅ Version control — store schema in Git ✅ Declarative approach — describe desired state, not steps

How to Help the Project?

• 🐛 Found a bug? Open an issue with description
• 💡 Have an idea? Suggest it in GitHub Discussions
• 🔧 Can fix it? Pull requests are welcome!
• ⭐ Like it? Star on GitHub
• 📝 Using it? Share your experience in comments

Conclusion

Managing Firestore schemas shouldn’t be painful. With FireSync you get:

✅ Version control for entire database schema ✅ Reproducible deployments via CI/CD ✅ Protection from forgotten TTL policies ✅ Easy migration between environments ✅ Transparent changes via Git history

GitHub: https://github.com/PavelRavvich/firesync

PyPI: https://pypi.org/project/firestore-schema-migration/

• Please consider clapping and following the writer! 👏
• Follow us on **Twitter(X), [LinkedIn](https://www.linkedin.com/in/pavel-ravvich/)**

Paul Ravvich