enterprise

README

GraphDB

A high-performance, feature-rich graph database built from scratch in Go. GraphDB combines modern storage techniques with powerful graph algorithms and multiple query interfaces.

Releases

Latest server release: v0.4.1. First-party clients: Python SDK v0.1.0 and TypeScript client v1.0.0 (Cloudflare Workers).

Try it in two minutes

All data endpoints require authentication, so the quickstart includes getting a token:

# 1. Start the server (Docker recommended)
docker run -p 8080:8080 -e ADMIN_PASSWORD='choose-a-password' dd0wney/graphdb:latest

# 2. Log in and grab a token
TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "choose-a-password"}' | jq -r .access_token)

# 3. Create your first node
curl -X POST http://localhost:8080/nodes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["Person"], "properties": {"name": "Alice", "age": 30}}'

Without ADMIN_PASSWORD, a development-mode server generates a random admin password and writes it to <data-dir>/.graphdb_admin_password. Pre-built binaries for Linux/macOS/Windows are on the releases page.

Available for:

• Docker: Multi-arch images (amd64, arm64) on Docker Hub
• macOS: arm64 (M1/M2/M3) & x86_64 (Intel)
• Linux: arm64 & x86_64
• Windows: arm64 & x86_64

Performance Highlights:

• 5M nodes + 50M edges in just 73MB RAM (15.31 bytes/node)
• 330K writes/sec - sustained throughput over 5M nodes
• 1.5M lookups/sec - blazing fast random reads
• 152µs average latency (cold cache), 38µs (hot cache)
• 10ms - average shortest path query

Features

Core Database

• LSM-Tree Storage - Efficient write-heavy workloads with leveled compaction
• Write-Ahead Logging (WAL) - Durability and crash recovery
• Bloom Filters - Fast negative lookups
• Block Cache - LRU caching for read performance
• Property Indexes - Fast property-based lookups
• Batched Operations - Efficient bulk data loading

Vector Search

• HNSW Indexes - Hierarchical Navigable Small World graphs for fast k-NN search
• Multiple Distance Metrics - Cosine, Euclidean, and Dot Product similarity
• Automatic Index Sync - Vector indexes stay in sync with node CRUD operations
• Label Filtering - Filter vector search results by node labels
• Tunable Parameters - Configure M, efConstruction, and ef for recall/speed tradeoffs

Graph Algorithms

• Cycle Detection - Find all cycles in the graph using DFS with three-color marking
• Topological Validators - DAG validation, topological sort, tree detection, connectivity, bipartite graphs
• PageRank - Node importance scoring with convergence detection
• Betweenness Centrality - Identify bridge nodes
• Community Detection - Label propagation algorithm
• Shortest Path - Bidirectional BFS and weighted Dijkstra
• Graph Traversal - DFS/BFS with configurable depth and direction

Constraint Validation

• Property Constraints - Validate node properties (required, type, range)
• Cardinality Constraints - Validate edge counts (min/max, direction)
• Validation Framework - Multi-constraint validation with detailed violation reporting
• Severity Levels - Error, Warning, Info classifications

Query Interfaces

1. Cypher-like Query Language

MATCH (p:Person)-[:KNOWS]->(f:Person)
WHERE p.age > 25
RETURN p, f

2. REST API Server

# Start the server
docker run -p 8080:8080 -e ADMIN_PASSWORD='choose-a-password' dd0wney/graphdb:latest

# Query via HTTP (get $TOKEN from /auth/login — see "Try it in two minutes")
curl -X POST http://localhost:8080/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (n:Person) RETURN n"}'

3. Interactive CLI

./bin/cli

graphdb> stats
graphdb> query MATCH (p:Person) RETURN p
graphdb> pagerank

4. Beautiful TUI (Terminal UI)

./bin/tui

Interactive terminal interface with:

• Real-time dashboard with statistics
• Node browser with table navigation
• Query console with syntax highlighting
• ASCII graph visualization
• PageRank metrics with bar charts

