> ## 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.
# Neo4j Community Dataset Database Handler
> Handler for per-dataset isolation on Neo4j Community edition using one Docker container per dataset.
Make sure that `ENABLE_BACKEND_ACCESS_CONTROL` in your `.env` file is **NOT** set to `False`.
Multi-user mode is enabled by default, therefore `ENABLE_BACKEND_ACCESS_CONTROL=True` by default.
Neo4j Community edition serves exactly **one** database per running server — `CREATE DATABASE`
(used by the plain `neo4j` handler) is an Enterprise-only feature. The `neo4j_community` handler
gets around this by running **one Neo4j Community Docker container per dataset**, mirroring the
[`neo4j_aura_dev` handler](/core-concepts/multi-user-mode/dataset-database-handlers/existing-dataset-database-handlers/neo4j-aura-dev)'s
one-instance-per-dataset model with Docker in place of the Aura REST API.
Use it when you want per-dataset graph isolation on the free Neo4j edition, on a host you control.
## Requirements
This handler requires a **reachable Docker daemon** on the host running Cognee. Before provisioning
a dataset, Cognee checks that the `docker` binary is on `PATH` and that `docker info` responds; if
either check fails, dataset creation raises a `RuntimeError` explaining what is missing.
Install the Neo4j dependencies, since this handler uses the Neo4j graph database provider:
```bash theme={null}
pip install "cognee[neo4j]"
```
## Environment Variables
```dotenv theme={null}
GRAPH_DATABASE_PROVIDER="neo4j"
GRAPH_DATASET_DATABASE_HANDLER="neo4j_community"
NEO4J_ENCRYPTION_KEY=
# Optional tuning
NEO4J_COMMUNITY_MAX_CONTAINERS=6
NEO4J_COMMUNITY_IMAGE="neo4j:5-community"
NEO4J_COMMUNITY_STARTUP_TIMEOUT=120
```
| Variable | Required | Default | Description |
| --------------------------------- | ----------- | ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `GRAPH_DATABASE_PROVIDER` | Yes | — | Must be `neo4j`; the handler rejects any other provider |
| `GRAPH_DATASET_DATABASE_HANDLER` | Yes | — | Selects the `neo4j_community` dataset database handler |
| `NEO4J_ENCRYPTION_KEY` | Recommended | `test_key` | Key used to encrypt the generated per-dataset passwords at rest (same scheme as `neo4j_aura_dev`) |
| `NEO4J_COMMUNITY_MAX_CONTAINERS` | No | `DATABASE_MAX_LRU_CACHE_SIZE` (`6`) | Ceiling on **concurrently running** containers |
| `NEO4J_COMMUNITY_IMAGE` | No | `neo4j:5-community` | Docker image used for the per-dataset containers |
| `NEO4J_COMMUNITY_STARTUP_TIMEOUT` | No | `120` | Seconds to wait for a container to accept bolt connections |
**`NEO4J_ENCRYPTION_KEY`** defaults to `"test_key"` if not set. Always set a strong random key in
production to protect the per-dataset container passwords stored in Cognee's relational database.
Every running container is a full Neo4j server and consumes CPU and RAM. Tune
`NEO4J_COMMUNITY_MAX_CONTAINERS` to the concurrency your host can actually sustain — it defaults to
`DATABASE_MAX_LRU_CACHE_SIZE` so the container pool tracks the graph-engine cache capacity.
## How It Works
**When a dataset is created**, Cognee:
1. Verifies Docker is available.
2. Picks a free localhost port and runs a `neo4j:5-community` container named
`cognee-neo4j-` with a named data volume `cognee-neo4j-data-`, where
`` is the dataset's UUID **without dashes**. The bolt port is published on
`127.0.0.1` only, and stays fixed for the container's lifetime.
3. Generates a random per-dataset password, encrypts it with Fernet, and stores it together with the
container name, volume name, and host port in the `DatasetDatabase` row.
4. Waits until a Neo4j server answers a bolt protocol handshake on the published port (a plain TCP
connect is not a readiness signal — `docker-proxy` accepts connections before Neo4j listens).
Containers are labelled `ai.cognee.neo4j_community=true` and `ai.cognee.dataset_id=`, so
Cognee only ever inspects, stops, or removes containers it created itself.
**Auto-start.** Before every operation on a dataset, Cognee decrypts the credentials and starts the
container if it is stopped. Graph data lives on the named volume, so it survives container stops and
Cognee restarts.
**Auto-stop.** Container lifetime follows the graph-engine LRU cache: once a dataset's engine is
evicted and no caller holds it, the dataset is idle and its container is stopped. The next operation
on that dataset starts it again.
**Container ceiling.** Before a container starts, Cognee counts the running containers it manages
(including ones that survived a restart, found via a `docker ps` label filter) and stops
least-recently-used ones until there is room under `NEO4J_COMMUNITY_MAX_CONTAINERS`.
**Deleting a dataset is irreversible.** `delete_dataset` removes both the dataset's container **and**
its named Docker volume, so all graph data for that dataset is destroyed. Back up the volume first if
you need to keep it.
If a container is removed outside of Cognee, the next operation on that dataset fails with an error
telling you to delete and re-create the dataset so a fresh container can be provisioned. Container
startup problems are visible through `docker logs cognee-neo4j-`.
Details About Cognee's Graph Stores
More Details About Multi-User Mode