# LightRAG Storage Backends: Complete Guide to KV, Vector, Graph, and Doc Status

> Explore LightRAG storage backends for KV, vector, graph, and doc status. Discover 24 production-ready options including JSON, Redis, PostgreSQL, MongoDB, Neo4j, and OpenSearch.

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

---

**LightRAG supports 24 production-ready storage backends across four persistence layers—key-value, vector, graph, and document-status data—utilizing a plug-in architecture that enables mixing JSON files, Redis, PostgreSQL, MongoDB, Neo4j, OpenSearch, and other databases.**

The HKUDS/LightRAG repository decouples data persistence from retrieval logic through abstract base classes defined in [`lightrag/base.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/base.py). This modular design allows developers to configure independent storage backends for each layer, swapping file-based solutions for enterprise databases as deployment requirements evolve.

## KV Storage Backends

LightRAG provides five concrete implementations for key-value storage, handling raw text chunks, LLM cache, and entity data:

- **`JsonKVStorage`** – File-based JSON persistence located in [`lightrag/kg/json_kv_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/json_kv_impl.py) (line 27)
- **`RedisKVStorage`** – Redis hash store implemented in [`lightrag/kg/redis_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/redis_impl.py) (line 127)
- **`PGKVStorage`** – PostgreSQL table storage in [`lightrag/kg/postgres_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/postgres_impl.py) (line 1939)
- **`OpenSearchKVStorage`** – OpenSearch document store in [`lightrag/kg/opensearch_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/opensearch_impl.py) (line 179)
- **`MongoKVStorage`** – MongoDB collection storage in [`lightrag/kg/mongo_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/mongo_impl.py) (line 81)

All KV backends inherit from `BaseKVStorage` and implement standardized methods including `get_by_id`, `upsert`, and `delete`.

## Vector Storage Backends

Eight backends support embedding vector persistence for similarity search, ranging from local file indices to distributed vector databases:

- **`FaissVectorDBStorage`** – Faiss index on disk in [`lightrag/kg/faiss_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/faiss_impl.py) (line 24)
- **`QdrantVectorDBStorage`** – Qdrant service integration in [`lightrag/kg/qdrant_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/qdrant_impl.py) (line 119)
- **`PGVectorStorage`** – PostgreSQL `vector` type extension in [`lightrag/kg/postgres_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/postgres_impl.py) (line 2469)
- **`OpenSearchVectorDBStorage`** – OpenSearch k-NN plugin in [`lightrag/kg/opensearch_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/opensearch_impl.py) (line 2322)
- **`NanoVectorDBStorage`** – NanoVectorDB implementation in [`lightrag/kg/nano_vector_db_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/nano_vector_db_impl.py) (line 26)
- **`MongoVectorDBStorage`** – MongoDB Atlas Vector Search in [`lightrag/kg/mongo_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/mongo_impl.py) (line 2040)
- **`MilvusVectorDBStorage`** – Milvus service integration in [`lightrag/kg/milvus_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/milvus_impl.py) (line 332)
- **`ChromaVectorDBStorage`** – *Deprecated* Chroma DB in [`lightrag/kg/deprecated/chroma_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/deprecated/chroma_impl.py) (line 20)

These classes extend `BaseVectorStorage` and provide `query` methods for approximate nearest neighbor search.

## Graph Storage Backends

Six graph storage implementations manage knowledge-graph nodes and edges using undirected graph structures:

- **`NetworkXStorage`** – In-process NetworkX graphs in [`lightrag/kg/networkx_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/networkx_impl.py) (line 26)
- **`PGGraphStorage`** – PostgreSQL table-based graphs in [`lightrag/kg/postgres_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/postgres_impl.py) (line 4004)
- **`OpenSearchGraphStorage`** – OpenSearch k-NN plus document graphs in [`lightrag/kg/opensearch_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/opensearch_impl.py) (line 947)
- **`Neo4JStorage`** – Neo4j database integration in [`lightrag/kg/neo4j_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py) (line 66)
- **`MongoGraphStorage`** – MongoDB collection storage in [`lightrag/kg/mongo_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/mongo_impl.py) (line 728)
- **`MemgraphStorage`** – Memgraph database connector in [`lightrag/kg/memgraph_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/memgraph_impl.py) (line 35)

Graph backends inherit from `BaseGraphStorage` and expose methods for node insertion, edge creation, and graph traversal.

## Document Status Storage Backends

Five backends track per-document processing state, including chunk lists, metadata, and pipeline status:

- **`JsonDocStatusStorage`** – JSON file persistence in [`lightrag/kg/json_doc_status_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/json_doc_status_impl.py) (line 30)
- **`RedisDocStatusStorage`** – Redis storage in [`lightrag/kg/redis_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/redis_impl.py) (line 518)
- **`PGDocStatusStorage`** – PostgreSQL tables in [`lightrag/kg/postgres_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/postgres_impl.py) (line 3354)
- **`OpenSearchDocStatusStorage`** – OpenSearch documents in [`lightrag/kg/opensearch_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/opensearch_impl.py) (line 470)
- **`MongoDocStatusStorage`** – MongoDB collections in [`lightrag/kg/mongo_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/mongo_impl.py) (line 285)

These extend `DocStatusStorage` and maintain processing state across document ingestion pipelines.

## How to Initialize Storage Backends

Instantiate any storage class by importing from its implementation module and passing the standard constructor arguments defined in the base classes:

```python
from lightrag.kg.json_kv_impl import JsonKVStorage
from lightrag.kg.faiss_impl import FaissVectorDBStorage
from lightrag.kg.networkx_impl import NetworkXStorage
from lightrag.kg.json_doc_status_impl import JsonDocStatusStorage

# Initialize JSON-backed KV storage

kv = JsonKVStorage(
    namespace="text_chunks",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

# Initialize Faiss vector storage

vector = FaissVectorDBStorage(
    namespace="text_chunks",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

# Initialize NetworkX graph storage

graph = NetworkXStorage(
    namespace="knowledge_graph",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

# Initialize JSON document status storage

doc_status = JsonDocStatusStorage(
    namespace="doc_status",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

```

To switch backends, change only the imported class while maintaining identical initialization parameters. For example, replacing `JsonKVStorage` with `RedisKVStorage` requires updating the import statement and class name:

```python
from lightrag.kg.redis_impl import RedisKVStorage

kv = RedisKVStorage(
    namespace="text_chunks",
    embedding_func=my_embed,
    global_config={"working_dir": "./data"},
    workspace="my_project",
)

```

All storage classes share common interface methods including `is_empty`, `upsert`, and `get_by_id`, enabling seamless backend substitution without modifying pipeline logic.

## Summary

- LightRAG provides **24 production-ready storage backends** across four persistence layers: KV (5), Vector (8), Graph (6), and Document Status (5)
- Each backend implements standardized interfaces (`BaseKVStorage`, `BaseVectorStorage`, `BaseGraphStorage`, `DocStatusStorage`) defined in [`lightrag/base.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/base.py)
- Database-specific implementations reside in `lightrag/kg/` with dedicated modules for PostgreSQL, MongoDB, Redis, Neo4j, OpenSearch, Memgraph, Milvus, Qdrant, and others
- Constructor signatures are uniform across all backends, allowing drop-in replacement by changing only the import statement and class name
- **`ChromaVectorDBStorage`** is deprecated and located in [`lightrag/kg/deprecated/chroma_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/deprecated/chroma_impl.py) (line 20); new implementations should use `FaissVectorDBStorage` or database-backed alternatives

## Frequently Asked Questions

### Can I use different database backends for different storage layers in LightRAG?

Yes. LightRAG's modular architecture allows mixing storage technologies according to your operational needs. For example, you can configure `RedisKVStorage` for key-value data, `MilvusVectorDBStorage` for vectors, `Neo4JStorage` for graphs, and `JsonDocStatusStorage` for document status within the same pipeline instance.

### Which storage backend offers the best performance for large-scale deployments?

**PostgreSQL** (via `PGKVStorage`, `PGVectorStorage`, `PGGraphStorage`, and `PGDocStatusStorage`) and **Neo4j** (via `Neo4JStorage`) provide the strongest consistency and query performance for high-volume transactional workloads. For specialized vector search throughput, **Milvus** or **Qdrant** typically outperform file-based alternatives in distributed environments.

### How do I migrate from file-based storage to PostgreSQL?

Migration requires changing import statements from file-based implementations (e.g., `JsonKVStorage`) to PostgreSQL equivalents (e.g., `PGKVStorage`) while maintaining the same constructor arguments. You must ensure your `global_config` includes PostgreSQL connection parameters. The data itself requires manual migration or re-ingestion, as storage implementations do not provide automatic data transfer between backend types.

### Is the Chroma vector storage still supported?

**`ChromaVectorDBStorage`** is deprecated and remains available only in [`lightrag/kg/deprecated/chroma_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/deprecated/chroma_impl.py) at line 20 for backward compatibility. It is not recommended for new projects. Migrate to `FaissVectorDBStorage` for local file-based vector storage, or to `PGVectorStorage` or `QdrantVectorDBStorage` for production database solutions.