GGraphDB

A general-purpose object-storage-backed graph database for entities, relationships, and topology

中文 README · Latest Release

GGraphDB 1.1 is a Go-based general-purpose current-state property knowledge graph for entity-relationship data. Knowledge bases, CMDB, asset relationships, service dependencies, topology, and impact analysis are supported application scenarios. It persists tenant data to local disk or S3-compatible object storage, using Parquet, manifest CAS, snapshots, and commit replay to provide versioned writes and explicit read-freshness control. It is not an RDF/OWL, SPARQL, ontology-reasoning, or historical graph engine.

Highlights

Capability	Description
Multi-tenant graph data	Tenant prefixes, entities, edges, and indexes are isolated by X-Tenant-ID.
Optional domain modeling	Entity types, labels, relation property schemas, identity reconciliation, source priority, and manual merge/split.
Graph queries	GraphQL, JSON Query DSL, bounded pattern match, bidirectional traversal, impact, and shortest path.
Bulk import	Resumable task-backed JSONL and CSV ingestion.
Object-storage persistence	Parquet manifests, commits, snapshots, entity pages, edge shards, and index objects.
Read/write topology	One binary supports all, writer, and reader deployment modes.
Optional multi-writer coordination	PostgreSQL head CAS supports 2–8 optimistic writers per tenant while local coordination remains the default.
Operations	Compact, GC, backup/restore, repair, integrity audit, index health, and metrics.

Architecture

flowchart LR
  A[Collectors / API] --> W[Writer\\nGRAPHDB_MODE=writer]
  W -. optional head CAS .-> P[(PostgreSQL\\ncoordination)]
  W --> O[(S3 / RustFS\\nParquet + Manifest)]
  O --> R[Reader fleet\\nGRAPHDB_MODE=reader]
  R --> Q[GraphQL / JSON DSL queries]
  A --> A1[all mode\\nlocal development]
  A1 --> O

Loading

Quick start

Local file storage

Requires Go 1.25 or newer:

go run ./cmd/graphdb serve
curl -fsS http://127.0.0.1:8080/v1/health

Docker Compose with MinIO

docker compose up --build
curl -fsS http://127.0.0.1:8080/v1/health

RustFS writer/reader topology

docker compose -f docker-compose.rustfs.yml up --build
curl -fsS http://127.0.0.1:38080/v1/health  # writer
curl -fsS http://127.0.0.1:38081/v1/health  # reader

Create a tenant, write data, and query

# 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 the JSON Query 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

# 4. Query the generic graph with GraphQL
curl -fsS -X POST http://127.0.0.1:8080/v1/query/graphql \
  -H 'X-Tenant-ID: demo' \
  -H 'Content-Type: application/json' \
  -d '{"query":"query Find($request: QueryRequest!) { graph(request: $request) { version results stats } }","operationName":"Find","variables":{"request":{"op":"match","kind":"person","where":[{"field":"name","op":"eq","value":"Alice"}],"project":["id","name"],"limit":10}}}'

The write response's version can be passed as min_version to a reader when the query must observe that write. Use allow_stale=true only when eventual consistency is acceptable.

Generic graph queries with GraphQL

The examples/commit.json dataset contains a non-CMDB graph: person:alice works at company:acme. GraphQL accepts the same generic JSON Query DSL request as a QueryRequest variable, so application-defined entity kinds, fields, and relation types work for organization graphs, project dependencies, data lineage, and other graph-shaped data.

Find an entity by a property:

query FindPerson($request: QueryRequest!) {
  graph(request: $request) {
    version
    results
    stats
  }
}

Use {"op":"match","kind":"person",...} as the request variable. Follow a typed relationship by changing it to {"op":"neighbors","id":"person:alice","relation_types":["works_at"]}.

See the GraphQL guide for the schema, errors, aliases, fragments, and 1.1 boundaries. The old FIND/MATCH text DSL remains at /v1/query/gql only for 1.0 compatibility and is not GraphQL.

Deployment modes

Mode	Use case	Behavior
all	Local development and small single-process deployments	One process handles writes and queries.
writer	Production write entry point	Write and control APIs; one local writer or a PostgreSQL-coordinated writer fleet.
reader	Query fleet	Loads from shared object storage and serves queries and exports.

For production, use shared S3/RustFS storage and multiple readers. Keep the default GRAPHDB_COORDINATION=local topology at one writer per tenant, or use GRAPHDB_COORDINATION=postgres with generic S3/RustFS for 2–8 optimistic writers. Process readiness actively probes object storage, and PostgreSQL mode prunes completed coordination rows with bounded retention. Reader-fleet readiness remains the tenant traffic admission gate. X-Tenant-ID is routing metadata, not authentication. Put authentication, authorization, TLS, and rate limiting at the gateway or service mesh.

Release

The latest published release is GGraphDB 1.1: v1.1.5. The release workflow publishes the tag only after its release checklist, 30-minute PostgreSQL CAS gate, and formal rollback drill pass. For v1.1.5, the release evidence also binds a real process-level WAL recovery run covering restart and object-store interruption in explicit WAL/segment mode.

Each release archive contains:

• static binaries for Linux amd64, Linux arm64, and macOS arm64;
• Dockerfile, MinIO/RustFS/PostgreSQL Compose files, and examples;
• deployment, security, capacity, API, query, SDK, changelog, and build metadata;
• a .sha256 checksum file.

See the release deployment guide or its 中文版本. Pushing a semantic-version tag such as v1.1.5 triggers GitHub Actions to build and publish the archive automatically. Legacy release_* tags remain supported for older deployment workflows.

Documentation

Guide	Contents
Database introduction · 中文	Product shape, data model, architecture, and boundaries.
Usage manual · 中文	Tenants, writes, queries, optional CMDB scenario capabilities, indexes, maintenance, and SDKs.
Deployment and operations · 中文	all/writer/reader, S3, RustFS, health checks, and production rules.
Security boundary · 中文	Data/admin listeners, gateway auth, tenant binding, RBAC, and TLS.
Capacity envelope · 中文	Release CAS gate, reproducible baselines, and recommended topology.
Release deployment · 中文	Download, verify, upgrade, rollback, and security boundaries.
Read and query · 中文	GraphQL, JSON DSL, pagination, streaming, explain, and profile.
Write and ingest · 中文	Commits, ingestion, idempotency, deletes, source policy, and backpressure.
Data model · 中文	Tenants, optional CI types, entities, relations, edges, and source governance.
OpenAPI contract	The complete HTTP API definition.
Go and Python SDKs · 中文	Client setup, reads, writes, streaming, and retry guidance.
All user guides · 中文	Complete API, deployment, operations, and troubleshooting map.

Project status and boundaries

GGraphDB v1 is intentionally focused:

• a general-purpose entity-relationship graph core, with CMDB governance as an optional domain profile;
• local coordination defaults to one active writer per tenant; optional PostgreSQL coordination provides optimistic multi-writer head CAS;
• object storage as the recommended production persistence layer;
• explicit reader freshness controls for strong-read workflows;
• authentication and authorization delegated to the deployment boundary.

See the feature gap tracker for remaining product work.

Development

# Unit and package tests
go test -mod=readonly ./...

# Validate both deployment topologies
docker compose config
docker compose -f docker-compose.rustfs.yml config

The repository also contains black-box e2e, load, soak, reader-freshness, recovery, and release-gate tools under tools/ and scripts/. Read the relevant operations document before running long or disruptive checks.

Contributing and license

See CONTRIBUTING.md, SECURITY.md, and LICENSE. The current license is rights-reserved; public source availability does not grant production or redistribution rights.