5. Admin CLI (Security Management)

# Generate encryption key
./bin/graphdb-admin security init --generate-key

# Check security health
./bin/graphdb-admin security health --token="your-jwt-token"

# Rotate encryption keys
./bin/graphdb-admin security rotate-keys --token="your-jwt-token"

# Export audit logs
./bin/graphdb-admin security audit-export --output=audit.json

See the CLI Admin documentation for complete usage.

Client Libraries

Language	Package	Where
Go	github.com/dd0wney/graphdb	Import the pkg/ packages directly (embedded) or call the REST/GraphQL API
Python	graphdb-client (sync + async, retry/backoff, caching, LangChain adapters)	clients/python/, tagged python-sdk/v0.1.0
TypeScript	@graphdb/client for Cloudflare Workers	workers/graphdb-client/, tagged ts-client/v1.0.0

Scalability & Limitations

GraphDB is designed for high performance on a single node. While it includes advanced multi-tenancy and high-throughput primitives, users should be aware of the following architectural trade-offs:

• Single-Node by Design: The core engine is optimized for single-machine deployments; throughput is bounded by the resources of a single Go process. The standalone replication binaries were retired in A8.1 (see the note under "Building from Source").
• In-Memory + LSM Architecture: By default, GraphDB prioritizes low-latency access by keeping the graph topology in memory. Persistent storage (LSM/B+Tree) is used for durability and cold data tiering.
• LSA Scale Ceiling: The built-in Latent Semantic Analysis (LSA) for vector embeddings is optimized for corpora of ~100K-500K documents (at 200 dimensions). For larger datasets, we recommend using dedicated embedding models (e.g., OpenAI, Anthropic, or BGE) via the standard /v1/embeddings interface.
• Horizontal Scaling: Horizontal scaling (sharding, distributed consensus) is currently the responsibility of the operator (e.g., deploying per-tenant instances behind a load balancer).

Documentation

Comprehensive API documentation is available at graphdb.pages.dev

• Interactive API Explorer (Swagger UI) - Try out API endpoints directly in your browser
• API Reference (Redoc) - Beautiful, searchable API documentation
• Quick Start Guide - Complete guide with examples and best practices
• OpenAPI Specification - Machine-readable API spec

Security Documentation

• CLI Admin Guide - Command-line tools for security management
• Security Quick Start - Get started with encryption and security features
• Security Integration Summary - Architecture and implementation details
• Encryption Architecture - Deep dive into encryption design

The documentation covers:

• Authentication (JWT tokens and API keys)
• Encryption at rest and in transit
• Security management and monitoring
• Audit logging and compliance
• All REST API endpoints
• Request/response schemas
• Code examples in multiple languages
• Error handling and best practices
• Rate limits and performance tips

Additional Features

• Graph Partitioning Primitives - Hash- and range-based partitioning helpers (pkg/partition)
• Temporal Graphs - Time-aware edge queries via TemporalQuery
• Multi-Tenancy - Tenant-scoped storage, auth, and quotas throughout the API surface

Performance Optimizations

• Parallel Query Execution - Worker pools for concurrent operations
• Streaming Results - Memory-efficient result iteration
• Query Pipelines - Composable query operations
• In-Memory + Persistent - Hybrid storage for optimal performance

Architecture

