Fix PostgreSQL connection errors

Most connection problems come down to three things: the wrong URL for where you’re connecting from, a client that isn’t using TLS, or a password that got mangled on the way. Find your error message below.

Before anything else, open the database’s Overview tab and check that its status is Running. A stopped database refuses every connection.

password authentication failed for user

FATAL:  password authentication failed for user "app_user"

The username or password in your URL doesn’t match the database.

• Copy the URL with the copy button instead of retyping it. Click the eye icon if you want to read the password and compare it with what your app has.
• Check your environment variable. A trailing space or newline in DATABASE_URL, or a .env file that wraps the value in extra quotes, is enough to break it.
• If you build the URL from parts, percent-encode special characters in the password. The URL on the Overview tab is already encoded correctly, so it’s safer to use it as-is.

The password can’t be changed from the dashboard. If it leaked, create a new database, move the data across and delete the old one.

Connection closed right away, or “SSL connection is required”

The external endpoint accepts TLS connections only. A client that connects without TLS is disconnected before it ever reaches PostgreSQL. Depending on the driver, you’ll see something like:

server closed the connection unexpectedly
Connection terminated unexpectedly

On other hosts the same mistake produces no pg_hba.conf entry for host ... no encryption. The fix is the same: turn TLS on.

• psql and libpq-based clients already try TLS first by default. If you set sslmode=disable anywhere, in the URL or in PGSSLMODE, remove it. For the strictest setting, add ?sslmode=verify-full&sslrootcert=system (libpq 16+). The certificate is a public Let’s Encrypt one, so system roots are enough.
• node-postgres (pg) doesn’t use TLS unless you ask. Pass ssl: true in the client config.
• Prisma, SQLAlchemy, Django and most ORMs take the libpq style ?sslmode=require on the URL.

Only the external URL goes through the TLS proxy. Apps running on Runsite should use the internal URL, which needs no TLS setup at all.

could not translate host name

could not translate host name "dpg-xxxxxxxx-rw" to address: Name or service not known

You’re using the internal URL from outside Runsite. The dpg-...-rw hostname only resolves inside the platform. From your laptop, CI or another provider, use the external URL, the one ending in .eu-central-postgres.runsite.app.

Connection refused or timing out

When the external host resolves but nothing answers, check these:

• External connections are turned off. Look at Settings → Public access. With Allow external connections off, the external URL disappears from the Overview tab and the proxy closes outside connections. Services in the same workspace can still connect over the internal URL.
• Your client doesn’t send SNI. The proxy routes connections by the hostname in the TLS handshake. libpq has sent it since PostgreSQL 14, so an older psql or driver built against libpq 13 or earlier can’t connect. Upgrade the client.
• Your network blocks outbound port 5432. Some office and university networks do. Try from another network to rule it out.

sorry, too many clients already

FATAL:  sorry, too many clients already

Every open connection counts against the plan’s max_connections: 100 on the smaller plans, up to 500 on the largest. The usual cause is a connection pool that is too large for the number of running copies of your app.

Multiply the pool size by the number of instances. Ten instances with a pool of 20 already make 200 connections. Lower the pool size, close connections you open in scripts, or move to a bigger plan in Settings → Plan.

Still stuck

The Logs tab on the database shows the server side of a failed connection, including authentication failures. Pick the time window around your attempt and look for FATAL lines. The dashboard page describes each tab.