Connectivity Overview

ParticleDB exposes five network protocols, each optimized for different workloads. The PostgreSQL wire protocol is the primary interface for SQL queries; the other protocols serve specialized roles.

Protocol Summary

Protocol	Default Port	Use Case	Client Libraries
PostgreSQL Wire	5432	SQL queries, transactions, prepared statements, pipeline mode	Any PostgreSQL driver (psycopg2, pg, pgx, JDBC, Npgsql, tokio-postgres, …)
gRPC	26257	Admin operations, inter-node communication, streaming	Any gRPC client (grpcurl, language-specific stubs)
HTTP API	8080	REST queries, KV operations, health checks, dashboard, metrics	curl, any HTTP client
Redis RESP	6379	Key-value operations, caching workloads	Any Redis client (redis-py, ioredis, redis-rs, …)
WebSocket	8081	Real-time subscriptions, live query results	Any WebSocket client

Quick Connection Examples

PostgreSQL Wire (primary)

# psql
psql -h localhost -p 5432 -d main

# Connection string (works with any PG driver)
postgresql://localhost:5432/main

# Unix socket (lowest latency)
psql -h /tmp -d main

gRPC

grpcurl -plaintext localhost:26257 particledb.Admin/GetStatus

HTTP API

# Health check
curl http://localhost:8080/health

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

# KV get
curl -X POST http://localhost:8080/v1/kv/get \
  -H "Content-Type: application/json" \
  -d '{"key": "user:1001", "table": "kv_store"}'

# KV set
curl -X POST http://localhost:8080/v1/kv/set \
  -H "Content-Type: application/json" \
  -d '{"key": "user:1001", "value": "Alice", "table": "kv_store"}'

# Server version
curl http://localhost:8080/v1/version

Redis RESP

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

Port Configuration

All ports are configurable via CLI flags, config file, or environment variables:

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
gRPC	--grpc-addr	network.grpc_addr	PDB_GRPC_ADDR
HTTP	--http-addr	network.http_addr	PDB_HTTP_ADDR
Redis	—	network.redis_port	PDB_REDIS_PORT

See Configuration for the full reference.

Security

All protocols support TLS encryption and authentication. See TLS / Security for setup instructions.

Protocol	TLS	Auth Methods
PG Wire	Yes	trust, password, md5
gRPC	Yes	Token-based
HTTP	Yes	Bearer token, Basic auth
Redis RESP	Yes	AUTH command
WebSocket	Yes (wss://)	Token in handshake

Choosing a Protocol

• SQL workloads (OLTP and OLAP) — Use the PostgreSQL wire protocol. It supports the full SQL dialect, transactions, prepared statements, binary format, and pipeline mode for maximum throughput.
• Admin and ops — Use gRPC for cluster management, node status, and backup operations.
• Dashboards and lightweight integrations — Use the HTTP API for simple query execution, health checks, and Prometheus metrics.
• Key-value workloads — Use the Redis RESP protocol with any Redis client library for GET/SET/SCAN operations.
• Real-time updates — Use WebSocket for live query subscriptions and change notifications.

Next Steps

• PostgreSQL Wire Protocol — Full protocol details
• gRPC — Admin and streaming API
• HTTP API — REST endpoints
• TLS / Security — Encryption and authentication
• ORM Compatibility — Tested ORMs and frameworks