Skip to main content

Google Firestore Provider

The Firestore provider implements ICloudNativePersistenceProvider for Google Cloud workloads with real-time document listeners, hierarchical collection paths, and batch write support.

Before You Start​

  • .NET 8.0+ (or .NET 9/10 for latest features)
  • A Google Cloud project with Firestore enabled
  • Familiarity with data access and IDb interface

Installation​

dotnet add package Excalibur.Data.Firestore

Dependencies: Excalibur.Data.Abstractions, Google.Cloud.Firestore

Quick Start​

using Microsoft.Extensions.DependencyInjection;

services.AddFirestore(options =>
{
    options.ProjectId = "my-gcp-project";
});

Registration Methods​

MethodWhat It RegistersKey Options
AddFirestore(opts)Core persistence providerProjectId, EmulatorHost
AddFirestoreWithDatabase(opts)Provider with specific databaseProjectId, DatabaseId
AddFirestoreSnapshotStore(opts)ISnapshotStoreCollectionName
AddFirestoreInboxStore(opts)IInboxStoreCollectionName

All methods also accept IConfiguration binding: AddFirestore(configuration, sectionName: "Firestore").

Change Data Capture​

services.AddCdcProcessor(cdc =>
{
    cdc.UseFirestore(firestore =>
    {
        firestore.CollectionPath("orders")
                 .WithStateStore("state-project-id", state =>
                 {
                     state.TableName("cdc-checkpoints");
                 });
    })
    .TrackTable("orders", t => t.MapAll<OrderChangedEvent>())
    .EnableBackgroundProcessing();
});

Collection Hierarchies​

Firestore supports hierarchical document/collection paths:

var key = new PartitionKey("users/user-123/orders", "/collection");
var orders = await provider.QueryAsync<Order>(
    queryText: "",
    key,
    parameters: null,
    consistencyOptions: null,
    cancellationToken: ct);

See Also​