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

> Easily switch graph database providers Neo4j Kuzu Neptune in Cognee by updating GraphConfig. Learn how to seamlessly migrate your graph operations.

- Repository: [Topoteretes/cognee](https://github.com/topoteretes/cognee)
- Tags: how-to-guide
- Published: 2026-03-16

---

**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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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:

```python
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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/cognee/cli/commands/config_command.py):

```bash

# 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:

```dotenv

# .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:

```python
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:

```python
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:

```python
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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/get_graph_engine.py). Create a new adapter class implementing `GraphDBInterface` from [`graph_db_interface.py`](https://github.com/topoteretes/cognee/blob/main/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.