Skip to content

Conversation

@A-K-6
Copy link

@A-K-6 A-K-6 commented Jan 1, 2026

Problem Statement

Managing multiple MongoDB databases and their associated Beanie models often requires significant boilerplate code to handle connections, migrations, and initialization for each database individually.

Solution: ODMClient

This PR introduces the ODMClient, a high-level utility class that centralizes and simplifies the lifecycle of Beanie applications.

Key Features

  • Batch Initialization: Use init_db with a configuration dictionary to initialize multiple databases and models in one call.
  • Centralized Connection Management: Uses AsyncMongoClient internally and supports async context manager usage (async with ODMClient(...) as client:).
  • Integrated Migrations: Automatically handles migrations during database registration with a built-in lock for safety.
  • Full Feature Support: Passes through all standard Beanie init parameters (allow_index_dropping, recreate_views, skip_indexes).
  • Improved Documentation: Includes a new tutorial and automated API documentation generation.

Examples

from beanie import ODMClient, Document

class User(Document): ...
class Product(Document): ...

db_config = {
    "user_db": [User],
    "product_db": [Product]
}

async with ODMClient("mongodb://localhost:27017") as client:
    await client.init_db(db_config, migrations_path="path/to/migrations")

Checklist

  • Code implementation of ODMClient (beanie/odm/client.py)
  • Comprehensive tests in tests/odm/test_client.py
  • Documentation added in docs/odm-client.md
  • mkdocs.yml / pydoc-markdown.yml updated for navigation
  • Tests for ODMClient passing locally

A-K-6 added 4 commits January 1, 2026 14:55
Introduces a new `ODMClient` class in `beanie.odm.client` to simplify
asynchronous MongoDB connection management and database initialization.

Key changes:
- Implements `ODMClient` with support for multiple database registrations.
- Integrates Beanie initialization and migration execution within the client.
- Adds support for async context management (`__aenter__`/`__aexit__`) to ensure proper connection handling.
- Exports `ODMClient` in the main `beanie` package.
- Includes initial test suite for the new client functionality.
The `ODMClient.init_db` and `register_database` methods now support `allow_index_dropping`, `recreate_views`, and `skip_indexes` parameters. These are passed directly to Beanie's `init_beanie` to provide finer control over database initialization.

Additionally, a documentation note and a corresponding test case were added to clarify that Beanie binds models globally, meaning the last database registered for a specific model class will prevail.
Introduces a new tutorial document for the `ODMClient` utility. The guide covers:
- Initialization with MongoDB URIs
- Registering single and multiple databases
- Handling database migrations
- Using the client as an async context manager
- Important notes regarding global model binding in Beanie
Update the pydoc-markdown configuration to include the new ODM Client tutorial and API reference.

- Added "ODM Client" to the tutorial navigation pointing to docs/tutorial/odm-client.md.
- Added a "Client" section to the API documentation covering the beanie.odm.client module.

These changes ensure that new client-related documentation is correctly indexed and rendered in the documentation site.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant