# How to Configure LightRAG with Neo4j for Production Knowledge Graph Storage

> Learn to configure LightRAG with Neo4j for production knowledge graph storage. Discover automatic connection pooling, isolation, indexing, and full-text search. For HKUDS/LightRAG users.

- Repository: [✨Data Intelligence Lab@HKU✨/LightRAG](https://github.com/HKUDS/LightRAG)
- Tags: how-to-guide
- Published: 2026-03-23

---

**LightRAG provides a production-ready Neo4j backend via `Neo4JStorage` that automatically handles connection pooling, workspace isolation, B-tree indexing, and full-text search with automatic retries on transient errors.**

The HKUDS/LightRAG repository ships with a native Neo4j storage implementation (`Neo4JStorage`) that persists knowledge graphs to Neo4j instead of memory. When you configure LightRAG with Neo4j, the storage layer manages schema creation, connection resilience, and multi-tenant isolation through environment variables or configuration files. This guide walks through deploying Neo4j, initializing the storage layer, and executing CRUD operations using the actual source implementation found in [`lightrag/kg/neo4j_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py).

## Deploy a Neo4j Instance

LightRAG supports any Neo4j 5.x deployment. Choose the topology that matches your operational requirements:

- **Docker (Community or Enterprise)**. Run locally for development or mount persistent volumes for single-node production:

```bash
docker run -d --name neo4j \
  -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/securepassword \
  -v /data/neo4j:/data \
  neo4j:5

```

- **Neo4j Aura**. Use the managed SaaS offering for automatic backups and TLS. Obtain the Bolt URI, username, and password from the Aura console, then set `NEO4J_URI=neo4j+s://your-id.databases.neo4j.io`.

- **Self-hosted Enterprise**. Install via official packages or Helm charts. Enable mandatory TLS with `dbms.connector.bolt.tls_level=REQUIRED` and configure `NEO4J_DATABASE` for multi-database isolation.

## Install the Neo4j Driver

LightRAG installs the official `neo4j` Python driver automatically via `pipmaster` when the storage class is first instantiated. The import is guarded in [`lightrag/kg/neo4j_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py) (lines 22-30), meaning you do not need to manually add the package to your requirements. The driver becomes available immediately upon calling `Neo4JStorage`.

## Configure Environment Variables

The `Neo4JStorage` class reads configuration from environment variables using `dotenv` (lines 34-38 in [`lightrag/kg/neo4j_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py)). Create a `.env` file in your project root with the following variables:

| Variable | Example | Purpose |
|----------|---------|---------|
| `NEO4J_URI` | `bolt://localhost:7687` | Bolt protocol endpoint. |
| `NEO4J_USERNAME` | `neo4j` | Authentication user. |
| `NEO4J_PASSWORD` | `securepassword` | Authentication password. |
| `NEO4J_WORKSPACE` | `production` | Logical workspace label for multi-tenant isolation. |
| `NEO4J_MAX_CONNECTION_POOL_SIZE` | `200` | Driver connection pool for concurrent workloads. |
| `NEO4J_DATABASE` | `knowledgegraph` | Target database name (Enterprise only). |
| `NEO4J_MAX_TRANSACTION_RETRY_TIME` | `30` | Seconds to retry transient failures. |

**Sample `.env` configuration:**

```dotenv
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=verysecret
NEO4J_WORKSPACE=production
NEO4J_MAX_CONNECTION_POOL_SIZE=200
NEO4J_KEEP_ALIVE=true

```

## Initialize Neo4JStorage

Instantiate the storage class with a namespace and embedding function, then call `initialize()` to provision indexes and verify connectivity:

```python
from lightrag.kg.neo4j_impl import Neo4JStorage

kg_storage = Neo4JStorage(
    namespace="myapp",
    global_config={"max_graph_nodes": 2000},
    embedding_func=my_embedder,
)

await kg_storage.initialize()

```

The `initialize()` method performs three critical setup tasks defined in [`lightrag/kg/neo4j_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py):

1. **Workspace Labeling**. Sanitizes the `NEO4J_WORKSPACE` value (or defaults to `base`) to create an isolated label namespace (lines 93-106).
2. **B-Tree Index**. Creates a B-tree index on `entity_id` for O(log n) lookups (lines 66-73).
3. **Full-Text Index**. Provisions a full-text index named `entity_id_fulltext_idx_<workspace>` with CJK analyzer support when available (lines 87-115).

If index creation fails (for example, on unsupported Neo4j editions), LightRAG logs a warning and falls back to unindexed queries rather than crashing.

## Upsert Nodes and Edges

### Upsert a Node

Use `upsert_node` to merge entities into the graph. The method sanitizes `entity_type` and applies the workspace label automatically (lines 30-55):

```python
await kg_storage.upsert_node(
    node_id="doc:12345",
    node_data={
        "entity_id": "doc:12345",
        "entity_type": "Document",
        "title": "Production Configuration Guide",
        "text": "Full article text...",
        "embedding": await my_embedder("Full article text...")
    },
)

```

### Upsert an Edge

The `upsert_edge` method creates a directed relationship between two nodes, ensuring both endpoints exist before writing (lines 100-120):

```python
await kg_storage.upsert_edge(
    source_node_id="doc:12345",
    target_node_id="topic:Neo4j",
    edge_data={"weight": 1.0, "description": "covers"}
)

```

Both operations are wrapped in `tenacity` retry decorators that handle transient Neo4j errors such as `ServiceUnavailable` and connection resets (lines 56-62, 119-133).

## Query the Knowledge Graph

LightRAG exposes async read methods optimized for production use:

- **`has_node(node_id)`**. Returns `True` if the entity exists, utilizing the B-tree index for constant-time existence checks.
- **`get_node(node_id)`**. Retrieves node properties with workspace labels stripped for clean application logic.
- **`get_knowledge_graph(node_label, max_depth, max_nodes)`**. Returns a subgraph structure suitable for LLM reasoning, automatically truncating results when limits are exceeded.

All read methods use the `@READ_RETRY` decorator to mitigate transient read failures.

## Production Optimization

Enable these configurations for high-availability deployments:

1. **Enable TLS**. Set `dbms.connector.bolt.tls_level=REQUIRED` in Neo4j and use `NEO4J_URI=neo4j+s://host:7687` for encrypted connections.
2. **Tune Connection Pools**. Set `NEO4J_MAX_CONNECTION_POOL_SIZE` to match your application's concurrent request volume (default is typically 100).
3. **Use Enterprise Database Isolation**. Set `NEO4J_DATABASE` to a dedicated database name for resource quotas and backup isolation.
4. **Monitor Index Health**. Check logs during initialization for warnings about unsupported index operations. Re-run `initialize()` after upgrading Neo4j versions to migrate indexes.

## Summary

- **Environment variables** drive all Neo4j connectivity; place them in `.env` or export directly.
- **`Neo4JStorage.initialize()`** provisions B-tree and full-text indexes automatically and establishes the workspace label for multi-tenancy.
- **`upsert_node` and `upsert_edge`** handle entity sanitization and relationship creation with automatic retry logic on transient failures.
- **Workspace labels** (controlled via `NEO4J_WORKSPACE`) allow multiple LightRAG instances to share a single Neo4j cluster safely.
- **Retry decorators** on all I/O operations ensure resilience against network instability or brief Neo4j unavailability.

## Frequently Asked Questions

### Does LightRAG support Neo4j Aura?

Yes. Configure `NEO4J_URI` with the `neo4j+s://` scheme provided by Aura, set `NEO4J_USERNAME` and `NEO4J_PASSWORD` to your Aura credentials, and omit `NEO4J_DATABASE` unless using an Enterprise Aura instance. The driver automatically handles TLS certificate verification.

### How does LightRAG handle transient connection failures?

All CRUD operations in [`lightrag/kg/neo4j_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py) are decorated with `tenacity` retry policies (lines 56-62 and 119-133) that catch `ServiceUnavailable`, `TransientError`, and connection resets. The driver retries with exponential backoff up to the limit specified in `NEO4J_MAX_TRANSACTION_RETRY_TIME` (default 30 seconds).

### Can multiple LightRAG applications share one Neo4j database?

Yes. Set a unique `NEO4J_WORKSPACE` value for each application. The storage layer prepends this workspace string to all node labels (lines 93-106), effectively isolating graphs within the same physical database. For stricter isolation, use Neo4j Enterprise and specify different `NEO4J_DATABASE` values.

### What indexes does LightRAG create automatically?

During initialization, LightRAG attempts to create two indexes: a **B-tree index** on the `entity_id` property for exact lookups (lines 66-73) and a **full-text index** named `entity_id_fulltext_idx_<workspace>` with CJK analyzer support for semantic search (lines 87-115). If the Neo4j edition lacks index administration privileges, LightRAG logs a warning and continues operation without indexes.