Connect Postgres
Console: Sidebar Connections → Connect customer database
What Connections does
- Tests TCP/Postgres from the control plane API (not your browser)
- Saves credentials encrypted in the control plane
- Syncs connection to your workspace analytics runtime (Superset REST)
Failure before save → red error under the form. Save OK but sync fails → 502 (often public HTTPS or runtime login).
Allowlist IPs (copy from UI)
Customer database must allow both:
| Source | Used for |
|---|---|
| API egress IP | Connection test + sync |
| Runtime EC2 IP | Chart queries after sync |
Shown on the connect form. API: GET /data-sources/egress-ips (Clerk auth).
Until stable NAT is enabled, ECS egress IP may change on redeploy — re-check allowlist after platform deploys.
Customer / DBA checklist
listen_addresses— not127.0.0.1only (ss -lntp | grep 5432)pg_hba.conf— allow both Embedded Canvas IPs; usehostsslwhen SSL =require- Security group / firewall — inbound TCP 5432 from both IPs
- Read-only role —
SELECTon required schemas - Tenant column on fact tables — validate ≥2 test tenant ids with different rows
- Runtime public HTTPS OK (Operator console runtime health) before sync
Connect form fields
| Field | Notes |
|---|---|
| Connection name | Unique per workspace; becomes Superset database label |
| Host / port / database | Customer Postgres or pooler host |
| Username / password | Read-only user |
| SSL | require (production) · disable (private demo only) |
Supabase Session pooler
Direct db.<project>.supabase.co often resolves to IPv6 — our API may fail with ENETUNREACH. Use Session pooler from Supabase Connect:
| Field | Example pattern |
|---|---|
| Host | aws-1-us-east-2.pooler.supabase.com (copy exact shard from Connect) |
| Port | 5432 |
| User | postgres.<project-ref> or role.<project-ref> |
| Database | postgres |
| SSL | require |
Do not mix pooler shards (e.g. nc to aws-1 but psql to aws-0).
Test from runtime EC2 before connecting:
psql "host=<pooler-host> port=5432 dbname=postgres user=postgres.<ref> sslmode=require" -c 'SELECT 1'
Add EC2 public IP + API egress IP in Supabase Network restrictions.
Common errors
| Message | Fix |
|---|---|
| Connection refused | Postgres on localhost only; nothing on 5432 |
| Timeout | Firewall / SG / Supabase network restrictions |
| Password authentication failed | User, password, or pg_hba |
ENETUNREACH + IPv6 | Use Session pooler host |
tenant/user … not found (pooler) | Wrong pooler shard or username format |
| 502 after green test | Runtime public HTTPS; check API logs |
Re-sync
Credentials already saved but runtime out of date:
- Analytics → Re-sync only, or
POST /data-sources/:id/sync-to-runtime
Deep reference
- CONNECT_MERCHANT_DATABASE.md
- End-to-end — Phase 2