Registry

When using the Mongoz, you must use the Registry object to tell exactly where the database is going to be.

Imagine the registry as a mapping between your documents and the database where is going to be written.

And is just that, nothing else and very simple but effective object.

The registry is also the object that you might want to use when generating migrations using Alembic.

import mongoz

database_uri = "mongodb://localhost:27017"
registry = mongoz.Registry(database_uri)


class User(mongoz.Document):
    """
    The User document to be created in the database as a table
    If no name is provided the in Meta class, it will generate
    a "users" table for you.
    """

    is_active: bool = mongoz.Boolean(default=False)

    class Meta:
        registry = registry
        database = "my_db"

Parameters

• url - The database URL to connect to.

  from mongoz import Registry
  
  registry = Registry(url="mongodb://localhost:27017")
  

Custom registry

Can you have your own custom Registry? Yes, of course! You simply need to subclass the Registry class and continue from there like any other python class.

import mongoz

database_uri = "mongodb://localhost:27017"
registry = mongoz.Registry(database_uri)


class MyRegistry(mongoz.Registry):
    """
    Add logic unique to your registry or override
    existing functionality.
    """

    ...


models = MyRegistry(database_uri)


class User(mongoz.Document):
    """
    The User document to be created in the database as a table
    If no name is provided the in Meta class, it will generate
    a "users" table for you.
    """

    is_active: bool = mongoz.Boolean(default=False)

    class Meta:
        registry = registry
        database = "my_db"

Run some document checks

Sometimes you might want to make sure that all the documents have the indexes up to date beforehand. This can be particularly useful if you already have a document and some indexes or were updated, added or removed. This functionality runs those checks for all the documents of the given registry.

import mongoz

database_uri = "mongodb://localhost:27017"
registry = mongoz.Registry(database_uri)


class User(mongoz.Document):
    """
    The User document to be created in the database as a table
    If no name is provided the in Meta class, it will generate
    a "users" table for you.
    """

    is_active: bool = mongoz.Boolean(default=False)

    class Meta:
        registry = registry
        database = "my_db"


# Make sure the document checks are run
await registry.document_checks()

Using within a framework

This functionality can be useful to be also plugged if you use, for example, an ASGI Framework such as Starlette, Lilya or Esmerald.

These frameworks handle the event lifecycle for you and this is where you want to make sure these checks are run beforehand.

Since Mongoz is from the same team as Lilya and Esmerald, let us see how it would look like with Esmerald.

from contextlib import asynccontextmanager

from esmerald import Esmerald

import mongoz

database_uri = "mongodb://localhost:27017"
registry = mongoz.Registry(database_uri)


class User(mongoz.Document):
    """
    The User document to be created in the database as a table
    If no name is provided the in Meta class, it will generate
    a "users" table for you.
    """

    is_active: bool = mongoz.Boolean(default=False)

    class Meta:
        registry = registry
        database = "my_db"


# Declare the Esmerald instance
app = Esmerald(routes=[...], on_startup=[registry.document_checks])


# Or using the lifespan
@asynccontextmanager
async def lifespan(app: Esmerald):
    # What happens on startup
    await registry.document_checks()
    yield
    # What happens on shutdown


app = Esmerald(routes=[...], lifespan=lifespan)