How to Switch Between Graph Database Providers in Cognee: Neo4j, Kuzu, and Neptune

You can switch between graph database providers in Cognee by updating the graph_database_provider setting in the global GraphConfig, which triggers a factory pattern to instantiate the appropriate adapter (Neo4j, Kuzu, Neptune, etc.) on the next graph operation.

Cognee abstracts graph storage behind a provider-based architecture that allows seamless swapping between local and cloud databases without changing your application code. Whether you need the embedded performance of Kuzu, the enterprise features of Neo4j, or the managed scalability of AWS Neptune, switching providers requires only a configuration change. This guide explains the architecture and provides practical examples for switching between graph database providers in Cognee using Python, CLI, or environment variables.

Understanding the Provider Architecture

The provider system in Cognee follows a clean separation between configuration and implementation. When you request a graph operation, the system resolves the current provider setting through a factory pattern that returns the appropriate adapter implementing the common GraphDBInterface.

The GraphConfig Model

All provider settings originate in cognee/infrastructure/databases/graph/config.py, which defines the GraphConfig Pydantic model. This model stores the graph_database_provider field (defaulting to "kuzu") and automatically reads from environment variables using SettingsConfigDict(env_file=".env", ...).

The Factory Pattern in get_graph_engine

When your code calls get_graph_engine(), the system executes a three-step resolution process defined in cognee/infrastructure/databases/graph/get_graph_engine.py:

1. Configuration retrieval: get_graph_engine() retrieves the current GraphConfig instance respecting async context.
2. Factory dispatch: _create_graph_engine() contains a mapping dictionary that associates provider strings with concrete adapter classes.
3. Adapter instantiation: The factory creates and caches the appropriate adapter (Neo4jAdapter, KuzuAdapter, RemoteKuzuAdapter, NeptuneGraphDB, or NeptuneAnalyticsAdapter).

All adapters implement GraphDBInterface from cognee/infrastructure/databases/graph/graph_db_interface.py, ensuring transparent operation across the codebase.

Supported Graph Database Providers

Cognee currently supports five provider configurations, each requiring specific connection parameters:

