# Graph databases (https://docs.ctxpipe.ai/docs/self-hosting/graph-databases)

When you self-host this service, you must set up an OpenCypher-compatible graph database for knowledge graphs, RAG, and related workloads. This guide helps you choose and set up one of the supported engines.

## Quick Start (FalkorDB)

The easiest way to start is **FalkorDB**. The default stack includes it as a Docker container. You do not need extra setup. Run:

```bash
docker compose --profile deploy up -d
```

By default, the backend connects to FalkorDB with the **native driver** at `redis://falkordb:6379`. For host-based deployments, point `GRAPH_DB_URI` at your FalkorDB instance (for example `redis://localhost:6379`). Or use any OpenCypher-compatible database with the Bolt driver.

On Docker Compose, the `GRAPH_DB_*` values in `.env` do not reach the backend.
Set them in a `docker-compose.override.yml`. See
[Settings that need an override file](/docs/self-hosting/deployment/docker#settings-that-need-an-override-file).

## Supported Engines

You can use any of these OpenCypher-compatible engines. FalkorDB uses its native driver (Redis protocol). Others use Bolt.

| Engine               | Best for                      | Notes                                                        |
| -------------------- | ----------------------------- | ------------------------------------------------------------ |
| **FalkorDB**         | Easy start, multi-tenant SaaS | Open-source. Included in Docker Compose. Graphs auto-create. |
| **Neo4j Enterprise** | Enterprise multi-tenant       | Requires `CREATE DATABASE` per org (admin).                  |
| **Neo4j Community**  | Cost-conscious multi-tenant   | One database per instance. Use instance-per-tenant.          |
| **Memgraph**         | Enterprise, real-time         | Enterprise edition for multi-database.                       |
| **Neptune**          | AWS-hosted                    | Managed service. Single graph per cluster.                   |

Set `GRAPH_DB_PROVIDER` to match your engine. The service infers the tenancy mode automatically.

## Environment Variables

| Variable                 | Required                  | Default                 | Description                                                                                 |
| ------------------------ | ------------------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
| `GRAPH_DB_URI`           | No                        | `redis://falkordb:6379` | FalkorDB: `redis://host:6379`. Others: Bolt URI (e.g. `bolt://host:7687`).                  |
| `GRAPH_DB_USER`          | No                        | `default` / `neo4j`     | Username for auth.                                                                          |
| `GRAPH_DB_PASSWORD`      | No                        | `""`                    | Password for auth.                                                                          |
| `GRAPH_DB_PROVIDER`      | No                        | `falkordb`              | Engine: `falkordb`, `neo4j-enterprise`, `neo4j-community`, `memgraph`, `neptune`.           |
| `GRAPH_DB_URI_<orgSlug>` | Yes (instance-per-tenant) | -                       | Per-org URI. Required when using Neo4j Community or Neptune. No fallback to `GRAPH_DB_URI`. |

**Example (FalkorDB, Docker network):**

```bash
GRAPH_DB_URI=redis://falkordb:6379
GRAPH_DB_PROVIDER=falkordb
```

**Example (Neo4j Community, instance-per-tenant, org slugs `acme`, `piedpiper`):**

```bash
GRAPH_DB_URI=bolt://neo4j.example.com:7687
GRAPH_DB_URI_acme=bolt://neo4j-acme.example.com:7687
GRAPH_DB_URI_piedpiper=bolt://neo4j-piedpiper.example.com:7687
GRAPH_DB_USER=neo4j
GRAPH_DB_PASSWORD=yourpassword
GRAPH_DB_PROVIDER=neo4j-community
```

**Example (Neptune):**

```bash
GRAPH_DB_URI_acme=bolt+s://your-cluster.region.neptune.amazonaws.com:8182
GRAPH_DB_PROVIDER=neptune
```

## Tenancy Modes

All setups are **multi-tenant**. The service must isolate the graph data of each organization from the data of the others. The service infers the tenancy strategy from the provider in `GRAPH_DB_PROVIDER`.

### Database-per-tenant (shared instance)

**Providers**: FalkorDB, Neo4j Enterprise, Memgraph

These engines support **multiple graphs or databases in one instance**, with strong isolation between them. One shared instance serves many organizations. Each organization gets its own graph or database (for example `org_abc123`). The service passes the database name of the organization when it runs queries. Data therefore stays isolated at the database layer.

### Instance-per-tenant (separate instance per org)

**Providers**: Neo4j Community, Neptune

Neo4j Community and Neptune **do not support multiple databases or graphs in one instance**. Each instance has one logical graph. For per-organization isolation, the service uses **instance-per-tenant**. Each organization must have its own database instance. The service routes each query to the instance of the organization. The deployment topology enforces isolation, not the database engine.

Set `GRAPH_DB_URI_<orgSlug>` for each organization (for example `GRAPH_DB_URI_acme`, `GRAPH_DB_URI_piedpiper`). There is no fallback to `GRAPH_DB_URI`. Each organization must have its own URI. The AWS CDK construct sets this variable for its one `orgSlug`, so CDK users need to do nothing.

## Engine-Specific Setup

### FalkorDB

* **Docker**: `falkordb/falkordb`. Uses Redis protocol on port 6379 by default. Pin a version in production; hosted ctxpipe pins one.
* **URI**: `redis://host:6379` (native driver, recommended for production).
* **User**: `default`
* **Password**: Empty by default. With Redis `--requirepass`, use that password.

### Neo4j

* **URI**: `bolt://host:7687`
* **User**: `neo4j`
* **Password**: Set via `GRAPH_DB_PASSWORD` or `NEO4J_AUTH` (Docker).

### Memgraph

* **URI**: `bolt://host:7687`
* **User**: Typically `memgraph` or as per your deployment.
* **Enterprise**: Use `memgraph` provider for database-per-tenant.

### Neptune

* **URI**: The Bolt endpoint of your cluster, with TLS (e.g. `bolt+s://cluster.region.neptune.amazonaws.com:8182`).
* **Auth**: ctxpipe does not support IAM database authentication. Turn IAM auth off on the cluster, as the AWS CDK construct does. Set `GRAPH_DB_USER` and `GRAPH_DB_PASSWORD` only if your cluster needs them. See [AWS Neptune docs](https://docs.aws.amazon.com/neptune/).
