For teams building high-throughput, latency-sensitive event-driven systems, we're introducing the Genesis DB gRPC endpoint. Available exclusively in the Enterprise Edition, this new interface provides native Protocol Buffer support, efficient binary serialization, and streaming capabilities alongside our existing HTTP API.

gRPC brings type safety, code generation, and performance benefits to your event sourcing architecture.

Why gRPC?

While our HTTP API remains the easiest way to interact with Genesis DB, gRPC offers distinct advantages for specific use cases:

• Binary serialization with Protocol Buffers for reduced payload sizes
• Strong typing and automatic client code generation
• Server streaming for real-time event observation
• HTTP/2 multiplexing for efficient connection usage
• Native support in Go, Python, Node.js, Java, and more

Configuration

The gRPC server runs on port 50051 by default and can be enabled via environment variables:

Once enabled, the gRPC endpoint provides full access to Genesis DB operations through the genesisdb.GenesisDBService service.

Core Operations

The gRPC API mirrors the HTTP API functionality with methods designed for event store operations:

Event Operations

• Commit Write events to the store with precondition support
• Stream Retrieve events for a subject with filtering options
• Observe Server streaming for real-time event notifications
• Query Execute GDBQL queries (Enterprise only)

Status and Discovery

• Ping Health check (no authentication required)
• GetStatus Detailed server status information
• GetSubjects List all subjects in the store
• GetTypes List all event types

Backup and Compliance

• CreateBackup Export all events
• RestoreBackup Import events from backup
• EraseSubject Delete events for GDPR compliance
• Audit Verify event chain integrity

Authentication

All RPC methods except Ping require authentication via the authorization metadata header. Pass your API token in the request metadata:

md := metadata.New(map[string]string{
    "authorization": "your-api-token",
})
ctx := metadata.NewOutgoingContext(context.Background(), md)

Quick Start with grpcurl

Test the gRPC endpoint quickly using grpcurl:

# Health check
grpcurl -plaintext localhost:50051 genesisdb.GenesisDBService/Ping

# Get server status
grpcurl -plaintext -H "authorization: your-token" \
  localhost:50051 genesisdb.GenesisDBService/GetStatus

# Commit an event
grpcurl -plaintext -H "authorization: your-token" -d '
{
  "events": [{
    "source": "my-app",
    "subject": "/users/123",
    "type": "user.created",
    "data": {"name": "John Doe", "email": "john@example.com"}
  }]
}' localhost:50051 genesisdb.GenesisDBService/Commit

Client Code Generation

Generate strongly-typed client code for your language using the Protocol Buffer compiler:

# Go
protoc --go_out=. --go-grpc_out=. proto/genesisdb.proto

# Python
pip install grpcio-tools
python -m grpc_tools.protoc --python_out=. --grpc_python_out=. \
  proto/genesisdb.proto

# Node.js
npm install @grpc/proto-loader grpc

Closing Thoughts

The gRPC endpoint extends Genesis DB's capabilities for teams that need maximum performance and type safety. Whether you're building microservices that communicate via gRPC or need efficient real-time event streaming, this new interface provides a robust foundation.

The HTTP API remains the recommended starting point for most users. gRPC is there when you need it for performance-critical integrations and polyglot environments.

View the Proto definitions on GitHub

Read the full gRPC documentation