Connectivity Overview

ParticleDB currently exposes four live server protocols: PostgreSQL wire, gRPC, HTTP, and Redis RESP. The repo also includes WebSocket protocol definitions, but the default server path today is HTTP SSE streaming rather than a production WebSocket upgrade endpoint.

Protocol Summary

Protocol	Default Port	Use Case	Client Libraries
PostgreSQL Wire	5432	SQL queries, transactions, prepared statements, pipeline mode	Any PostgreSQL driver
gRPC	26257	Typed SQL RPCs, batch execution, bulk insert, CDC, health	grpcurl, generated stubs
HTTP API	8080	JSON SQL, KV helpers, health, status page	curl, fetch, any HTTP client
Redis RESP	6379	Key-value and Redis-style data structures	Any Redis client
SSE SQL streaming	8080	Incremental SQL results over HTTP	curl -N, browser EventSource, fetch-based clients

Quick Connection Examples

PostgreSQL Wire

psql -h localhost -p 5432 -U particledb -d particledb

gRPC

grpcurl -plaintext \
  -import-path proto \
  -proto proto/particledb.proto \
  -d '{}' \
  localhost:26257 \
  particledb.v1.ParticleDB/Health

HTTP API

curl http://localhost:8080/health

curl -X POST http://localhost:8080/v1/sql \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT COUNT(*) AS total FROM products"}'

Redis RESP

redis-cli -p 6379
> SET user:1001 '{"name":"Alice"}'
> GET user:1001

Port Configuration

Protocol	CLI Flag	Config Key	Env Variable
PG Wire	--pg-addr	network.pg_addr	PDB_PG_ADDR
PG Unix Socket	--pg-unix-socket	network.pg_unix_path	PDB_PG_UNIX_PATH
HTTP	--http-addr	network.http_addr	PDB_HTTP_ADDR
gRPC	--grpc-addr	network.grpc_addr	PDB_GRPC_ADDR
Redis	(config/env only)	network.redis_port	PDB_REDIS_PORT
Metrics	--metrics-port	network.metrics_port	PDB_METRICS_PORT
Health	--health-port	network.health_port	PDB_HEALTH_PORT

See Configuration for the full reference.

Security

PG wire, gRPC, and Redis support direct TLS from the server. The built-in HTTP server is plain HTTP today, so use a reverse proxy or ingress if you need HTTPS or request-layer auth for /v1/*.

Protocol	TLS	Auth
PG Wire	Yes	trust, password, md5
gRPC	Yes	Authorization: Bearer <username>:<password> when auth is enabled
HTTP	Via reverse proxy	Front with your normal proxy/gateway if needed
Redis RESP	Yes	AUTH
SSE SQL streaming	Via reverse proxy	Same as the HTTP server

Choosing a Protocol

• Applications and ORMs — Use PostgreSQL Wire.
• Generated clients, CDC, and typed RPCs — Use gRPC.
• Simple curl/fetch integrations — Use the HTTP API.
• Redis-style caching/data structures — Use Redis RESP.
• Incremental result delivery over HTTP — Use /v1/sql/stream today.

Next Steps

• PostgreSQL Wire Protocol — Full protocol details
• gRPC — Protobuf service details
• HTTP API — JSON SQL, KV, health, and SSE
• TLS / Security — TLS/auth details by protocol
• ORM Compatibility — Tested frameworks