Graph databases
Choose and set up an OpenCypher-compatible graph database when self-hosting ctxpipe.
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:
docker compose --profile deploy up -dBy 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.
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):
GRAPH_DB_URI=redis://falkordb:6379
GRAPH_DB_PROVIDER=falkordbExample (Neo4j Community, instance-per-tenant, org slugs acme, piedpiper):
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-communityExample (Neptune):
GRAPH_DB_URI_acme=bolt+s://your-cluster.region.neptune.amazonaws.com:8182
GRAPH_DB_PROVIDER=neptuneTenancy 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_PASSWORDorNEO4J_AUTH(Docker).
Memgraph
- URI:
bolt://host:7687 - User: Typically
memgraphor as per your deployment. - Enterprise: Use
memgraphprovider 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_USERandGRAPH_DB_PASSWORDonly if your cluster needs them. See AWS Neptune docs.