Firestore emulator

Firestore is a document database that organizes application data into collections and documents. It suits flexible records such as profiles, catalogs, and application state.

When to use Firestore

Typical uses

Use when records have evolving fields and fit a collection-and-document model, with reads driven by document IDs or indexed field queries.

Examples

User profiles and product catalogs
Document-based application backends

Databases

Firestore is opt-in to save memory. Add firestore to the services you start, for example localcloud start --local-only --services firestore,gcs,pubsub; --services sets the exact list.

Hello world

Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1. Install and start · shell

curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only --services firestore
# Export GOOGLE_CLOUD_PROJECT and FIRESTORE_EMULATOR_HOST
eval "$(localcloud env)"

Python

Create, read, and update a document

2. Install SDK · shell

python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-firestore

3. Save as hello.py

import os
from uuid import uuid4
from google.cloud import firestore

assert os.environ['FIRESTORE_EMULATOR_HOST']
client = firestore.Client(project=os.environ['GOOGLE_CLOUD_PROJECT'])
document = client.collection('guide').document(uuid4().hex)
try:
    document.set({'message': 'hello'}, timeout=30)
    message = document.get(timeout=30).get('message')
    assert message == 'hello'
    print(message)
    document.update({'message': 'updated'}, timeout=30)
    assert document.get(timeout=30).get('message') == 'updated'
finally:
    document.delete(timeout=30)
    client.close()

4. Runpython hello.py

Full example guide

Documented workflows

Document CRUD
Queries and single-field indexes

Service boundaries

Opt-in: add firestore to localcloud start --services
Validate composite indexes, concurrent transactions, listeners, and transforms
Security Rules and Firestore triggers need runtime validation

Try it in your project

Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

Integration

Build an integration test loop

Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Open guide

Agent testing

Use Firestore with an AI agent

Before the agent changes application logic, have it create local Firestore state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

Configure this repo

Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.