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.
TLS Configuration
Section titled “TLS Configuration”Server-side TLS
Section titled “Server-side TLS”-
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 authorityopenssl 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 CAopenssl 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.extopenssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \-days 365 -sha256 -extfile san.ext -out server.crtClients verify the server against
ca.crt. A single self-signed certificate used as its own root works withpsql, butpdb-cliand other clients with strict verification reject it (CA used as end entity), so prefer the two-step form above. -
Set file permissions
Terminal window chmod 600 server.key ca.keychmod 644 server.crt ca.crt -
Start ParticleDB with TLS
Terminal window particledb start \--tls-cert /path/to/server.crt \--tls-key /path/to/server.keyIn 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.
Client Connections With TLS
Section titled “Client Connections With TLS”# Encrypted, server not verifiedpsql "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 wirepdb-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
Section titled “Authentication”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 |
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 ….
Per-Protocol Notes
Section titled “Per-Protocol Notes”SQL clients
Section titled “SQL clients”- Direct TLS supported
- Auth:
scram-sha-256,password,trust(andmd5with--allow-md5-auth)
- Direct TLS supported
- When authentication is on, send HTTP Basic credentials in the
authorizationmetadata:Basic <base64 of username:password>. ABearer <username>:<password>header is not accepted.Healthneeds no credentials.
Example:
grpcurl \ -cacert ca.crt \ -H "authorization: Basic $(printf 'postgres:secret' | base64)" \ -proto particledb.proto \ -d '{}' \ localhost:7173 \ particledb.v1.ParticleDB/HealthHTTP API
Section titled “HTTP API”- 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;/metricson the HTTP port requires a superuser. --require-tls-for-credentialsrefuses 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:7173Native clients
Section titled “Native clients”- Direct TLS supported, with the same certificate
- Authenticates against the same users;
pdb-clitakes--sslmode,--sslrootcert,--sslcertand--sslkey
Redis clients
Section titled “Redis clients”- Direct TLS supported
- Authenticate with
AUTH <username> <password>(the single-argumentAUTH <password>form authenticates as a user nameddefault)
redis-cli -p 6379 --tls --cacert ca.crt --user postgres --pass mysecretpasswordSecurity Best Practices
Section titled “Security Best Practices”-
Enable TLS in production for the SQL and native clients, gRPC, Redis, and HTTP.
-
Do not use
trustoutside local development. -
Front the built-in HTTP server with your normal reverse proxy if you need rate limiting or WAF behavior.
-
Bind listeners to specific interfaces when possible.
-
Use Unix sockets for local PG connections when you want the lowest-overhead path; restrict them with
--unix-socket-mode 0700or--unix-socket-require-same-uid. -
Enable audit logging if you need an in-database activity trail:
Terminal window particledb start --audit-logEach statement is recorded with its user, client address, operation, target and SQL text. Read it with
SELECT * FROM __pdb_audit_log. Add--audit-log-selectsto recordSELECTstatements too.
Next Steps
Section titled “Next Steps”- Configuration. Full server configuration reference
- SQL client compatibility. Client compatibility and auth behavior
- Connectivity Overview. Client addresses and authentication
Related
Section titled “Related”This site uses Google Analytics cookies to count visits. Privacy · License