┌─────────────────────────────────────────────────┐
│               GraphDB                            │
├─────────────────────────────────────────────────┤
│  User Interfaces                                 │
│  • Interactive TUI (Bubble Tea)                  │
│  • REST API Server                               │
│  • Query Language (Cypher-like)                  │
│  • Command-Line Interface                        │
├─────────────────────────────────────────────────┤
│  Query Layer (PARALLEL)                          │
│  • Lexer → Parser → Executor                     │
│  • Worker Pool                                   │
│  • Streaming Results                             │
│  • Query Pipelines                               │
├─────────────────────────────────────────────────┤
│  Algorithm Layer                                 │
│  • PageRank, Centrality, Community Detection    │
│  • Bidirectional BFS, Weighted Dijkstra         │
│  • Graph Traversal (DFS/BFS)                     │
├─────────────────────────────────────────────────┤
│  Storage Layer (LSM)                             │
│  • MemTable → Immutable MemTable → SSTables     │
│  • Bloom Filters + Block Cache                  │
│  • Leveled Compaction                            │
│  • Write-Ahead Logging (WAL)                     │
├─────────────────────────────────────────────────┤
│  Advanced Features                               │
│  • Vector Search (HNSW) + Hybrid Retrieval      │
│  • Temporal Graphs (time-aware queries)         │
│  • Multi-Tenancy (auth, quotas, isolation)      │
└─────────────────────────────────────────────────┘

Quick Start

Using Docker (Easiest)

Follow "Try it in two minutes" at the top of this README — start the container with ADMIN_PASSWORD, log in at /auth/login, and call the API with the returned token. /health is the only unauthenticated check:

curl http://localhost:8080/health

Deployment ordering: create property and vector indexes before serving production traffic — index builds are admin operations that run after writes, and queries fall back to scans until the index exists. See docs/PRODUCTION_QUICKSTART.md for the full production path.

Using Pre-built Binaries

Download the archive for your platform (Linux/macOS/Windows, amd64/arm64) from GitHub Releases, then:

tar -xzf graphdb_*_$(uname -s)_$(uname -m).tar.gz
ADMIN_PASSWORD='choose-a-password' ./graphdb-server --port 8080

Releases up to and including v0.4.1 name the server binary cluso-server; from the next release it is graphdb-server.

Building from Source

# Clone the repository
git clone https://github.com/dd0wney/graphdb
cd graphdb

# Build all binaries
go build -o bin/server ./cmd/server
go build -o bin/cli ./cmd/cli
go build -o bin/tui ./cmd/tui
go build -o bin/tui-demo ./cmd/tui-demo

