Skip to content

Connection pool exhausted

Quick summary

Your connection pool has no available connections — all are checked out and the acquire request timed out.

Why this happens

  • Connections are not being released back to the pool after use due to missing close/return calls

  • The pool size is too small for the concurrent load on the application

  • Long-running queries hold connections for extended periods, starving other requests

Minimal example

✗ Broken code
app.get('/users', async (req, res) => {
  const client = await pool.connect();
  const users = await client.query('SELECT * FROM users');
  res.json(users);
  // missing client.release() — connection leaked!
});
✓ Fixed code
app.get('/users', async (req, res) => {
  const client = await pool.connect();
  try {
    const users = await client.query('SELECT * FROM users');
    res.json(users);
  } finally {
    client.release(); // always released
  }
});

Using try/finally to release the connection ensures it returns to the pool even if the query or response fails, preventing pool exhaustion.

How to diagnose

  • Check the pool stats for total, idle, and active connections to confirm exhaustion

  • Review code for connections that are acquired but not released in all code paths

  • Monitor query execution times to identify slow queries that hold connections too long

How to fix

  • Ensure all acquired connections are released in a finally block

  • Increase the pool max size to handle the peak concurrent load

  • Optimize slow queries or move long-running operations to a separate worker with its own pool

How to prevent

  • Always release connections in a finally block or use a pool helper that auto-releases

  • Size the connection pool based on expected concurrent load and monitor pool usage

Related Resources

Related Glossary

Related Lessons

← Back to language