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.
The errors you may see
Section titled “The errors you may see”From the gateway, in your engine’s own protocol:
- PostgreSQL:
FATAL: too many connections for this instance(SQLSTATE53300) - 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.
connection rate limit exceeded; slow down
Section titled “connection rate limit exceeded; slow down”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.
Find out how many connections you use
Section titled “Find out how many connections you use”- 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.
Fix 1: size your application pools
Section titled “Fix 1: size your application pools”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": truein the create request (zb api POST /v1/orgs/{org}/projects/<project_id>/instances ...).zb instances createhas 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 withzb 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.
Fix 3: close leaked connections
Section titled “Fix 3: close leaked connections”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.
Fix 4: resize
Section titled “Fix 4: resize”A larger size has a higher connection limit. The instance restarts during a resize; see Resize.
zb instances resize <instance_id> --size m2On the Free plan the size is fixed at f0; upgrading the plan lets you choose a larger size.
Still stuck?
Section titled “Still stuck?”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.