GGraphDB 2.4.4

A multi-tenant property graph database, with a built-in management console.

简体中文 · 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

Current release

2.4.4 fixes ambiguous entity identities, invalid batches blocking WAL progress, quadratic array deduplication and numeric aggregation overflow. Standalone writes adopt the new identity rules automatically, alongside inode protection and online tenant metadata recovery. Release binaries use Go 1.27.3.

Area	What 2.4.4 provides
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	Deterministic replication failures, cancelable reads, durable replay and protected GC continuation
Deployment	Standalone direct/WAL, independent Raft replicas and tenant-sharded Raft groups

See release validation for evidence and version boundaries for compatibility.

Start

1. Run the service

From the repository root, with the Go version in go.mod:

go build -o bin/graphdb ./cmd/graphdb
GRAPHDB_DATA_DIR=./.graphdb bin/graphdb serve

Prefer a packaged binary? Follow release deployment to download and verify it.

Container alternative

Run from the repository root. The default Compose deployment has one service and one persistent volume.

docker compose up -d --build

2. Open the console

Open 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.

3. Check the service

In another terminal:

curl -fsS http://127.0.0.1:8080/v1/health

Health is a liveness check. Use the readiness checks before sending production traffic.

Write and query

Keep the service running. Execute these commands from the repository root so the example files resolve correctly. They use the default combined listener.

1. Create a tenant

curl -fsS -X POST http://127.0.0.1:8080/v1/tenants \
  -H 'Content-Type: application/json' \
  -d '{"tenant_id":"demo","name":"Demo"}'

2. Write example graph data

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.json

3. Query with JSON DSL

curl -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.json

For 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

Capabilities

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 options

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.

Validation and limits

This round verified cold replay of old commits, recovery of invalid v2.4.3 WAL batches, durable failure status after restart and protocol-4 replica consistency on OrbStack Linux. The 2.4.4 validation 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: New commits record their identity rules; old commits retain their original replay semantics. Already merged entities are not automatically separated. Keep a pre-upgrade backup: older binaries cannot safely reuse directories after new-format writes. Raft still defaults to protocol 1; activate protocol 4 separately after upgrading every voter. See the upgrade guide. 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.

Documentation

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.4.4 validation · Compatibility

Some cluster operations guides are currently Chinese-only; the user guide and console documentation are bilingual.

Development

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.

Contributing · Security · License — rights reserved