• neo4j: Requires graph_database_url (bolt:// endpoint); optionally accepts graph_database_username and graph_database_password. Uses Neo4jAdapter.
• kuzu: Default provider. Requires graph_file_path for local storage. Uses KuzuAdapter.
• kuzu-remote: Requires graph_database_url for remote Kuzu instances. Uses RemoteKuzuAdapter.
• neptune: Requires Neptune endpoint URL. Uses NeptuneGraphDB.
• neptune_analytics: Requires Neptune Analytics endpoint URL. Uses NeptuneAnalyticsAdapter.

If required parameters are missing, _create_graph_engine raises an EnvironmentError with specific details about the missing configuration, preventing runtime failures.

Methods to Switch Providers

You can change the graph database provider through three interfaces: the Python API, the CLI, or environment variables. All methods update the same underlying GraphConfig singleton.

Programmatic Configuration (Python API)

The most direct method uses cognee.config.set_graph_database_provider() to switch providers at runtime:

import cognee

# Switch to Neo4j

cognee.config.set_graph_database_provider("neo4j")
cognee.config.graph_database_url = "bolt://localhost:7687"
cognee.config.graph_database_username = "neo4j"
cognee.config.graph_database_password = "secret"

# The next graph operation will use Neo4jAdapter

engine = await cognee.get_graph_engine()

The cognee.config object proxies the GraphConfig model, so any field defined in config.py can be overridden programmatically.

Command Line Interface (CLI)

For DevOps workflows and containerized deployments, use the CLI commands defined in cognee/cli/commands/config_command.py:

# Check current configuration

cognee config get

# Switch to Kuzu (local file-based)

cognee config set graph_database_provider kuzu

# Configure Neptune Analytics

cognee config set graph_database_provider neptune_analytics
cognee config set graph_database_url https://your-neptune-endpoint.amazonaws.com/graph-id

Environment Variables

For Docker deployments or CI/CD pipelines, set the GRAPH_DATABASE_PROVIDER environment variable. The GraphConfig model automatically loads these values on initialization:

# .env file

GRAPH_DATABASE_PROVIDER=neo4j
GRAPH_DATABASE_URL=bolt://neo4j:7687
GRAPH_DATABASE_USERNAME=neo4j
GRAPH_DATABASE_PASSWORD=secret

Place the .env file at your project root, and Cognee will populate the configuration fields automatically without code changes.

Complete Code Examples

Switching from Kuzu to Neo4j

This example demonstrates migrating from the default Kuzu provider to Neo4j, including proper async initialization:

import asyncio
import cognee
from cognee import config, get_graph_engine

async def setup_neo4j():
    # Switch provider

    config.set_graph_database_provider("neo4j")
    config.graph_database_url = "bolt://localhost:7687"
    config.graph_database_username = "neo4j"
    config.graph_database_password = "secret"
    
    # Factory creates Neo4jAdapter

    engine = await get_graph_engine()
    
    # Use the common interface

    await engine.add_node({"id": "article_1", "type": "Article"})
    print(f"Connected to {type(engine).__name__}")

asyncio.run(setup_neo4j())

Using Kuzu (Default Configuration)

When using Kuzu, no explicit configuration is required unless you need a custom file path:

import cognee

# Kuzu is the default (graph_database_provider: "kuzu")

engine = await cognee.get_graph_engine()

# Operations automatically use local Kuzu storage

await engine.add_node({"id": "node1", "type": "Document"})

Configuring AWS Neptune Analytics

For cloud deployments, switch to the Neptune Analytics provider:

import cognee
from cognee import config

config.set_graph_database_provider("neptune_analytics")
config.graph_database_url = "https://your-graph-id.us-east-1.neptune.amazonaws.com"

engine = await cognee.get_graph_engine()

# Engine is now NeptuneAnalyticsAdapter

Validation and Error Handling

The factory in cognee/infrastructure/databases/graph/get_graph_engine.py (lines 95-127) validates provider configuration before instantiation. If you select neo4j without setting graph_database_url, or choose kuzu without graph_file_path, the system raises an EnvironmentError immediately rather than failing during graph operations.

This early validation ensures that provider switches are atomic and safe, with clear error messages indicating exactly which configuration key is missing.

Summary

• Provider abstraction: Cognee uses a factory pattern in get_graph_engine.py to map provider strings to concrete adapters implementing GraphDBInterface.
• Configuration sources: Set graph_database_provider via cognee.config.set_graph_database_provider(), CLI (cognee config set), or the GRAPH_DATABASE_PROVIDER environment variable.
• Supported providers: Choose from neo4j, kuzu, kuzu-remote, neptune, and neptune_analytics, each with specific connection requirements.
• Default behavior: Kuzu is the default provider, requiring no configuration for local development.
• Safety: Missing required parameters trigger EnvironmentError with specific details about the configuration gap.

Frequently Asked Questions

What is the default graph database provider in Cognee?

The default provider is Kuzu ("kuzu"), defined in the GraphConfig model in cognee/infrastructure/databases/graph/config.py. This embedded, file-based graph database requires no external dependencies, making it ideal for local development and testing.

Can I switch graph database providers at runtime without restarting my application?

Yes. Calling cognee.config.set_graph_database_provider() updates the global configuration singleton immediately. The next call to get_graph_engine() will instantiate the new adapter based on the updated settings. However, existing graph engine instances cached from previous calls may need to be refreshed depending on your async context scope.

Why does Cognee raise an EnvironmentError when I switch to Neo4j?

The EnvironmentError occurs in _create_graph_engine when required connection parameters are missing. For Neo4j, you must set graph_database_url (the bolt:// endpoint). The error message specifies exactly which configuration key is absent, allowing you to diagnose whether the issue is in your Python code, CLI command, or environment variables.

How do I add support for a custom graph database provider?

You can extend the factory by modifying the supported_databases mapping in cognee/infrastructure/databases/graph/get_graph_engine.py. Create a new adapter class implementing GraphDBInterface from graph_db_interface.py, then add your provider string and class to the factory dictionary. Your adapter will then be selectable via the standard configuration methods.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}