Skip to content
You're not viewing the latest version. Click here to go to latest.

# Beanie

FastAPI Users provides the necessary tools to work with MongoDB databases using the Beanie ODM.

## Setup database connection and collection

The first thing to do is to create a MongoDB connection using mongodb/motor (automatically installed with Beanie).

    import motor.motor_asyncio
    from beanie import PydanticObjectId
    from fastapi_users.db import BeanieBaseUser, BeanieUserDatabase

    DATABASE_URL = "mongodb://localhost:27017"
    client = motor.motor_asyncio.AsyncIOMotorClient(
        DATABASE_URL, uuidRepresentation="standard"
    )
    db = client["database_name"]

    class User(BeanieBaseUser[PydanticObjectId]):
        pass

    async def get_user_db():
        yield BeanieUserDatabase(User)

You can choose any name for the database.

## Create the User model

As for any Beanie ODM model, we'll create a `User` model.

    import motor.motor_asyncio
    from beanie import PydanticObjectId
    from fastapi_users.db import BeanieBaseUser, BeanieUserDatabase

    DATABASE_URL = "mongodb://localhost:27017"
    client = motor.motor_asyncio.AsyncIOMotorClient(
        DATABASE_URL, uuidRepresentation="standard"
    )
    db = client["database_name"]

    class User(BeanieBaseUser[PydanticObjectId]):
        pass

    async def get_user_db():
        yield BeanieUserDatabase(User)

As you can see, FastAPI Users provides a base class that will include base fields for our `User` table. You can of course add you own fields there to fit to your needs!

Document ID is a MongoDB ObjectID

Beanie automatically manages document ID by encoding/decoding MongoDB ObjectID.

If you want to use another type, like UUID, you can override the `id` field:

    import uuid

    from pydantic import Field

    class User(BeanieBaseUser[uuid.UUID]):
        id: uuid.UUID = Field(default_factory=uuid.uuid4)

Notice that `BeanieBaseUser` expects a generic type to define the actual type of ID you use.

Info

The base class is configured to automatically create a unique index on `id` and `email`.

## Create the database adapter

The database adapter of FastAPI Users makes the link between your database configuration and the users logic. It should be generated by a FastAPI dependency.

    import motor.motor_asyncio
    from beanie import PydanticObjectId
    from fastapi_users.db import BeanieBaseUser, BeanieUserDatabase

    DATABASE_URL = "mongodb://localhost:27017"
    client = motor.motor_asyncio.AsyncIOMotorClient(
        DATABASE_URL, uuidRepresentation="standard"
    )
    db = client["database_name"]

    class User(BeanieBaseUser[PydanticObjectId]):
        pass

    async def get_user_db():
        yield BeanieUserDatabase(User)

Notice that we pass a reference to the `User` model we defined above.

## Initialize Beanie

When initializing your FastAPI app, it's important that you initialize Beanie so it can discover your models. We can achieve this using a startup event handler on the FastAPI app:

    from beanie import init_beanie

    @app.on_event("startup")
    async def on_startup():
        await init_beanie(
            database=db,  # (1)!
            document_models=[
                User,  # (2)!
            ],
        )

1. This is the `db` Motor database instance we defined above.

2. This is the Beanie `User` model we defined above. Don't forget to also add your very own models!

Back to top