Registry lifecycle¶

A Registry constructs and owns exactly one PyMongo AsyncMongoClient. Databases, collections, documents, managers, and QuerySets derived from it reuse that client and its connection pools.

Application lifetime¶

Create the Registry with application configuration, then close it during shutdown:

import asyncio

from mongoz import Document, Registry, String


async def main() -> None:
    registry = Registry("mongodb://localhost:27017")

    class HealthRecord(Document):
        status: str = String()

        class Meta:
            registry = registry
            database = "application"

    try:
        await registry.driver.admin.command("ping")
        await registry.document_checks()
    finally:
        await registry.close()


asyncio.run(main())

close() is async and idempotent. Closing is final: the Registry does not manufacture a replacement client and cannot be reopened. A database or collection wrapper obtained earlier is also invalid after its Registry is closed.

Bounded work¶

Use the async context manager for scripts, jobs, and tests whose ownership fits a lexical scope:

async with Registry("mongodb://localhost:27017") as registry:
    database = registry.get_database("analytics")
    await database.driver.command("ping")

If the body and cleanup both fail, Mongoz preserves the body failure and chains the cleanup failure as its cause. Cancellation is not translated.

Event-loop ownership¶

The native async client becomes bound to the loop that performs its first database operation. Do not share a Registry across event loops. Test suites that create a fresh loop per test should either use one loop-scoped Registry or construct and close a Registry inside each loop-owned fixture.

Read Registry, database, and collection for the wrapper model and Production setup for an application lifecycle example.