Note on replication: graphdb is single-node by design. The standalone replication binaries (cmd/graphdb-{primary,replica} + nng variants) and the pkg/replication/ library were retired in A8.1 (PRs #129/#130/#133, 2026-05-12) because they pre-dated the multi-tenancy work and routed writes to the default tenant. Use cmd/server for any real deployment. Horizontal scale is a multi-quarter roadmap item — see docs/internals/design/A8_1_SPIKE_2026-05-12.md for the architectural decision and docs/PRODUCTION_QUICKSTART.md § "Scale Considerations" for the practical workarounds.

Try the Interactive TUI Demo

# Create demo database
./bin/tui-demo

# Launch the beautiful TUI
./bin/tui

The TUI includes:

• Dashboard - Real-time stats, uptime, query metrics
• Nodes - Browse all nodes in a table
• Query - Execute Cypher queries interactively
• Graph - Visualize your graph structure
• Metrics - PageRank analysis with visual bars

Usage Examples

Programmatic Usage

package main

import (
    "fmt"

    "github.com/dd0wney/graphdb/pkg/algorithms"
    "github.com/dd0wney/graphdb/pkg/constraints"
    "github.com/dd0wney/graphdb/pkg/query"
    "github.com/dd0wney/graphdb/pkg/storage"
)

func main() {
    // Create graph
    graph, _ := storage.NewGraphStorage("./data")
    defer graph.Close()

    // Create nodes
    alice, _ := graph.CreateNode(
        []string{"Person"},
        map[string]storage.Value{
            "name": storage.StringValue("Alice"),
            "age":  storage.IntValue(30),
        },
    )

    bob, _ := graph.CreateNode(
        []string{"Person"},
        map[string]storage.Value{
            "name": storage.StringValue("Bob"),
            "age":  storage.IntValue(25),
        },
    )

    // Create edge
    graph.CreateEdge(alice.ID, bob.ID, "KNOWS", nil, 1.0)

    // Detect cycles in the graph
    cycles, _ := algorithms.DetectCycles(graph)
    stats := algorithms.AnalyzeCycles(cycles)
    fmt.Printf("Found %d cycles\n", stats.TotalCycles)

    // Quick check for cycles
    hasCycle, _ := algorithms.HasCycle(graph)
    fmt.Printf("Graph has cycles: %v\n", hasCycle)

    // Validate graph constraints
    validator := constraints.NewValidator()
    validator.AddConstraint(&constraints.PropertyConstraint{
        NodeLabel:    "Person",
        PropertyName: "age",
        Type:         storage.TypeInt,
        Required:     true,
    })
    validationResult, _ := validator.Validate(graph)
    fmt.Printf("Graph valid: %v\n", validationResult.Valid)

    // Run PageRank
    opts := algorithms.PageRankOptions{
        MaxIterations: 100,
        DampingFactor: 0.85,
        Tolerance:     1e-6,
    }
    result, _ := algorithms.PageRank(graph, opts)

    // Execute query
    executor := query.NewExecutor(graph)
    lexer := query.NewLexer("MATCH (p:Person) WHERE p.age > 25 RETURN p")
    tokens, _ := lexer.Tokenize()
    parser := query.NewParser(tokens)
    parsedQuery, _ := parser.Parse()
    results, _ := executor.Execute(parsedQuery)
}

Query Language Examples

-- Find all people
MATCH (p:Person) RETURN p

-- Find friends of Alice
MATCH (p:Person {name: "Alice"})-[:KNOWS]->(f)
RETURN f

-- Find paths
MATCH (a:Person)-[:KNOWS*1..3]->(b:Person)
WHERE a.age > 25
RETURN a, b

-- Create nodes
CREATE (p:Person {name: "Alice", age: 30})

-- Create relationships
MATCH (a:Person {name: "Alice"}), (b:Person {name: "Bob"})
CREATE (a)-[:KNOWS]->(b)

-- Update properties
MATCH (p:Person {name: "Alice"})
SET p.age = 31

-- Delete nodes
MATCH (p:Person {name: "Alice"})
DELETE p

REST API Examples

# Health check
curl http://localhost:8080/health

# Get metrics
curl http://localhost:8080/metrics

# Create node
curl -X POST http://localhost:8080/nodes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["Person"],
    "properties": {"name": "Alice", "age": 30}
  }'

# Create edge
curl -X POST http://localhost:8080/edges \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_node_id": 1,
    "to_node_id": 2,
    "type": "KNOWS",
    "weight": 1.0
  }'

# Execute query
curl -X POST http://localhost:8080/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (p:Person) RETURN p"}'

# Find shortest path
curl -X POST http://localhost:8080/shortest-path \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_node_id": 1,
    "end_node_id": 5,
    "max_depth": 10
  }'

# Run PageRank
curl -X POST http://localhost:8080/algorithms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "pagerank",
    "parameters": {
      "iterations": 10,
      "damping_factor": 0.85
    }
  }'

# Detect cycles in the graph
curl -X POST http://localhost:8080/algorithms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "detect_cycles",
    "parameters": {
      "min_length": 2
    }
  }'

# Quick check if graph has any cycles
curl -X POST http://localhost:8080/algorithms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "has_cycle"
  }'

# Batch create nodes
curl -X POST http://localhost:8080/nodes/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {"labels": ["Person"], "properties": {"name": "Alice"}},
      {"labels": ["Person"], "properties": {"name": "Bob"}}
    ]
  }'

Vector Search Examples

Vector search enables semantic similarity queries using HNSW indexes - perfect for AI/ML applications, recommendation systems, and semantic search.

# 1. Create a vector index for embeddings
curl -X POST http://localhost:8080/vector-indexes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "property_name": "embedding",
    "dimensions": 384,
    "metric": "cosine"
  }'

