Skip to content

Document Stores

Overview

The athomic.database.documents module provides the abstraction layer for connecting to and managing document-oriented databases within the Athomic Layer. It follows a provider-based pattern, allowing different backends like MongoDB to be used interchangeably without affecting the services that depend on them.

The primary responsibility of this module is to provide a lifecycle-managed, ready-to-use database client instance that can be passed to data repositories or Object-Document Mappers (ODMs) like Beanie.

How It Works

The components of this module are designed to work together seamlessly with the central ConnectionManager:

  1. Configuration: In your settings.toml, you define one or more connections under [database.documents]. Each connection specifies a backend (e.g., "mongo").
  2. Factory Creation: The ConnectionManager calls the DocumentsDatabaseFactory for each configured connection.
  3. Registry Lookup: The factory uses the backend name to look up the corresponding provider class (e.g., MongoProvider) in the DocumentDatabaseRegistry.
  4. Instantiation: The factory instantiates the provider class with its specific configuration.
  5. Lifecycle Management: The ConnectionManager then manages the start and stop lifecycle of the created provider instance.

All providers must adhere to the DocumentsDatabaseProtocol, which guarantees a consistent interface for obtaining the native database client.

Available Providers

MongoProvider

This is the primary, production-ready provider for connecting to a MongoDB server or replica set. It is built on top of the official asynchronous driver motor. The provider handles: - Securely resolving the connection URI. - Establishing the connection and verifying it with a ping command. - Providing the native AsyncIOMotorDatabase object that can be used directly by libraries like Beanie.

LocalDBProvider

A simple, in-memory provider designed for testing and development. It simulates the connection lifecycle (start, stop, wait_ready) without requiring any external database dependencies. This is extremely useful for fast and isolated unit tests.

Configuration

Below is an example of how to configure a MongoDB connection in your settings.toml. You can define multiple connections with different names (e.g., default_mongo, logs_mongo).

[default.database.documents.default_mongo]
# Enables or disables this specific document database connection.
enabled = true

# The name of the backend. This is the key used in the registry.
backend = "mongo"

  # Provider-specific settings, validated by a Pydantic model.
  [default.database.documents.default_mongo.provider]
  # The connection URI for the MongoDB instance.
  # This can be a direct value or a secret reference.
  url = "mongodb://user:pass@localhost:27017" # pragma: allowlist secret

  # The name of the database to use.
  database_name = "main_app_db"

API Reference

nala.athomic.database.documents.protocol.DocumentsDatabaseProtocol

Bases: BaseServiceProtocol, Protocol

Protocol for a document database provider.

Defines the contract for managing a database connection and providing access to the native database instance (e.g., a Motor/Beanie database object). It inherits from ConnectionServiceProtocol to be managed by the application's lifecycle.

get_database() async

Returns the native database instance required by repositories to perform operations.

nala.athomic.database.documents.factory.DocumentsDatabaseFactory

Factory responsible for creating a singleton instance of the configured document database provider.

create(settings) classmethod

Creates and returns a singleton instance of the document database provider.

nala.athomic.database.documents.providers.mongo_provider.MongoProvider

Bases: DocumentsDatabaseBase, CredentialResolve

A Document Database Provider implementation for MongoDB.

This class manages the connection lifecycle, state, and client access for a MongoDB instance using the asynchronous motor.motor_asyncio library. It integrates credential resolution to securely handle the connection URI. It inherits all core lifecycle and state management logic from DocumentsDatabaseBase.

Attributes:

Name Type Description
settings MongoSettings

The MongoDB-specific configuration settings.
client AsyncIOMotorClient | None

The underlying Motor client instance.
_db AsyncIOMotorDatabase | None

The active database instance.

__init__(settings=None)

Initializes the MongoProvider.

Parameters:

Name Type Description Default
settings Optional[DocumentsSettings]

The document database configuration settings.

 None