Install

Docs / Connect

Connect

Every client connects through the SkelaDB proxy at the host name you installed with (SKELA_TLS_DNS_NAME), port 6432 unless your load balancer maps another. The proxy terminates TLS, authenticates the role, wakes the branch if it is suspended and pools connections.

Connection strings

The console’s Connect dialog builds them for you:

postgresql://app_3f2a...:<password>@sql.example.com:6432/app?sslmode=verify-full&options=branch%3Db-1c9e...
  • sslmode=verify-full verifies the proxy certificate. Give clients your issuer’s CA (sslrootcert=/path/ca.crt) if it is not in their trust store. The proxy refuses plaintext logins.
  • options=branch=<branch> selects the branch. Libraries that cannot pass startup options can instead connect to a host name whose first label is the branch name, if your DNS and certificate cover it.
  • branch=~read~<branch> connects to the branch’s read replicas. A read connection never falls back to the writer.
  • branch=~session~<branch> gives the connection its own server session (see pooling below).

PostgreSQL 17 clients can use sslnegotiation=direct to save a round trip.

Authentication

Only SCRAM-SHA-256 passwords are supported. MD5 and plaintext passwords are not: create roles with password_encryption = 'scram-sha-256' (the default) and reset any password stored as MD5. A wrong password and an unknown role produce the same error, 28P01. After five failures from one address for one role, that address backs off for that role, up to five minutes.

The roles the console and the connection API give you are not superusers: they cannot run server programs, read server files or change server configuration. Only the platform’s admin and project API tokens can obtain the superuser connection (known-limitations.md).

Pooling

By default the proxy pools by transaction: your session borrows a server connection for each transaction, so thousands of mostly idle clients share a few server connections. Prepared statements, including protocol-level ones, work across transactions. Session state that outlives a transaction (SET without LOCAL, advisory locks held across transactions, LISTEN, temporary tables) needs a session connection: use branch=~session~<branch>. Migration tools and pg_dump should use session connections.

Waking and idle suspension

A suspended branch wakes on the first connection; the client waits while the compute starts, typically one to two seconds, and up to 30 seconds before the proxy gives up with 08001. A branch suspends after suspendAfterSeconds (5 minutes by default) without client sessions; logical replication connections count as activity. Set suspendAfterSeconds to 0 for a branch that must never suspend.

The proxy must look up the role’s password in the branch, so a connection attempt can wake a suspended branch before the password is checked. Repeated failed or abandoned logins from an address make that address back off from the whole branch, so it cannot keep the branch awake.

Source networks

Network access in the console (or the branch’s allowed and blocked CIDRs in the API) limits which client addresses may connect. Your load balancer must preserve client source addresses for this to work.

Limits

Each proxy replica admits 10,000 sessions, at most 2,500 for one branch, and keeps at most 16 server connections open in total, 8 for any one role and database. When a limit is reached new logins receive 53300 and existing sessions continue.