Skip to content

Update from code changes: TLS enforcement on the Metrics SQL API #1029

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update from code changes: TLS enforcement on the Metrics SQL API #1029

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions references/integrations/metrics-sql-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,11 +134,31 @@ PGWIRE_SSL_CERT_PATH=/path/to/tls.crt # server certificate (leaf first, then c
PGWIRE_SSL_KEY_PATH=/path/to/tls.key # private key
```

If `PGWIRE_PORT` is set without certificate paths and without `PGWIRE_SSL_MODE=disabled`, Lightdash fails fast at boot with a config error — this is intentional, so a misconfigured deployment can't accidentally accept Lightdash tokens in plaintext.

- If your certificate is from a public CA (e.g. Let's Encrypt), clients can use `sslmode=require` or `verify-full`.
- If you use a private CA or a self-signed certificate, clients either pass the CA with `sslrootcert=/path/to/ca.pem` for verification, or use `sslmode=require` (encrypted, but the server identity isn't verified).

The certificate and key files are watched by modification time and reloaded on change, so `cert-manager` renewals apply without a restart. A failed reload keeps the previously loaded certificate in place and logs an error.

The server starts a separate TCP listener on that port, so you'll also need to expose it through your load balancer or network configuration alongside the main Lightdash port. It requires a valid `LIGHTDASH_LICENSE_KEY` — see [Enterprise License Keys](/self-host/customize-deployment/enterprise-license-keys).

<Warning>
The Postgres wire protocol handshake is StartTLS-style — the client sends a plaintext `SSLRequest` before upgrading — so **a generic TLS-terminating load balancer (e.g. an L7 HTTPS proxy) cannot front this endpoint.** Terminate TLS at Lightdash by giving the backend the cert and key. If you must front it, use a Postgres-aware proxy (e.g. PgBouncer, HAProxy in `mode tcp`) and set `PGWIRE_SSL_MODE=disabled` on the Lightdash side so it accepts plaintext from the proxy on a trusted network.
</Warning>

### Rejecting plaintext clients

With TLS required (the default), a client that connects with `sslmode=disable` is rejected before authentication — no password is ever prompted for, so Lightdash tokens cannot be leaked over cleartext:

```text
psql: error: connection to server ... failed:
ERROR: connection requires TLS
SQLSTATE: 28000
```

Update client connection strings to `sslmode=require` (or stronger) to fix this.

## Limitations

- **No explicit joins, subqueries, or CTEs.** Queries select from a single explore; joins are defined in the semantic layer.
Expand Down
Loading