{"id":6361,"library":"fastapi-users-db-beanie","title":"FastAPI Users Beanie DB Adapter","description":"FastAPI Users database adapter for Beanie ODM, providing tools to integrate user management with MongoDB databases. It leverages Beanie, an asynchronous Object-Document Mapper built on Pydantic and Motor. The library is currently at version 5.0.0 and is in maintenance mode, focusing on security updates and dependency maintenance, with no new features planned.","status":"maintenance","version":"5.0.0","language":"en","source_language":"en","source_url":"https://github.com/fastapi-users/fastapi-users-db-beanie","tags":["FastAPI","users","authentication","Beanie","MongoDB","ODM"],"install":[{"cmd":"pip install fastapi-users-db-beanie","lang":"bash","label":"Pip"}],"dependencies":[{"reason":"Core user management library, this package is an adapter for it.","package":"fastapi-users"},{"reason":"Asynchronous MongoDB ODM. Requires Beanie >=2.0 for v5.0.0 of this adapter.","package":"beanie"},{"reason":"Asynchronous MongoDB driver, used by Beanie for database interactions.","package":"motor"}],"imports":[{"symbol":"BeanieBaseUser","correct":"from fastapi_users.db import BeanieBaseUser"},{"symbol":"BeanieUserDatabase","correct":"from fastapi_users.db import BeanieUserDatabase"},{"note":"Since v2.0.0, BeanieBaseUser is a mixin and must explicitly inherit from beanie.Document.","wrong":"from fastapi_users.db import BeanieBaseUser # when not inheriting Document","symbol":"Document","correct":"from beanie import Document"},{"note":"BeanieBaseUser only supports PydanticObjectId as the ID type since v2.0.0.","wrong":"from beanie import ObjectId","symbol":"PydanticObjectId","correct":"from beanie import PydanticObjectId"}],"quickstart":{"code":"import os\nfrom typing import AsyncGenerator\n\nimport motor.motor_asyncio\nfrom beanie import Document, init_beanie, PydanticObjectId\nfrom fastapi import Depends, FastAPI\nfrom fastapi_users import FastAPIUsers, schemas\nfrom fastapi_users.authentication import BearerTransport, AuthenticationBackend\nfrom fastapi_users.db import BeanieBaseUser, BeanieUserDatabase\n\n# --- Beanie/MongoDB Setup ---\nDATABASE_URL = os.environ.get('MONGODB_URL', 'mongodb://localhost:27017')\nclient = motor.motor_asyncio.AsyncIOMotorClient(\n    DATABASE_URL,\n    uuidRepresentation=\"standard\"\n)\ndb = client[os.environ.get('MONGODB_DB_NAME', 'database_name')]\n\nclass User(BeanieBaseUser[PydanticObjectId], Document):\n    # You can add custom fields here\n    pass\n\nclass UserRead(schemas.BaseUser[PydanticObjectId]):\n    pass\n\nclass UserCreate(schemas.BaseUserCreate):\n    pass\n\nclass UserUpdate(schemas.BaseUserUpdate):\n    pass\n\nasync def get_user_db() -> AsyncGenerator[BeanieUserDatabase, None]:\n    yield BeanieUserDatabase(User)\n\n# --- FastAPI Users Setup ---\nbearer_transport = BearerTransport(tokenUrl=\"auth/jwt/login\")\n\ndef get_jwt_strategy():\n    SECRET = os.environ.get('AUTH_SECRET', 'YOUR_SUPER_SECRET_KEY') # CHANGE THIS IN PRODUCTION!\n    return AuthenticationBackend(\n        name=\"jwt\",\n        transport=bearer_transport,\n        get_user_token_data=UserRead, # Or your custom token data schema\n        secret=SECRET,\n        lifetime_seconds=3600\n    )\n\nfastapi_users = FastAPIUsers(\n    get_user_db,\n    [get_jwt_strategy()],\n    UserRead,\n    UserCreate,\n    UserUpdate\n)\n\n# --- FastAPI App ---\napp = FastAPI()\n\n@app.on_event(\"startup\")\nasync def on_startup():\n    await init_beanie(\n        database=db,\n        document_models=[User]\n    )\n\napp.include_router(\n    fastapi_users.get_auth_router(get_jwt_strategy()),\n    prefix=\"/auth/jwt\",\n    tags=[\"auth\"]\n)\n\napp.include_router(\n    fastapi_users.get_register_router(UserRead, UserCreate),\n    prefix=\"/auth\",\n    tags=[\"auth\"]\n)\n\napp.include_router(\n    fastapi_users.get_users_router(UserRead, UserUpdate),\n    prefix=\"/users\",\n    tags=[\"users\"]\n)\n","lang":"python","description":"This quickstart demonstrates how to integrate `fastapi-users-db-beanie` with FastAPI Users and Beanie. It sets up a MongoDB connection, defines a `User` model inheriting from `BeanieBaseUser` and `beanie.Document`, and provides a dependency for `BeanieUserDatabase`. The FastAPI app includes authentication and user management routers, ensuring Beanie is initialized on startup."},"warnings":[{"fix":"Upgrade Python to 3.10+ and Beanie to 2.0+ before upgrading this package.","message":"Version 5.0.0 drops support for Python 3.9 and Beanie versions older than 2.0. Ensure your environment meets these requirements.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade Python to 3.10+ for compatibility with the latest versions.","message":"Versions 4.0.0 and 3.0.0 dropped support for Python 3.8 and 3.7 respectively. Older Python versions are no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your User model definition to `class User(BeanieBaseUser[PydanticObjectId], Document): ...`","message":"In version 2.0.0, `BeanieBaseUser` and `BeanieBaseAccessToken` became pure mixins and no longer automatically inherit from `beanie.Document`. You must explicitly inherit from `Document` when defining your user model. Additionally, `BeanieBaseUser` now only supports `PydanticObjectId` as the ID type.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `await init_beanie(database=db, document_models=[YourUserModel])` is called during application startup.","message":"Beanie database initialization (`init_beanie`) must occur before any database operations are attempted. This is typically done in FastAPI's `startup_event` handler or using an `async_context_manager` for the app's `lifespan`.","severity":"gotcha","affected_versions":"All"},{"fix":"While `motor` still works, be aware of potential future changes in recommended connection methods as PyMongo's native async client matures. Monitor Beanie and FastAPI Users documentation for updates.","message":"The documentation currently instructs users to use `motor.motor_asyncio.AsyncIOMotorClient` for MongoDB connections. However, `pymongo 4.16+` now includes a native asynchronous client, suggesting `motor` might eventually be replaced or become less recommended.","severity":"deprecated","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}