Skip to content
ParticleDB
Release candidateParticleDB 1.1.19-rc.17 is not yet GA or ready for production data.Release status →

TLS and authentication

This page shows how to encrypt connections with TLS and how clients authenticate on each interface. With a certificate configured, ParticleDB terminates TLS itself on SQL clients, native clients, gRPC, Redis and HTTP. The dedicated health-check port and the Prometheus exporter port stay plain HTTP.

  1. Generate or obtain certificates

    For a production deployment, use a certificate from your CA. For testing, create a local CA and a server certificate signed by it:

    Terminal window
    # A local certificate authority
    openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
    -keyout ca.key -out ca.crt -subj "/CN=ParticleDB local CA"
    # A server certificate for localhost, signed by that CA
    openssl req -newkey rsa:4096 -sha256 -nodes \
    -keyout server.key -out server.csr -subj "/CN=localhost"
    printf "subjectAltName=DNS:localhost,IP:127.0.0.1\n" > san.ext
    openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
    -days 365 -sha256 -extfile san.ext -out server.crt

    Clients verify the server against ca.crt. A single self-signed certificate used as its own root works with psql, but pdb-cli and other clients with strict verification reject it (CA used as end entity), so prefer the two-step form above.

  2. Set file permissions

    Terminal window
    chmod 600 server.key ca.key
    chmod 644 server.crt ca.crt
  3. Start ParticleDB with TLS

    Terminal window
    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"

Once a certificate is configured, the TCP listeners that use it accept only TLS connections on their configured addresses. A PostgreSQL client that does not request TLS (sslmode=disable) is refused with SQLSTATE 08004 (server requires TLS); plain-text native client, gRPC, Redis and HTTP connections to those ports fail as well. Local Unix-socket connections are not affected.

Terminal window
# Encrypted, server not verified
psql "postgresql://postgres@localhost:5432/particledb?sslmode=require"
# Encrypted and verified against your CA (host name must match the certificate)
psql "postgresql://postgres@localhost:5432/particledb?sslmode=verify-full&sslrootcert=ca.crt"
# Native wire
pdb-cli -h localhost -U postgres --sslmode verify-full --sslrootcert ca.crt

\conninfo in psql shows the negotiated protocol, for example SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, …).

import psycopg2
conn = psycopg2.connect(
host="localhost",
port=5432,
dbname="particledb",
user="postgres",
password="secret",
sslmode="verify-full",
sslrootcert="/path/to/ca.crt",
)

Authentication is on by default. The same users and passwords apply to every protocol; --auth-method chooses how SQL client clients prove their password:

Method Description
scram-sha-256 Recommended; safe with or without TLS
password (default) Cleartext password exchange; requires TLS. refused over a non-TLS connection
trust No password on any protocol. local development only
md5 Disabled unless you also pass --allow-md5-auth; legacy clients only
Terminal window
particledb start --auth-method scram-sha-256 --pg-password-file /etc/particledb/pg_password

--pg-password / --pg-password-file set the password of the initial superuser (postgres unless you change it with --pg-username). Create further users with CREATE ROLE … LOGIN PASSWORD ….

  • Direct TLS supported
  • Auth: scram-sha-256, password, trust (and md5 with --allow-md5-auth)
  • Direct TLS supported
  • When authentication is on, send HTTP Basic credentials in the authorization metadata: Basic <base64 of username:password>. A Bearer <username>:<password> header is not accepted. Health needs no credentials.

Example:

Terminal window
grpcurl \
-cacert ca.crt \
-H "authorization: Basic $(printf 'postgres:secret' | base64)" \
-proto particledb.proto \
-d '{}' \
localhost:7173 \
particledb.v1.ParticleDB/Health
  • With --tls-cert / --tls-key, the main HTTP port serves HTTPS only (curl --cacert ca.crt https://localhost:7173/health). The dedicated health-check port and the Prometheus exporter stay plain HTTP.
  • When authentication is on, /v1/* endpoints (except /v1/version) require HTTP Basic credentials; /metrics on the HTTP port requires a superuser.
  • --require-tls-for-credentials refuses HTTP Basic credentials sent over a non-TLS connection (401, credentials require TLS).
  • A reverse proxy or ingress in front of the HTTP port works as well:
client -> https://db.example.com -> reverse proxy -> http://127.0.0.1:7173
  • Direct TLS supported, with the same certificate
  • Authenticates against the same users; pdb-cli takes --sslmode, --sslrootcert, --sslcert and --sslkey
  • Direct TLS supported
  • Authenticate with AUTH <username> <password> (the single-argument AUTH <password> form authenticates as a user named default)
Terminal window
redis-cli -p 6379 --tls --cacert ca.crt --user postgres --pass mysecretpassword
  1. Enable TLS in production for the SQL and native clients, gRPC, Redis, and HTTP.

  2. Do not use trust outside local development.

  3. Front the built-in HTTP server with your normal reverse proxy if you need 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 path; restrict them with --unix-socket-mode 0700 or --unix-socket-require-same-uid.

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

    Terminal window
    particledb start --audit-log

    Each statement is recorded with its user, client address, operation, target and SQL text. Read it with SELECT * FROM __pdb_audit_log. Add --audit-log-selects to record SELECT statements too.

Documentation home · Troubleshooting