Skip to content
ParticleDB

gRPC

ParticleDB ships a single gRPC service defined in proto/particledb.proto. The current server exposes SQL execution, batch execution, client-streaming inserts, CDC subscriptions, and health checks on the gRPC port.

Endpoint

Section titled “Endpoint”
127.0.0.1:26257

Configure it with:

Terminal window
particledb start --grpc-addr 0.0.0.0:26257

What Is Actually Served

Section titled “What Is Actually Served”

The current protobuf package is particledb.v1, and the server implements one service:

service ParticleDB {
  rpc ExecuteSQL(ExecuteSqlRequest) returns (ExecuteSqlResponse);
  rpc BatchExecute(BatchExecuteRequest) returns (BatchExecuteResponse);
  rpc StreamInsert(stream InsertRowRequest) returns (InsertResult);
  rpc Subscribe(SubscribeRequest) returns (stream ChangeEvent);
  rpc Health(HealthRequest) returns (HealthResponse);
}

There is no particledb.Admin / particledb.Query split in the current proto.

Proto Files

Section titled “Proto Files”

The main entrypoint is:

proto/particledb.proto

Generate stubs from that file:

Terminal window
protoc --go_out=. --go-grpc_out=. proto/particledb.proto
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. proto/particledb.proto

grpcurl

Section titled “grpcurl”

The server does not expose gRPC reflection today, so use -import-path and -proto.

Health

Section titled “Health”
Terminal window
grpcurl -plaintext \
  -import-path proto \
  -proto proto/particledb.proto \
  -d '{}' \
  localhost:26257 \
  particledb.v1.ParticleDB/Health

Example response:

{
  "status": "OK",
  "version": "0.1.0"
}

Execute SQL

Section titled “Execute SQL”
Terminal window
grpcurl -plaintext \
  -import-path proto \
  -proto proto/particledb.proto \
  -d '{"sql":"SELECT 1 AS ok"}' \
  localhost:26257 \
  particledb.v1.ParticleDB/ExecuteSQL

Example response:

{
  "columns": [
    { "name": "ok", "type": "Int64" }
  ],
  "rows": [
    {
      "values": [
        { "intValue": "1" }
      ]
    }
  ],
  "rowsAffected": "1"
}

Batch execute

Section titled “Batch execute”
Terminal window
grpcurl -plaintext \
  -import-path proto \
  -proto proto/particledb.proto \
  -d '{"statements":["CREATE TABLE demo (id BIGINT PRIMARY KEY)","INSERT INTO demo VALUES (1)","SELECT * FROM demo"]}' \
  localhost:26257 \
  particledb.v1.ParticleDB/BatchExecute

Message Shapes

Section titled “Message Shapes”
message ExecuteSqlRequest {
  string sql = 1;
  repeated Value params = 2;
}


message ExecuteSqlResponse {
  repeated Column columns = 1;
  repeated Row rows = 2;
  int64 rows_affected = 3;
  string error = 4;
}


message HealthResponse {
  string status = 1;
  string version = 2;
}

Value is a protobuf oneof supporting integers, floats, strings, booleans, nulls, and bytes.

Authentication

Section titled “Authentication”

When --auth-method trust or --no-auth is used, gRPC calls are accepted without credentials.

When auth is enabled, the current server expects:

Authorization: Bearer <username>:<password>

Example:

Terminal window
grpcurl \
  -cacert ca.crt \
  -H "authorization: Bearer admin:secret" \
  -import-path proto \
  -proto proto/particledb.proto \
  -d '{}' \
  localhost:26257 \
  particledb.v1.ParticleDB/Health

TLS

Section titled “TLS”

The gRPC endpoint supports direct TLS with the same certificate/key pair used by the PG wire and Redis listeners:

Terminal window
particledb start \
  --grpc-addr 0.0.0.0:26257 \
  --tls-cert /path/to/server.crt \
  --tls-key /path/to/server.key

What To Use gRPC For

Section titled “What To Use gRPC For”
  • Typed SQL execution without going through PG wire drivers
  • Batch execution from generated clients
  • Client-streaming inserts
  • CDC subscriptions
  • Health probes from gRPC-native environments

For normal application SQL and ORM compatibility, the PostgreSQL wire protocol is still the most ergonomic default.

Next Steps

Section titled “Next Steps”