grafeo-server¶

Standalone HTTP server and web UI for the Grafeo graph database.

GitHub Docker Hub

Overview¶

grafeo-server wraps the Grafeo engine in a REST API, GQL Wire Protocol (gRPC) and Bolt v5.x wire protocol, turning it from an embeddable library into a standalone database server. Pure Rust, single binary. Available in four tiers to match different deployment needs.

• REST API with auto-commit and explicit transaction modes
• GQL Wire Protocol (gRPC) on port 7688 for binary wire-protocol clients
• Bolt v5.x on port 7687 for Neo4j driver compatibility
• Multi-language queries: GQL, Cypher, GraphQL, Gremlin, SPARQL, SQL/PGQ
• Admin API: database stats, WAL management, integrity validation, index management
• Search API: vector (KNN/HNSW), text (BM25) and hybrid search
• Batch queries with atomic rollback
• WebSocket streaming for interactive query execution
• Web UI (Studio) for interactive query exploration
• ACID transactions with session-based lifecycle
• In-memory or persistent: omit data directory for ephemeral, set it for durable storage

Docker Image Tiers¶

Four tiers are published to Docker Hub on every release:

Versioned tags follow the pattern: 0.4.6, 0.4.6-gwp, 0.4.6-bolt, 0.4.6-full.

GWP¶

GQL-only gRPC wire protocol. Minimal footprint for machine-to-machine communication. Ideal for:

• Sidecar containers
• CI/CD test environments
• Edge deployments

docker run -p 7688:7688 grafeo/grafeo-server:gwp --data-dir /data

Bolt¶

Cypher-only Bolt v5 wire protocol. Compatible with existing Neo4j drivers (Python neo4j, JavaScript neo4j-driver, etc.).

docker run -p 7687:7687 grafeo/grafeo-server:bolt --data-dir /data

Standard (default)¶

HTTP REST API with all query languages, graph algorithms and the Studio web UI. This is the default grafeo-server:latest image.

docker run -p 7474:7474 grafeo/grafeo-server

Full¶

Everything in standard plus GWP, Bolt, AI/search features, ONNX embedding generation, authentication (bearer token, HTTP Basic), TLS and JSON Schema validation. Production-ready with all features and security built in.

docker run -p 7474:7474 -p 7687:7687 -p 7688:7688 grafeo/grafeo-server:full

Quick Start¶

Docker¶

# In-memory (ephemeral)
docker run -p 7474:7474 grafeo/grafeo-server

# Persistent storage
docker run -p 7474:7474 -v grafeo-data:/data grafeo/grafeo-server --data-dir /data

Docker Compose¶

docker compose up -d

Server at http://localhost:7474. Web UI at http://localhost:7474/studio/.

Binary¶

grafeo-server --data-dir ./mydata    # persistent
grafeo-server                        # in-memory

API Endpoints¶

Query (auto-commit)¶

curl -X POST http://localhost:7474/query \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (p:Person) RETURN p.name, p.age"}'

Transactions¶

# Begin
SESSION=$(curl -s -X POST http://localhost:7474/tx/begin | jq -r .session_id)

# Execute
curl -X POST http://localhost:7474/tx/query \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: $SESSION" \
  -d '{"query": "INSERT (:Person {name: '\''Alix'\''})"}'

# Commit (or POST /tx/rollback)
curl -X POST http://localhost:7474/tx/commit \
  -H "X-Session-Id: $SESSION"

WebSocket¶

Connect to ws://localhost:7474/ws for interactive query execution:

{"type": "query", "id": "q1", "query": "MATCH (n) RETURN n", "language": "gql"}

Admin¶

Database introspection, maintenance and index management:

Search¶

Vector, text and hybrid search (requires vector-index, text-index, hybrid-search features):

GQL Wire Protocol (GWP)¶

The gwp and full builds include a gRPC-based binary wire protocol on port 7688. All query, transaction, database, admin and search operations are available over gRPC. Configure with --gwp-port or GRAFEO_GWP_PORT.

Bolt v5.x (BOLTR)¶

The bolt and full builds include a Bolt v5.x wire protocol on port 7687, compatible with Neo4j drivers. Configure with --bolt-port or GRAFEO_BOLT_PORT.

Health & Feature Discovery¶

curl http://localhost:7474/health

The health endpoint reports which features are compiled into the running server:

{
  "status": "ok",
  "features": {
    "languages": ["gql", "cypher", "sparql", "gremlin", "graphql", "sql-pgq"],
    "engine": ["parallel", "wal", "spill", "mmap"],
    "server": ["gwp"]
  }
}

Configuration¶

Environment variables (prefix GRAFEO_), overridden by CLI flags:

Authentication (feature: auth)¶

TLS (feature: tls)¶

Feature Flags (building from source)¶

When building from source, Cargo feature flags control which capabilities are compiled in:

Individual features can also be mixed:

# GWP + Bolt (both wire protocols, no HTTP)
cargo build --release --no-default-features --features "gwp,bolt,gql,cypher,storage"

# HTTP API with auth
cargo build --release --features auth

See the grafeo-server README for the complete feature flag reference.

Wire Protocols¶

grafeo-server supports two binary wire protocols for high-performance client-server communication. Both are standalone Rust crates that any database can adopt via backend traits.

GWP (GQL Wire Protocol)¶

GitHub crates.io

A pure Rust gRPC wire protocol for GQL (ISO/IEC 39075), the international standard query language for property graphs. GWP is the primary wire protocol for grafeo-server, available on port 7688 by default.

Key features:

• Full GQL type system including extended numerics (BigInteger, BigFloat, Decimal)
• Six gRPC services: Session, GQL, Catalog, Admin, Search, Health
• Server-side streaming for large result sets
• GQLSTATUS codes for structured error reporting per the ISO standard
• Pluggable backend via GqlBackend trait
• Optional TLS via rustls
• Idle session reaping and graceful shutdown

Client bindings:

Status: v0.1.6, active development. The type system and service architecture are stable. Recent work has focused on aligning the catalog hierarchy (catalog > schema > graph) with the GQL specification.

BOLTR (Bolt Wire Protocol)¶

GitHub crates.io

A pure Rust implementation of the Bolt v5.x wire protocol, the binary protocol used by Neo4j for client-server communication. BOLTR enables compatibility with existing Neo4j drivers and tooling.

Key features:

• Full Bolt v5.1-5.4 protocol support with PackStream binary encoding
• Complete Bolt type system: scalars, graph elements, temporal and spatial types
• TCP chunked message framing
• Both server (BoltBackend trait) and client (BoltConnection, BoltSession) APIs
• Pluggable authentication via AuthValidator trait
• Optional TLS via tokio-rustls
• ROUTE message support for cluster-aware drivers
• Graceful connection draining on shutdown

Status: v0.1.1, active development. Spec-complete for Bolt 5.1-5.4 including ROUTE and TELEMETRY messages. Rust-only at this time (existing Neo4j drivers in other languages work out of the box).

Protocol Comparison¶

When to Use¶

Requirements¶

• Docker (recommended) or Rust toolchain for building from source

License¶

Apache-2.0