# Firestore emulator

> Run Firestore document and query workflows locally. Firestore is opt-in: add firestore to the --services list when you start LocalCloud.
>
> Source: https://local.cloud/services/firestore/

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

## 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.

Connection

Environment variable

`FIRESTORE_EMULATOR_HOST=localhost:5384`

Runtime details

- **Endpoints:** gRPC :5384
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Google Official

## 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](https://local.cloud/docs/)

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

Python:

### 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

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

#### Save as hello.py

```python
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

```bash
python hello.py
```

#### Verify the result

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

#### Expected output

```
hello
```

[Full example guide](https://local.cloud/docs/sdk-examples/#firestore-python)

Java:

### 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

```bash
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

```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

```bash
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

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Firestore emulator feature comparison](https://local.cloud/compare/emulators/?service=firestore): Browse features by category, see which ones only LocalCloud offers, and open Google's documentation for each.

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](https://local.cloud/ai/) 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](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Firestore documentation](https://docs.cloud.google.com/firestore/native/docs/overview): service concepts and cloud usage.