Skip to content

Graph Databases

Overview

The athomic.database.graph module provides the abstraction layer for connecting to and managing graph-oriented databases within the Athomic Layer. It allows the application to model complex relationships, such as data lineage, social networks, or impact analysis graphs, using a high-performance, asynchronous interface.

Similar to the Document Stores and Key-Value Stores modules, it follows a provider-based pattern, decoupling the application logic from the underlying graph technology.

Core Concepts

GraphDatabaseProtocol

This is the abstract contract that all graph database providers must implement. It defines the standard interface for executing queries (e.g., Cypher) and managing the connection lifecycle.

GraphManager

The GraphManager is the orchestrator for graph connections. It is responsible for: - Multi-Tenancy: Managing multiple named connections (e.g., default, analytics, fraud_detection) defined in the configuration. - Lifecycle: Ensuring that all configured graph drivers are connected at startup and gracefully closed at shutdown. - Registry: Providing access to specific client instances via get_client("connection_name").

Neo4jProvider

This is the primary, production-ready provider implementation. It wraps the official Neo4j Python Driver (Async), adding critical enterprise features: - Observability: Automatically wraps queries with OpenTelemetry tracing spans and Prometheus metrics. - Resilience: Manages connection pooling and retry logic for transient network errors. - Security: Integrates with the Credentials module to resolve database passwords securely at runtime.

How It Works

  1. Configuration: You define your graph connections in settings.toml under the [database.graph] section.
  2. Initialization: At application startup, the central ConnectionManager initializes the GraphManager.
  3. Factory Creation: The GraphManager uses the GraphDatabaseFactory to instantiate the configured backend (e.g., Neo4jProvider) for each defined connection.
  4. Usage: Services inject the GraphDatabaseProtocol via the connection manager to execute queries without knowing the implementation details.

Usage Example

Basic Query Execution

To interact with the graph database, retrieve the client from the connection manager and use the execute_query method.

from nala.athomic.database.factory import connection_manager_factory

async def get_service_dependencies(service_name: str):
    # 1. Get the connection manager (Singleton)
    manager = connection_manager_factory.create()

    # 2. Get the default graph client
    # You can also pass a specific name: manager.get_graph_db("analytics")
    graph_db = manager.get_graph_db() 

    # 3. Define a Cypher query
    query = """
    MATCH (s:Service {name: $name})-[:CALLS]->(target:Service)
    RETURN target.name as dependency, target.version as version
    """

    # 4. Execute asynchronously
    # The provider handles the session management automatically
    results = await graph_db.execute_query(
        query, 
        parameters={"name": service_name}
    )

    return [record["dependency"] for record in results]

Configuration

Graph connections are configured using the standard Connection Group pattern found in settings.toml.

[default.database.graph]
# The name of the default connection to return when none is specified.
default_connection_name = "default_graph"

  # --- Connection 1: The main application graph ---
  [default.database.graph.connections.default_graph]
  enabled = true
  backend = "neo4j"

    [default.database.graph.connections.default_graph.provider]
    backend = "neo4j"
    # Connection URI (supports bolt://, neo4j://, neo4j+s://)
    uri = "bolt://localhost:7687"
    user = "neo4j"
    # Secure password reference via the Secrets module
    password = { path = "database/neo4j", key = "password" } # pragma: allowlist secret

    # Connection pool tuning
    max_connection_pool_size = 50
    max_connection_lifetime = 3600

  # --- Connection 2: A separate analytics graph ---
  [default.database.graph.connections.analytics_graph]
  enabled = true
  backend = "neo4j"
    [default.database.graph.connections.analytics_graph.provider]
    backend = "neo4j"
    uri = "neo4j+s://analytics-cluster.graph.io:7687"
    user = "analytics_svc"
    password = { path = "database/neo4j-analytics", key = "password" } # pragma: allowlist secret

API Reference

nala.athomic.database.graph.protocol.GraphDatabaseProtocol

Bases: BaseServiceProtocol, Protocol

Defines the contract for a Graph Database provider. This ensures the application is decoupled from specific graph technology drivers.

get_driver() async

Returns the underlying native driver instance.

run_query(query, parameters=None) async

Executes a Cypher (or equivalent) query and returns a list of records.

Parameters:

Name Type Description Default
query str

The query string.

 required
parameters Optional[Dict[str, Any]]

Dictionary of parameters to bind to the query.

 None

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries representing the result records.

nala.athomic.database.graph.manager.GraphManager

Bases: BaseManager[GraphDatabaseProtocol, GraphSettings]

A specialized lifecycle manager for Graph Database connections.

This class orchestrates the initialization, connection, and shutdown of multiple graph database providers (e.g., 'default', 'analytics'). It acts as the single point of access for retrieving specific graph clients within the application.

It inherits robust lifecycle management from BaseManager, ensuring that all configured graph connections are established during startup and gracefully closed during shutdown.

__init__(settings)

Initializes the GraphManager.

Parameters:

Name Type Description Default
settings DatabaseSettings

The root database settings object containing the 'graph' connection group configuration.

 required

nala.athomic.database.graph.providers.neo4j.Neo4jProvider

Bases: GraphDatabaseBase, CredentialResolve

Concrete implementation of the GraphDatabaseProtocol for Neo4j.

__init__(settings)

Initializes the Neo4jProvider instance.

Parameters:

Name Type Description Default
settings GraphSettings

The root database settings object containing the 'graph' connection group configuration.

 required

nala.athomic.database.graph.factory.GraphDatabaseFactory

Factory for creating GraphDatabaseProtocol instances.

create(settings=None) classmethod

Creates a graph provider instance.

If 'settings' is NOT provided, it resolves the DEFAULT connection from the global AppSettings (ConnectionGroupSettings).