# 2. Create nodes with vector embeddings
curl -X POST http://localhost:8080/nodes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["Document"],
    "properties": {
      "title": "Introduction to Graph Databases",
      "embedding": [0.1, 0.2, 0.3, ...]
    }
  }'

# 3. Perform semantic similarity search
curl -X POST http://localhost:8080/vector-search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "property_name": "embedding",
    "query_vector": [0.15, 0.22, 0.31, ...],
    "k": 10,
    "include_nodes": true,
    "filter_labels": ["Document"]
  }'

# Response:
# {
#   "results": [
#     {"node_id": 123, "distance": 0.15, "score": 0.85, "node": {...}},
#     {"node_id": 456, "distance": 0.23, "score": 0.77, "node": {...}}
#   ],
#   "count": 10,
#   "time": "1.234ms"
# }

# List all vector indexes
curl -X GET http://localhost:8080/vector-indexes \
  -H "Authorization: Bearer $TOKEN"

# Delete a vector index
curl -X DELETE http://localhost:8080/vector-indexes/embedding \
  -H "Authorization: Bearer $TOKEN"

Supported Distance Metrics:

Metric	Best For	Score Range
cosine	Text embeddings, normalized vectors	-1 to 1
euclidean	Spatial data, image features	0 to 1
dot_product	Maximum inner product search	unbounded

Graph-Augmented Retrieval (/v1/retrieve)

/v1/retrieve composes hybrid search (FTS + LSA via RRF) with graph traversal to return ranked context chunks for LLM prompts. Each result includes a source.path array — the BFS path from the contributing seed — so downstream code can cite why a chunk is in context. Tenant-scoped end-to-end.

The endpoint shape matches LangChain's BaseRetriever, so it drops into existing RAG pipelines. See examples/retrieve-curl.sh and examples/retrieve-langchain.py.

curl -X POST http://localhost:8080/v1/retrieve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What does Alice know about graph databases?",
    "k": 10,
    "max_hops": 2,
    "max_tokens": 4096
  }'

# Response:
# {
#   "documents": [
#     {
#       "page_content": "Alice authored a paper on graph database internals...",
#       "metadata": {
#         "node_id": 42,
#         "score": 0.87,
#         "source": {
#           "node_id": 42,
#           "label": "Doc",
#           "path": [17, 23, 42]   // seed → Person Alice → this Doc
#         }
#       }
#     }
#   ],
#   "took_ms": 124
# }

Request fields (defaults in parentheses):

Field	Type	Default	Notes
query	string	(required)	Free-text query, FTS + LSA seed retrieval
k	int	10	Max chunks returned (after token-budget drop)
max_hops	int	2	BFS depth from seeds; 0 = seeds only
max_tokens	int	4096	Token budget; chunks dropped whole, lowest score first
alpha	float	0.7	Weight on normalized seed score
beta	float	0.3	Weight on exp(-d/τ) graph-distance term
tau	float	2.0	Decay constant for distance falloff
labels	string[]	—	Optional seed-stage label filter
include_node	bool	false	Hydrate full node into metadata.node

A hard 50-node cap prevents pathological expansion in dense graphs. See docs/internals/design/F2_GRAPHRAG_DESIGN.md for the design rationale and pkg/retrieval/retrieval_bench_test.go for measured latency (p95=82µs on 1k nodes).

Benchmarks

Performance Results

Capacity Test (5M nodes + 50M edges):

Validated on GitHub Actions (AMD EPYC 7763, 16GB RAM):

Metric	Performance	Notes
Write Throughput	330K nodes/sec	Sustained rate over 5M nodes
Read Throughput	1.5M lookups/sec	Random reads
Cold Cache Latency	152µs average	Initial read
Hot Cache Latency	38µs average	4x speedup on cached data
Memory Efficiency	15.31 bytes/node	Incredibly low overhead
Total Memory (5M nodes)	73 MB	Including 50M edges

Unit Benchmarks (per operation):

