TLS / Security

ParticleDB supports direct TLS on the PostgreSQL wire, gRPC, and Redis listeners. The built-in HTTP server is plain HTTP today, so if you expose /v1/*, /health*, or /metrics externally, terminate TLS in your reverse proxy or ingress.

TLS Configuration

Server-side TLS

1. Generate or obtain certificates

   openssl req -x509 -newkey rsa:4096 -sha256 -days 365 \
     -nodes -keyout server.key -out server.crt \
     -subj "/CN=particledb" \
     -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

2. Set file permissions

   chmod 600 server.key
   chmod 644 server.crt

3. Start ParticleDB with TLS

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

   In config files, the server reads TLS paths from the network section:

   [network]
   tls_cert_path = "/path/to/server.crt"
   tls_key_path = "/path/to/server.key"

Client Connections With TLS

psql "postgresql://localhost:5432/particledb?sslmode=require"
psql "postgresql://localhost:5432/particledb?sslmode=verify-full&sslrootcert=ca.crt"

import psycopg2

conn = psycopg2.connect(
    host="localhost",
    port=5432,
    dbname="particledb",
    sslmode="require",
    sslrootcert="/path/to/ca.crt",
)

Authentication

ParticleDB supports three auth modes for PG wire and Redis:

Method	Description
trust	No password required
password	Cleartext password exchange
md5	MD5 challenge-response

Configure it with:

particledb start --auth-method password --pg-password mysecretpassword
particledb start --auth-method md5 --pg-password mysecretpassword

Per-Protocol Notes

PostgreSQL Wire

• Direct TLS supported
• Auth: trust, password, md5

gRPC

• Direct TLS supported
• Auth header format when enabled:

Authorization: Bearer <username>:<password>

Example:

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

HTTP API

• No built-in HTTPS listener today
• No PG/gRPC-style request authentication on /v1/*
• Recommended production pattern: terminate TLS and enforce auth in your reverse proxy / ingress

Example:

client -> https://db.example.com -> reverse proxy -> http://127.0.0.1:8080

Redis RESP

• Direct TLS supported
• Auth via AUTH

redis-cli -p 6379 --tls --cacert ca.crt
AUTH mysecretpassword

Security Best Practices

1. Enable TLS in production for PG wire, gRPC, and Redis.

2. Do not use trust outside local development.

3. Front the built-in HTTP server with your normal reverse proxy if you need HTTPS, auth, rate limiting, or WAF behavior.

4. Bind listeners to specific interfaces when possible.

5. Use Unix sockets for local PG connections when you want the lowest-overhead trusted path.

6. Enable audit logging if you need an in-database activity trail:

   particledb start --audit-log

Next Steps

• Configuration — Full server configuration reference
• PostgreSQL Wire Protocol — Client compatibility and auth behavior
• Connectivity Overview — All live protocols and ports