Guides

Why my database connection fails — three causes and how to tell them apart in a minute

Illustration: a bundle of cables that won't fit into one socket

Works locally. Deployed — the database won't connect. And the annoying part: the error sounds like you're being flooded with users, when the only user is you.

Good news: this breakage has three common causes, and they're distinguishable by the error text. Don't guess — read the symptom and go straight to the right section.

Cause 1: too many connections (even with one user)

Symptom: FATAL: sorry, too many clients already, Max client connections reached, remaining connection slots are reserved.

Why. PostgreSQL spawns a separate process for every connection — not a thread, a full process with its own memory. So connections are expensive and there aren't many: on small instances the limit sits somewhere around sixty.

Now layer serverless on top. Every cold start is a new instance of your app, and it opens its own connection pool. A dozen parallel requests easily becomes a dozen pools of 5–10 connections each. The limit is gone, and the culprit isn't traffic — it's arithmetic.

The second classic case is a database client created inside the request handler. Then every call opens a new connection, and often never closes it.

How to check. Run two queries in the SQL editor:

show max_connections;
select count(*) from pg_stat_activity;

If the second number is creeping up on the first, diagnosis confirmed.

How to fix.

  • Connect through a pooler in transaction mode. On Supabase that's a separate host and port 6543 — it keeps hot connections and hands them out for the duration of a query, not the lifetime of a function.
  • In serverless, set your app's pool size to 1–2 connections. A big pool inside a function is pointless: concurrency there comes from instances, not from the pool.
  • Create the client once per module, not inside the handler.

Cause 2: the address exists, but the network doesn't reach it

Symptom: connect ENETUNREACH, hanging until timeout, ETIMEDOUT. Meanwhile the exact same string connects fine from your laptop.

Why. Direct database connections on some platforms (Supabase among them) live on IPv6. Your home ISP probably speaks IPv6. The hosting network where your backend runs — often not.

Hence the magic trick: the same connection string works for you and fails on the server. It's natural to suspect the password or a firewall, but the issue is the protocol version.

How to check. Take the same connection string and run it not locally but from the environment where it fails — a one-off job on the same host, for example. Works locally, ENETUNREACH there? That's it.

How to fix. Switch to the pooler connection string: it has an IPv4 address. For an always-on server use the pooler's session mode; for functions, transaction mode. A dedicated IPv4 address for direct connections is usually a paid add-on, and 99% of the time you don't need it.

Cause 3: the connection string is lying

Symptom: password authentication failed for user "postgres", database does not exist, getaddrinfo ENOTFOUND.

Three sub-cases here, all about copy-paste.

  • Placeholder never replaced. The string still literally contains [YOUR-PASSWORD]. Funny, but it's the number one cause of "the password doesn't work".
  • Special characters not encoded. A connection string is a URL. If your password contains @, #, / or :, they must be encoded: @ becomes %40, # becomes %23. Otherwise the parser decides the host starts in the middle of your password — hence the odd ENOTFOUND.
  • The environment variable never arrived. Your code reads an empty string and falls back to localhost. Check this first — the how is covered in why your environment variables aren't working.

How to check. Log not the password itself but its length and the first characters of the host. Zero length means the variable didn't arrive. An unexpected host means the string parsed differently than you assumed.

The debugging order that saves you an evening

  1. Connect to the database with a client from your own machine — that proves the database is alive and the password is right.
  2. Connect with the same string from the environment where it fails. The difference between steps 1 and 2 is almost always networking or the pooler.
  3. Only then dig into the application code.

Half of all lost evenings are spent debugging code in a situation where step 2 was broken. If you're only just setting the database up, walk through the guide on connecting a database to your app — it builds the connection string step by step.

Why does it work locally but not on the server?

Because locally you have different network access, different environment variables, and one instance of the app instead of ten. Three differences, three causes from this article.

Does a pooler solve all connection problems?

No. It removes the client limit and gives you IPv4, but it won't save you from code that opens a connection and never lets go. Transaction mode also drops session-level features like prepared statements and LISTEN.

How many connections does my app need?

Fewer than you think. A regular backend is fine with a pool of 5–10, a function with 1–2. Extra connections don't speed up the database — they take memory away from it.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →