A multi-tenant property graph database, with a built-in management console.
简体中文 · Stable download · Documentation · Release notes
Manage entities, relationships and source-governed ingestion; query the graph with JSON DSL or GraphQL. Start with one process and one local disk. Add independent Raft replicas for high availability or tenant-sharded Raft groups for horizontal expansion. Object storage and PostgreSQL are not required at runtime; S3-compatible storage is optional for snapshot backups.
Start · Write and query · Choose a deployment · Validation
2.6.1 returns a complete, retryable HTTP 503 when Raft maintenance cancels a read before its response starts. Writes on interrupted streams remain bounded.
2.6.0 includes opt-in large-graph sharding and partitioned WAL. Raft defaults to protocol 1. Protocol 12 requires explicit activation on the home group. See activation and upgrade limits and 2.6.0 validation.
2.5.1 enables durable asynchronous WAL ingestion in standalone Compose and splits oversized index catch-up into ordered incremental updates. Release binaries use Go 1.27.3.
| Area | Capabilities in 2.6.0 |
|---|---|
| Management UI | Embedded English / Simplified Chinese console at /ui/; no separate frontend service |
| Daily workflows | Chart overview, structured forms and details, query workbench, ingestion and maintenance |
| Large tenant registries | Server-side tenant ID search and bounded pages for tenant selection and cluster placements |
| Bounded indexes | Opt-in adjacency trees, local page merging and pruned range scans; legacy layouts and global edge cursors retained |
| Reliability | Durable receipt publication, WAL replay, offline receipt checks and automatic inode reclamation |
| Deployment | Standalone direct/WAL, independent Raft replicas and tenant-sharded Raft groups, with opt-in large-graph partitioning and partitioned WAL |
See release checks for evidence and version boundaries for compatibility.
From the repository root, with the Go version in go.mod:
go build -o bin/graphdb ./cmd/graphdb
GRAPHDB_DATA_DIR=./.graphdb bin/graphdb servePrefer a packaged binary? Follow release deployment to download and verify it.
Container alternative
Run from the repository root. The standalone Compose deployment has one service and one persistent volume. Ingest batches use the local WAL and return HTTP 202 after fsync. Use GRAPHDB_INGEST_MODE=direct for synchronous ingestion without a WAL, or send Prefer: wait=committed to wait for a WAL batch's terminal result.
docker compose up -d --buildOpen http://127.0.0.1:8080/ui/. Choose a tenant in the top bar and a language at the bottom of the sidebar. With split listeners, open the management port. See the console guide.
In another terminal:
curl -fsS http://127.0.0.1:8080/v1/healthHealth is a liveness check. Use the readiness checks before sending production traffic.
Keep the service running. Execute these commands from the repository root so the example files resolve correctly. They use the default combined listener.
curl -fsS -X POST http://127.0.0.1:8080/v1/tenants \
-H 'Content-Type: application/json' \
-d '{"tenant_id":"demo","name":"Demo"}'curl -fsS -X POST http://127.0.0.1:8080/v1/commits \
-H 'X-Tenant-ID: demo' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: demo-commit-001' \
--data @examples/commit.jsoncurl -fsS -X POST http://127.0.0.1:8080/v1/query \
-H 'X-Tenant-ID: demo' \
-H 'Content-Type: application/json' \
--data @examples/query-match.jsonFor GraphQL, follow the GraphQL examples. The console also provides a query workbench with table, JSON and graph result views.
| Contract | Meaning |
|---|---|
X-Tenant-ID |
Selects the tenant for data APIs |
version |
Pass the write response's version as min_version when the read must observe that write |
data_hash |
Commit digest, identified as sha256-shards-v2:<hex> |
| WAL acceptance | GRAPHDB_INGEST_MODE=wal enables WAL; HTTP 202 confirms acceptance, and Prefer: wait=committed waits for the terminal result |
| Workflow | Supported operations |
|---|---|
| Model and govern | Entity/relationship types, field constraints, identity keys, source priority, idempotency and collector state |
| Query | Match, pattern, neighbors, traversal, impact, shortest path, aggregation, pagination and streaming |
| Store and ingest | Direct commits, durable WAL ingestion, Parquet commits, snapshots and persistent indexes |
| Operate | Import/export, saved queries, tenant lifecycle, backup/restore, repair, compaction, GC and persistent tasks |
| Integrate and observe | Go/Python SDKs, Prometheus metrics, JSON logs and optional OTLP traces |
| Deployment | Use when | Start here |
|---|---|---|
| Standalone | One process with synchronous local direct/WAL writes | Local disk guide · Compose |
| Raft | Majority persistence and leader failover; each replica holds a full copy on its own disk | Three-replica guide · Compose |
| Sharded Raft | Independent catalog/shard groups, tenant placement and explicit migration | Sharding guide · Compose |
All three support direct and WAL ingestion. Standalone leaves GRAPHDB_RAFT_*
unset; Raft requires the complete node configuration. Sharding adds catalog/shard
roles and serve-router. Separate deployments need separate ports and directories.
Directory ownership. One process exclusively owns each data directory. Stop it before running offline CLI tools on that directory; use HTTP for live administration. Linux and macOS local filesystems are supported. Separate reader/writer processes and shared network filesystems are unsupported.
Upgrade and recovery. Stop the old standalone 2.0/2.1/2.2 process before reusing its directory. Raft directories cannot become standalone by removing settings, and standalone data cannot bootstrap a replica. Use API imports or backup restore into a new directory when moving between deployments. Raft upgrades follow the qualified rolling window. No 1.x migration is provided.
Backups and access. Standalone supports built-in S3 scheduling; Raft uses external scheduling of cluster backup APIs. The backup worker provides retries, verification, isolated drills and Compose/systemd examples for both. Configure authentication, tenant authorization and TLS at your gateway before exposing the service.
Development testing exercised power loss during shared graph-file publication, first receipt database creation and WAL replay. The 2.5.0 power-cut record, exact-tag gates and packaged evidence define release qualification.
Across three same-host HTTP repetitions of a 16,000-string array, median append_unique latency fell from approximately 4.25 seconds in v2.4.3 to 7 milliseconds in the candidate. This focused comparison does not establish production throughput, overall write P99 or capacity. Historical tail measurements remain relevant.
Upgrade boundary. Standalone startup persists local directory format v2 before enabling packed receipts. Keep a complete pre-upgrade runtime backup and restore it into a separate directory for rollback. Raft defaults to protocol 1. See version boundaries. Cross-host reliability, day-scale stability and production capacity remain unqualified.
Storage and publication design
Data files are synced before manifest/catalog publication. A bounded four-worker write path coalesces directory syncs with file, byte and time budgets; Parquet random reads select columns and row groups. Bounded caches invalidate on local publication. GC protects active read views; destructive lifecycle operations wait for them to finish.
Raft prepares maintenance outside the application barrier where the protocol permits, pauses conflicting writes for the maintenance tenant, uses separate bounded control queues and migrates with disk-backed chunks. Publication, graph decoding and rollback still consume resources. See architecture.
| I want to… | Read |
|---|---|
| Browse all guides | Documentation index · User guide |
| Use the console | Management UI |
| Build a query or client | Query capabilities · GraphQL · OpenAPI · Go SDK · Python SDK |
| Maintain the service | Product operations · Raft operations · Diagnostic metrics |
| Check release evidence | 2.6.1 release checks · Compatibility |
Some cluster operations guides are currently Chinese-only; the user guide and console documentation are bilingual.
Use OrbStack Linux with a Linux volume for backend runtime validation.
| Check | Command |
|---|---|
| Unit tests | go test -mod=readonly ./... |
| Static analysis | go vet -mod=readonly ./... |
| Full static release gate | RELEASE_GATE_VERIFY_ONLY=1 scripts/release_gate.sh |
| Runtime integration | RELEASE_GATE_SKIP_STATIC=1 scripts/release_gate.sh |
| 30-minute maintenance soak | GRAPHDB_GATE_SOAK=1 RELEASE_GATE_SKIP_STATIC=1 scripts/release_gate.sh |
The runtime gate exercises direct/WAL ingestion, graph APIs, maintenance and restart consistency. Scripts manage their own processes and retain evidence in the printed output directory.