> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Dataset Database Handlers: What are they?
> How Cognee maps datasets to graph and vector storage backends
# What is a Dataset Database Handler?
Dataset Database Handlers are small, pluggable classes that define how a Cognee dataset maps to concrete storage backends for:
* **Graph databases**
* **Vector databases**
They act as the abstraction layer between a logical dataset and its physical storage.
Extensible by design: You can write custom handlers to integrate Cognee with any database and database backend (AWS, Azure, GCP, local setups and etc.) without modifying core code.
In this diagram, we can see that each dataset is mapped to its own unique Neo4j graph database instance using a Neo4j Aura Dataset Database Handler.
This connection is automatically resolved at runtime based on the authenticated user and dataset being accessed and is done when recalling, remembering, forgetting, creating, or otherwise modifying a dataset.
If you're using Cognee with `ENABLE_BACKEND_ACCESS_CONTROL` set to `False`, you don't need to configure handlers.
## How graph isolation works
Dataset Database Handlers matter specifically in multi-user mode, because that is when Cognee stops treating datasets as logical partitions inside one shared graph and starts routing each dataset to its own storage backend.
| | Single-user mode | Multi-user mode |
| ------------------------ | ---------------------------- | -------------------------------------- |
| **Graph databases** | One shared instance | One per dataset |
| **Separation mechanism** | `dataset_id` metadata filter | Physical database boundary |
| **Handler required** | No | Yes (`GRAPH_DATASET_DATABASE_HANDLER`) |
All datasets share one physical graph database. There are no hard graph-level boundaries between them. Dataset separation is tracked logically in the relational database through `dataset_id`, and queries are scoped using that metadata at runtime.
Each dataset is routed to its own dedicated physical graph database. When a dataset is first accessed, Cognee invokes the configured graph dataset database handler to provision or resolve the correct backend for that dataset. Connection metadata is stored in the relational database and resolved at query time, so each dataset's graph operations run against an isolated database instance.
## What Dataset Database Handlers Do
Handlers encapsulate all backend-specific logic required to manage dataset storage, including:
* **Provisioning or resolution** of per-dataset storage
* **Runtime connection resolution**, such as:
* Secret decryption
* Fetching short-lived credentials
* **Teardown and deletion** of per-dataset storage
Handlers are selected through configuration and registered in a central handler registry. This allows Cognee to support multiple providers and custom storage setups without modifying core pipeline code.
## Why Dataset Database Handlers Exist
Dataset Database Handlers solve several core system needs:
* **Multi-tenant isolation** — Each dataset can map to its own graph and/or vector database, enabling clean separation when backend access control is enabled.
* **Pluggability** — Providers like LanceDB, Kùzu, or Neo4j Aura can be added or swapped without changing application logic.
* **Secure secret handling** — Credentials can be resolved at connection time instead of being stored in plaintext in the relational database.
* **Lifecycle control** — All create, resolve, and delete semantics for a backend live in one well-defined place.
Cognee requires database instances provisioned via the Dataset Database Handler to be active and running. While Cognee facilitates the creation and deletion of these databases, it does not manage the operational lifecycle—such as starting or stopping containers—during its own startup or shutdown processes.
Learn about datasets as the core unit of storage in Cognee
Deep dive into configuring and using dataset database handlers