gRPC

ParticleDB exposes a gRPC API on port 26257 for admin operations, inter-node communication, and streaming workloads. The gRPC interface is designed for programmatic control and high-throughput streaming — use the PostgreSQL wire protocol for SQL queries.

Endpoint

localhost:26257

Configure with:

particledb start --grpc-addr 0.0.0.0:26257

Proto File

The ParticleDB gRPC service definitions are available in the repository:

proto/particledb.proto

Generate client stubs for your language using protoc or buf:

# Generate Go stubs
protoc --go_out=. --go-grpc_out=. proto/particledb.proto

# Generate Python stubs
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. proto/particledb.proto

Service Overview

service Admin {
  // Server status and health
  rpc GetStatus (StatusRequest) returns (StatusResponse);

  // Cluster information
  rpc GetClusterInfo (ClusterInfoRequest) returns (ClusterInfoResponse);

  // Backup and restore
  rpc CreateBackup (BackupRequest) returns (BackupResponse);
  rpc RestoreBackup (RestoreRequest) returns (RestoreResponse);

  // Table management
  rpc ListTables (ListTablesRequest) returns (ListTablesResponse);
  rpc GetTableStats (TableStatsRequest) returns (TableStatsResponse);
}

service Query {
  // Execute a SQL query and return results
  rpc Execute (QueryRequest) returns (QueryResponse);

  // Stream large result sets
  rpc ExecuteStream (QueryRequest) returns (stream QueryRow);

  // Bulk insert via streaming
  rpc BulkInsert (stream InsertRow) returns (BulkInsertResponse);
}

Usage Examples

grpcurl

# Check server status
grpcurl -plaintext localhost:26257 particledb.Admin/GetStatus

# List tables
grpcurl -plaintext localhost:26257 particledb.Admin/ListTables

# Execute a query
grpcurl -plaintext -d '{"sql": "SELECT COUNT(*) FROM products"}' \
  localhost:26257 particledb.Query/Execute

# Get table statistics
grpcurl -plaintext -d '{"table_name": "products"}' \
  localhost:26257 particledb.Admin/GetTableStats

Python

import grpc
import particledb_pb2
import particledb_pb2_grpc

channel = grpc.insecure_channel("localhost:26257")
admin_stub = particledb_pb2_grpc.AdminStub(channel)

# Get server status
status = admin_stub.GetStatus(particledb_pb2.StatusRequest())
print(f"Version: {status.version}")
print(f"Uptime: {status.uptime_seconds}s")
print(f"Connections: {status.active_connections}")

# List tables
tables = admin_stub.ListTables(particledb_pb2.ListTablesRequest())
for table in tables.tables:
    print(f"{table.name}: {table.row_count} rows")

Go

import (
    "context"
    "log"

    pb "github.com/particledb/particledb-go/proto"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

conn, err := grpc.NewClient("localhost:26257",
    grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

client := pb.NewAdminClient(conn)
status, err := client.GetStatus(context.Background(), &pb.StatusRequest{})
if err != nil {
    log.Fatal(err)
}
log.Printf("Version: %s, Uptime: %ds", status.Version, status.UptimeSeconds)

Streaming

Server-side streaming (large result sets)

query_stub = particledb_pb2_grpc.QueryStub(channel)

# Stream results row by row — no memory pressure for large result sets
request = particledb_pb2.QueryRequest(sql="SELECT * FROM large_table")
for row in query_stub.ExecuteStream(request):
    print(row.values)

Client-side streaming (bulk insert)

def generate_rows():
    for i in range(1_000_000):
        yield particledb_pb2.InsertRow(
            table="events",
            values=[str(i), f"event_{i}", "1234567890"]
        )

response = query_stub.BulkInsert(generate_rows())
print(f"Inserted {response.rows_inserted} rows")

TLS

Enable TLS for the gRPC endpoint:

particledb start \
  --tls-cert /path/to/server.crt \
  --tls-key /path/to/server.key

Connect with TLS:

credentials = grpc.ssl_channel_credentials(
    root_certificates=open("ca.crt", "rb").read()
)
channel = grpc.secure_channel("localhost:26257", credentials)

grpcurl -cacert ca.crt localhost:26257 particledb.Admin/GetStatus

Authentication

When authentication is enabled, include credentials in the gRPC metadata:

metadata = [("authorization", "Bearer <token>")]
status = admin_stub.GetStatus(
    particledb_pb2.StatusRequest(),
    metadata=metadata
)

Next Steps

• HTTP API — REST endpoints for simpler integrations
• PostgreSQL Wire Protocol — Primary SQL interface
• TLS / Security — Full security configuration