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

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.

Example usage

Service ID: firestore. Enable this service in the exact list of services your project starts; see the opt-in instruction above. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. First-time setup

# Export GOOGLE_CLOUD_PROJECT and FIRESTORE_EMULATOR_HOST
eval "$(localcloud env)"

Python

Create, read, and update a document

Create, read, update, and delete a document; Firestore stores flexible application records in collections.

Enable Firestore, exercise a unique document, and clean up through the SDK.

SDK dependencies

Run in a new example directory

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

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()

Run the example

python hello.py

Verify the result

The command completes successfully and prints the expected output shown below.

Expected output

hello

Full example guide

Java

Write and read a document

Write and retrieve a document; Firestore stores flexible application records in collections.

The Firestore client reads FIRESTORE_EMULATOR_HOST. Firestore must be enabled in your running instance. Requires JDK 17+ and Maven.

SDK dependencies

Run in a new example directory

cat > pom.xml <<'XML'
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId><artifactId>local-example</artifactId><version>1</version>
  <dependencies><dependency>
    <groupId>com.google.cloud</groupId><artifactId>google-cloud-firestore</artifactId><version>3.49.0</version>
  </dependency></dependencies>
</project>
XML
mvn -q dependency:build-classpath -Dmdep.outputFile=classpath.txt

Save as Hello.java

import com.google.cloud.firestore.FirestoreOptions;
import java.util.Map;
import java.util.Objects;
import java.util.UUID;

public class Hello {
  public static void main(String[] args) throws Exception {
    var host = Objects.requireNonNull(System.getenv("FIRESTORE_EMULATOR_HOST"));
    var options = FirestoreOptions.newBuilder()
        .setProjectId(Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT")))
        .setEmulatorHost(host).build();
    try (var database = options.getService()) {
      var document = database.collection("examples").document(UUID.randomUUID().toString());
      try {
        document.set(Map.of("message", "Hello from LocalCloud!")).get();
        System.out.println(document.get().get().getString("message"));
      } finally {
        document.delete().get();
      }
    }
  }
}

Run the example

java --class-path "$(cat classpath.txt)" Hello.java

Verify the result

The command completes successfully and prints the expected output shown below.

Expected output

Hello from LocalCloud!

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check localcloud status --verbose, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

Documented workflows

Document CRUD

Enable Firestore in the service list, create a document with a unique test ID, and read and update its fields. Delete the fixture and assert the missing-document path.
Queries and single-field indexes

Seed documents with different field values, run the filters and ordering used by the application, and compare the returned IDs. Test index setup separately from document creation.

Service boundaries

Opt-in; include firestore in the exact --services list
Validate composite indexes, concurrent transactions, listeners, transforms, Security Rules, and triggers

Code examples and integrations

Integration

Build an integration test loop

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

Open guide

Comparison

Firestore emulator feature comparison

Browse features by category, see which ones only LocalCloud offers, and open Google's documentation for each.

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.

Firestore emulator FAQ

How do I run Firestore locally?

Start LocalCloud using the setup guide, then export its environment in the same terminal as your application. Firestore is opt-in, so start it with localcloud start --local-only --services firestore,gcs,pubsub.

Which environment variable points the SDK at the local Firestore?

LocalCloud exports FIRESTORE_EMULATOR_HOST=localhost:5384. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

Does the local Firestore behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real Firestore before production deployment.

Related guides

Compatibility: compare all 27 service guides.
Configuration: service selection and runtime settings.
Official Firestore documentation : service concepts and cloud usage.

Firestore emulator

Typical uses

Explore another service

Example usage

Python

Create, read, and update a document

Save as hello.py

Run the example

Verify the result

Expected output

Java

Write and read a document

Save as Hello.java

Run the example

Verify the result

Expected output

Documented workflows

Document CRUD

Queries and single-field indexes

Service boundaries

Code examples and integrations

Build an integration test loop

Firestore emulator feature comparison

Use Firestore with an AI agent

Configure this repo

Firestore emulator FAQ

How do I run Firestore locally?

Which environment variable points the SDK at the local Firestore?

Does the local Firestore behave exactly like Google Cloud?

Related guides