Skip to content

Help

Too many connections

Tested with:Databasezy API v1 · zb CLI 0.1

Every instance size has a connection limit (max_connections). Both the engine and the Databasezy gateway enforce it. When it is reached, new connections are refused until others close. The fix is almost always to use fewer, longer lived connections: a connection pool in your application, the built-in pooler for PostgreSQL, or a larger size when you really need more. The limit for each size is in the size catalogue.

From the gateway, in your engine’s own protocol:

  • PostgreSQL: FATAL: too many connections for this instance (SQLSTATE 53300)
  • MySQL and MariaDB: error 1040
  • Valkey and Redis: -ERR max number of clients reached

From the engine itself, for example PostgreSQL’s FATAL: sorry, too many clients already or remaining connection slots are reserved. The cause and the fix are the same.

This is a different limit: how fast new connections are opened, per instance and per client IP address. It is hit by code that opens a new connection for every query or every request, or by many processes reconnecting at once after a restart. Reuse connections from a pool, and add jittered backoff to reconnect loops.

  • In the portal, Instance → Connect → Pooling and limits shows the connection limit and the peak this week.
  • Instance → Metrics → New connections shows how many connections were opened through the gateway. Concurrent connections are not charted yet.
  • On the database, PostgreSQL: SELECT state, count(*) FROM pg_stat_activity GROUP BY state;. MySQL: SHOW PROCESSLIST;.

Look for many idle connections (pools that are too large or never close) and for connections from a tool or job you forgot about.

Add up the pool size of every process that connects, multiplied by the number of replicas, and keep the total well under the limit. Leave about 10 connections free for migrations, backups and your own psql sessions. A pool of 5 to 10 connections per process is enough for most web applications. Connection pooling has settings for common drivers and frameworks.

Serverless functions open a new connection per invocation, which exhausts the limit quickly under load. Keep their pool at 1 to 5 connections and use the pooler below on PostgreSQL.

Fix 2: the PgBouncer pooler (PostgreSQL and TimescaleDB)

Section titled “Fix 2: the PgBouncer pooler (PostgreSQL and TimescaleDB)”

PostgreSQL and TimescaleDB instances can run a PgBouncer pooler in transaction mode. It lets many short client connections share a small number of server connections. Things to know:

  • The pooler is chosen when the instance is created. Set "pooler_enabled": true in the create request (zb api POST /v1/orgs/{org}/projects/<project_id>/instances ...). zb instances create has no flag for it yet, and it cannot be turned on for an existing instance yet. To move an existing database onto a pooled instance, create the new instance with the pooler and copy the data with zb migrate --from <old_id> --to <new_id>.
  • Transaction mode has limits: no session state between transactions, no LISTEN/NOTIFY, and prepared statements need your ORM’s pooler setting. The pooled endpoint is the instance’s own host and port (there is no separate pooler host). Migration tools and anything else that needs a session use the instance’s direct host, pg-<id>-direct... on the same port, which goes past PgBouncer to the primary; its connections count against the same connection limit, so keep them to tools and jobs (pooled vs direct).

See Connection pooling for the endpoint to use and per-ORM settings. MySQL and the other engines have no built-in pooler; use the driver’s pool.

On PostgreSQL, sessions that sit idle inside an open transaction for 5 minutes are closed by the server (idle_in_transaction_session_timeout). If you see terminating connection due to idle-in-transaction timeout, your code opened a transaction and never committed or rolled it back. Fix the code path rather than raising the limit.

A larger size has a higher connection limit. The instance restarts during a resize; see Resize.

shell
zb instances resize <instance_id> --size m2

On the Free plan the size is fixed at f0; upgrading the plan lets you choose a larger size.

Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket). Include the instance id, the region, its size, the exact error text, your client or driver and pool settings, how many processes connect, and the time it happened in UTC. Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.