Skip to main content
FirestoreDB is a lightweight wrapper around the google.cloud.firestore_v1.AsyncClient that provides a single, consistent way to configure your Firestore connection — whether you are targeting the production service, a local emulator during development, or a MagicMock in unit tests. Once constructed, pass it to init_firestore_odm to wire up all your document models.

​
Constructor

class FirestoreDB:
    def __init__(
        self,
        project_id: str,
        database: Optional[str] = None,
        credentials=None,
        emulator_host: Optional[str] = None,
    )
​
project_id
str
required
Your Google Cloud project identifier (for example "my-gcp-project"). This is passed directly to the underlying AsyncClient.
​
database
str | None
The Firestore database ID to connect to. Omit (or pass None) to use the default database "(default)".
​
credentials
google.auth.credentials.Credentials | None
Explicit Google Auth credentials object. When None the Google SDK’s Application Default Credentials chain is used automatically.
​
emulator_host
str | None
Host and port of a running Firestore emulator such as "localhost:8080". When provided, the constructor sets the FIRESTORE_EMULATOR_HOST environment variable and points the AsyncClient to the emulator instead of the production service.

​
The client attribute

After construction, FirestoreDB.client holds the live AsyncClient instance. You can access it directly if you need to run raw Firestore operations outside the ODM. 
raw_ref = db.client.collection("raw_collection").document("doc_id")
snap = await raw_ref.get()
The client attribute is replaced in-place by use_emulator, clear_emulator, and mock_firestore_for_tests. Any models that already have a reference to db will automatically use the new client because BaseFirestoreModel reads db.client at call time, not at injection time.

​
Methods

​
use_emulator

Switch the instance to a local Firestore emulator and recreate the AsyncClient. Sets the FIRESTORE_EMULATOR_HOST environment variable so that the Google client libraries route all traffic to the emulator. 
def use_emulator(self, host: str = "localhost:8080") -> None
​
host
str
default:"\"localhost:8080\""
The hostname and port where the Firestore emulator is listening. Uses "localhost:8080" by default, which matches the default port used by firebase emulators:start.
db = FirestoreDB(project_id="my-project")
db.use_emulator()          # connect to localhost:8080
db.use_emulator("0.0.0.0:9090")  # connect to a custom host/port

​
clear_emulator

Disable the emulator and reconnect to the production Firestore service. Removes the FIRESTORE_EMULATOR_HOST environment variable and recreates the AsyncClient pointing at the real backend. 
def clear_emulator(self) -> None

db.use_emulator()       # switch to emulator
# ... run some tests ...
db.clear_emulator()     # switch back to production

​
mock_firestore_for_tests

Replace client with a unittest.mock.MagicMock. This is the fastest way to isolate unit tests from Firestore without running the emulator or touching the network. 
def mock_firestore_for_tests(self) -> None
After calling this method, all calls to db.client return the mock. You can configure return values on the mock using standard unittest.mock APIs. No network calls are made.
db.mock_firestore_for_tests()
db.client.collection.return_value.document.return_value.get = AsyncMock(
    return_value=mock_snapshot
)

​
The init_firestore_odm function

init_firestore_odm is a standalone module-level function exported from firestore_pydantic_odm. It wires up one or more document model classes to a FirestoreDB instance in a single call, replacing the need to call initialize_db and initialize_fields on each class individually. It also populates the internal model registry used for cascade deletions. 
def init_firestore_odm(
    database: FirestoreDB,
    document_models: List[Type[BaseFirestoreModel]],
) -> None
​
database
FirestoreDB
required
The FirestoreDB instance to inject into every model class listed in document_models.
​
document_models
List[Type[BaseFirestoreModel]]
required
All model classes that should be registered with the ODM. Include every top-level collection model and every subcollection model — the order does not matter. The registry built from this list is used when performing cascade deletes.

​
Code examples

from firestore_pydantic_odm import FirestoreDB, init_firestore_odm, BaseFirestoreModel

class User(BaseFirestoreModel):
    class Settings:
        name = "users"
    username: str
    email: str

# Uses Application Default Credentials automatically
db = FirestoreDB(project_id="my-gcp-project")
init_firestore_odm(database=db, document_models=[User])

# Optional: target a named database (non-default)
db_named = FirestoreDB(
    project_id="my-gcp-project",
    database="my-secondary-db",
)