Operation	Throughput	Latency
CompressedEdgeList New	~1.3M ops/sec	4.6µs
EdgeStore CacheHit	~9.4M ops/sec	640ns
EdgeCache Hit/Miss	~320M ops/sec	19ns
Property Index Insert	~30M ops/sec	192ns
Property Index Lookup	~14M ops/sec	394ns
LSM Put	~33M ops/sec	179ns
LSM Get	~122M ops/sec	49ns
Node Creation	~15K ops/sec	401µs
Edge Creation	~14K ops/sec	413µs
GetNode	~29M ops/sec	207ns
Shortest Path	~1K queries/sec	10.25ms
PageRank (10K nodes)	Converges in <100ms	-

Storage Benchmarks:

Benchmark	Throughput	Latency
Node Creation	2,812 nodes/sec	355µs
Edge Creation	2,875 edges/sec	347µs
Random Lookups	1.5M lookups/sec	0.65µs
Outgoing Edges Query	449K queries/sec	2.22µs
BFS Traversal	22,845 traversals/sec	0.04ms

Running Benchmarks

# Clone and build
git clone https://github.com/dd0wney/graphdb
cd graphdb

# Run all benchmarks
go test -bench=. ./...

# Run specific benchmark
go test -bench=BenchmarkGraphStorage ./pkg/storage

# With memory profiling
go test -bench=. -benchmem ./pkg/storage

# Run capacity test
cd pkg/storage
RUN_CAPACITY_TEST=1 go test -run Test5MNodeCapacity -v

Project Structure

graphdb/
├── cmd/
│   ├── server/          # REST API server (the production binary)
│   ├── cli/             # Interactive CLI
│   ├── tui/             # Terminal UI
│   ├── graphdb-admin/   # Security/admin CLI (login, mint-token, keys, audit)
│   ├── benchmark-*/     # Performance benchmarks
├── pkg/                 # 37 packages; the largest:
│   ├── storage/         # Graph storage engine (sharded in-memory + WAL + snapshots + LSM)
│   ├── query/           # Cypher-like query language (lexer, parser, executor)
│   ├── api/             # REST API server, auth, middleware
│   ├── graphql/         # GraphQL API
│   ├── algorithms/      # Graph algorithms
│   ├── vector/          # HNSW vector indexes
│   ├── search/          # Full-text search
│   └── retrieval/       # Graph-augmented retrieval (/v1/retrieve)
├── clients/python/      # First-party Python SDK
├── workers/graphdb-client/  # First-party TypeScript client (Cloudflare Workers)
└── docs/                # Guides, API reference, design docs

Configuration

Server Options

./bin/server --help

Flags:
  --port int        HTTP server port (default 8080)
  --data string     Data directory (default "./data/server")

Storage Configuration

Default settings in code (customizable):

opts := storage.Options{
    MemTableSize:  64 * 1024 * 1024,  // 64MB
    BlockSize:     4096,               // 4KB
    CacheSize:     100,                // 100 blocks
    BloomFPR:      0.01,               // 1% false positive rate
    BatchSize:     100,                // WAL batch size
    FlushInterval: 100 * time.Microsecond,
}

Testing

# Run all tests
go test ./...

# Test specific package
go test ./pkg/storage
go test ./pkg/algorithms
go test ./pkg/query

# Run with race detector
go test -race ./...

# Verbose output
go test -v ./...

# Run capacity test
cd pkg/storage
RUN_CAPACITY_TEST=1 go test -run Test5MNodeCapacity -v

TUI Features

The Terminal UI (built with Bubble Tea, Bubbles, and Lipgloss) provides:

1. Dashboard View

   • Real-time node/edge counts
   • Uptime tracking
   • Query statistics
   • Quick action guide

2. Nodes View

   • Table-based node browser
   • Keyboard navigation (↑/↓, j/k)
   • Display node IDs, labels, properties

3. Query View

   • Interactive query input
   • Execute Cypher-like queries
   • Display results with success/error messages
   • Query examples and syntax help

