> ## 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 Aura Dataset Database Handler

> Handler for connecting to a Neo4j database, enabling multi-user mode on a Neo4j database instance hosted on their cloud, Neo4j Aura.

<Warning>
  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.
</Warning>

The Neo4j adapter is one of Cognee's core graph adapters, along with Kuzu. Multi-user mode, however,
is only enabled via the Neo4j Aura Cloud with this handler. You can read more about Aura in the official
[Neo4j Aura docs](https://neo4j.com/docs/aura/).

## Local vs. Cloud Storage

By default, Cognee stores graph data locally using Kuzu (a file-based database). When you switch to Neo4j,
your data moves to a Neo4j server — which can be local (self-hosted) or cloud-based (Neo4j Aura).

* **Self-hosted Neo4j** — You run Neo4j yourself (locally or on a server). Data stays on that server.
* **Neo4j Aura** — Neo4j's fully managed cloud service. Data is stored in Neo4j's cloud infrastructure; nothing is saved locally on your machine. This is useful for teams, production deployments, or when you need managed backups.

## Installation

Both options use Neo4j as the graph database provider, so install the Neo4j dependencies first:

```bash theme={null}
pip install "cognee[neo4j]"
```

## Two Ways to Use Neo4j Aura

<Tabs>
  <Tab title="Connect to an Existing Aura Instance">
    If you already have a Neo4j Aura account and a database instance, you can point Cognee at it
    directly using the connection URI from your Aura console:

    ```dotenv theme={null}
    GRAPH_DATABASE_PROVIDER="neo4j"
    GRAPH_DATABASE_URL="neo4j+s://<your-instance-id>.databases.neo4j.io"
    GRAPH_DATABASE_NAME="neo4j"
    GRAPH_DATABASE_USERNAME="neo4j"
    GRAPH_DATABASE_PASSWORD="<your-aura-password>"
    ```

    This is the simplest approach. All datasets share the same Aura instance.

    For the general Neo4j provider setup and more context on using a single shared Aura database,
    see [Graph Stores](/setup-configuration/graph-stores#neo4j-aura-cloud).
  </Tab>

  <Tab title="Auto-Provisioned Aura Instances per Dataset (this handler)">
    The `Neo4jAuraDevDatasetDatabaseHandler` goes further: it automatically creates a dedicated
    Neo4j Aura instance for each Cognee dataset via the Neo4j Aura API, and deletes it when the
    dataset is removed. This enables strong per-dataset isolation for multi-user deployments.

    This handler requires **Neo4j Aura API OAuth credentials**, not a regular database password.

    ### Getting Aura API Credentials

    To use the auto-provisioning handler you need OAuth credentials from the Neo4j Aura console:

    1. Log in to [console.neo4j.io](https://console.neo4j.io)
    2. Navigate to **Account → API Keys**
    3. Create a new API key to obtain a `client_id` and `client_secret`
    4. Find your **Tenant ID** on the Aura console home page or under account settings

    ### Environment Variables

    Set the following variables in your `.env` file:

    ```dotenv theme={null}
    GRAPH_DATABASE_PROVIDER="neo4j"
    NEO4J_CLIENT_ID=<your_oauth_client_id>
    NEO4J_CLIENT_SECRET=<your_oauth_client_secret>
    NEO4J_TENANT_ID=<your_aura_tenant_id>
    NEO4J_ENCRYPTION_KEY=<a_secret_key_for_encrypting_stored_credentials>
    GRAPH_DATASET_DATABASE_HANDLER="neo4j_aura_dev"
    ```

    | Variable                         | Required    | Description                                           |
    | -------------------------------- | ----------- | ----------------------------------------------------- |
    | `NEO4J_CLIENT_ID`                | Yes         | OAuth client ID from the Neo4j Aura API console       |
    | `NEO4J_CLIENT_SECRET`            | Yes         | OAuth client secret from the Neo4j Aura API console   |
    | `NEO4J_TENANT_ID`                | Yes         | Your Neo4j Aura tenant (organization) ID              |
    | `NEO4J_ENCRYPTION_KEY`           | Recommended | Key used to encrypt database passwords at rest        |
    | `GRAPH_DATASET_DATABASE_HANDLER` | Yes         | Selects the `neo4j_aura_dev` dataset database handler |

    <Warning>
      **`NEO4J_ENCRYPTION_KEY`** defaults to `"test_key"` if not set. Always set a strong random key in production to protect the Aura instance credentials stored in Cognee's relational database.
    </Warning>

    ### How It Works

    When a dataset is created, Cognee:

    1. Calls the Neo4j Aura API to provision a new database instance (1 GB, Neo4j 5, GCP)
    2. Polls until the instance is ready (up to \~5 minutes)
    3. Encrypts the instance password and stores the connection details in Cognee's relational database
    4. Returns connection info so subsequent operations use that dataset's dedicated graph

    When a dataset is deleted, Cognee calls the Aura API to tear down the corresponding instance.

    <Info>
      Each dataset gets its own Aura instance. For applications with many datasets, this results in
      multiple Aura instances running in parallel. Check your Aura plan limits accordingly.
    </Info>
  </Tab>
</Tabs>

<CardGroup cols={2}>
  <Card title="Graph Stores" icon="book" href="/setup-configuration/graph-stores">
    Details About Cognee's Graph Stores (including Neo4j Aura Option 1)
  </Card>

  <Card title="Multi-User Overview" icon="users" href="/core-concepts/multi-user-mode/multi-user-mode-overview">
    More Details About Multi-User Mode
  </Card>
</CardGroup>