4. Graph View

   • ASCII art graph visualization
   • Shows node connections
   • Displays relationship types
   • Handles large graphs gracefully

5. Metrics View

   • Live PageRank computation
   • Top nodes by score
   • Visual bar charts
   • Performance metrics

Keyboard Controls:

• Tab / Shift+Tab - Navigate views
• ↑/↓ or j/k - Navigate lists
• Enter - Execute query
• q or Ctrl+C - Quit

Advanced Features

Temporal Graphs

Query which edges existed at a specific point in time:

tq := storage.NewTemporalQuery(graph)

// Edges attached to a node at a timestamp
edges, _ := tq.GetEdgesAtTime(nodeID, timestamp)

// Edges within a time range
ranged, _ := tq.GetEdgesInTimeRange(nodeID, start, end)

Graph Partitioning Primitives

Hash- and range-based partitioning helpers for operator-managed sharding:

p := partition.NewHashPartition(partitionCount)
idx := p.GetPartition(nodeID)

Contributing

Contributions are welcome! Areas for improvement:

• Additional graph algorithms (community detection variants, centrality measures)
• Query language features (aggregations, subqueries, UNION)
• Storage optimizations (compression, tiered storage)
• Distributed consensus (Raft, Paxos)
• Web-based UI (React/Vue dashboard)
• Additional data types (geospatial, full-text search)

License

GraphDB is released under the MIT License.

Community Edition (Free)

• All core features
• Unlimited nodes and edges
• Full API access
• Open source (MIT)
• Community support (GitHub Issues)
• Use for personal projects, open source, evaluation

Professional Edition ($49/month)

• Everything in Community
• Commercial use license
• Email support (48h response)
• Priority bug fixes
• Performance consultation

Enterprise Edition ($299/month)

• Everything in Professional
• Priority support (24h response)
• Architecture consultation
• Early access to distributed features
• Custom SLA available

For commercial licensing details, open an issue on GitHub.

Acknowledgments

Built with:

• Bubble Tea - TUI framework
• Bubbles - TUI components
• Lipgloss - Terminal styling

Roadmap

• Core graph storage (nodes, edges, properties)
• LSM-tree persistent storage
• Write-ahead logging (with payload encryption)
• Property indexes
• Graph algorithms (PageRank, centrality, community)
• Cypher-like query language
• REST + GraphQL API servers
• Interactive CLI + TUI
• Vector search (HNSW) + hybrid retrieval (/v1/retrieve)
• Full-text search
• Multi-tenancy (auth, quotas, isolation)
• Temporal graphs
• Multi-platform release binaries + Docker Hub images
• First-party Python SDK and TypeScript (Workers) client
• Distributed consensus / sharded writes (multi-quarter; single-node by design today)
• Query optimizer
• Geospatial queries
• Web-based dashboard

Why GraphDB?

Built for BL Pay, a next-generation payment platform that needed to:

• Map trust networks between users in real-time
• Detect fraud patterns across payment relationships
• Handle high-volume transaction graph updates
• Scale efficiently with minimal infrastructure

Use cases perfect for GraphDB:

• Fraud detection & prevention
• Social networks & trust graphs
• Payment network analysis
• Knowledge graphs for AI/LLM
• Recommendation engines
• IoT sensor networks
• Real-time analytics

---

Built with Go

For questions, issues, or feature requests, please open an issue on GitHub.

Try it now: docker run -p 8080:8080 dd0wney/graphdb:latest

Documentation

Overview

Package enterprise provides enterprise-grade validation tests for Fortune 500 deployment readiness.

This framework demonstrates testing patterns for: 1. Multi-tenancy isolation 2. SSO/OIDC integration 3. Backup/restore cycles 4. Bulk import/export 5. Scale testing (10M+ nodes) 6. Lock contention analysis

All tests follow table-driven patterns and measure exact metrics required for commercial readiness.

Index

• func BenchmarkComparison(b *testing.B)
• func BenchmarkConcurrentWrites(b *testing.B)
• func BenchmarkImportRate(b *testing.B)
• func BenchmarkLockContention(b *testing.B)
• func BenchmarkMultiTenantQueries(b *testing.B)
• func BenchmarkRestoreTime(b *testing.B)
• func BenchmarkScaleTest(b *testing.B)
• func BenchmarkTokenValidation(b *testing.B)
• type PerformanceBudget
  • func (pb *PerformanceBudget) CheckBudget(actualQueryP95 int64, actualWriteP99 int64, actualMemLeak int64, ...) bool
• type TestSuite
  • func (ts *TestSuite) TestBackupRestoreCycle(t *testing.T)
  • func (ts *TestSuite) TestDeadlockDetection(t *testing.T)
  • func (ts *TestSuite) TestImportExport(t *testing.T)
  • func (ts *TestSuite) TestMultiTenantIsolation(t *testing.T)
  • func (ts *TestSuite) TestOIDCFlow(t *testing.T)

Functions

func BenchmarkComparison

func BenchmarkComparison(b *testing.B)

ComparisonBenchmark compares performance across scales

func BenchmarkConcurrentWrites

func BenchmarkConcurrentWrites(b *testing.B)

BenchmarkConcurrentWrites measures write scaling efficiency

func BenchmarkImportRate

func BenchmarkImportRate(b *testing.B)

BenchmarkImportRate measures bulk import throughput

func BenchmarkLockContention

func BenchmarkLockContention(b *testing.B)

LockContentionTest measures global lock impact

func BenchmarkMultiTenantQueries

func BenchmarkMultiTenantQueries(b *testing.B)

BenchmarkMultiTenantQueries measures query latency with 50 concurrent tenants

func BenchmarkRestoreTime

func BenchmarkRestoreTime(b *testing.B)

BenchmarkRestoreTime measures RTO (Recovery Time Objective)

func BenchmarkScaleTest

func BenchmarkScaleTest(b *testing.B)

ScaleTest verifies linear scaling up to 10M nodes

func BenchmarkTokenValidation

func BenchmarkTokenValidation(b *testing.B)

BenchmarkTokenValidation measures cache performance

Types

type PerformanceBudget

type PerformanceBudget struct {
	QueryP95Ms        int64
	WriteLatencyP99Ms int64
	MemoryLeakPerHour int64
	GCPauseMaxMs      int64
	LockFreeRatio     float64
	DeadlockCount     int64
}

ValidatePerformanceBudget ensures metrics meet SLOs

func (*PerformanceBudget) CheckBudget

func (pb *PerformanceBudget) CheckBudget(
	actualQueryP95 int64,
	actualWriteP99 int64,
	actualMemLeak int64,
	actualGCMax int64,
	actualLockFree float64,
	actualDeadlock int64) bool

CheckBudget validates actual metrics against requirements

type TestSuite

type TestSuite struct {
	// contains filtered or unexported fields
}

TestSuite provides enterprise validation testing

func (*TestSuite) TestBackupRestoreCycle

func (ts *TestSuite) TestBackupRestoreCycle(t *testing.T)

BackupRestoreCycleTest verifies data integrity across backup/restore

func (*TestSuite) TestDeadlockDetection

func (ts *TestSuite) TestDeadlockDetection(t *testing.T)

DeadlockDetectionTest ensures no deadlocks under concurrent load

func (*TestSuite) TestImportExport

func (ts *TestSuite) TestImportExport(t *testing.T)

ImportExportTest verifies bulk data round-trip

func (*TestSuite) TestMultiTenantIsolation

func (ts *TestSuite) TestMultiTenantIsolation(t *testing.T)

TenantIsolationTest verifies cross-tenant data cannot leak

func (*TestSuite) TestOIDCFlow

func (ts *TestSuite) TestOIDCFlow(t *testing.T)

OIDCFlowTest verifies complete OIDC authentication