Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages

Help for owners

My Heroku app says too many database connections

Short answer

Every Heroku Postgres plan has a fixed number of connections, and every web process, worker and script holds some. As an app adds dynos or background jobs it can run out. Connection pooling on the server side lets many app connections share fewer database ones, but it is not offered on every plan.

  • Written for business owners
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Does this sound like your situation?

  • Errors say too many connections or remaining connection slots are reserved.
  • It happens at busy hours or when background jobs start.
  • Adding more dynos made it worse, not better.
  • A report or script run by hand knocks the live site over.
  • Restarting the app fixes it for a while.

Why does this happen?

  1. Each plan allows a fixed number of connections

    Heroku lists connection limits per plan, for example 20 on the smallest Essential plans, 200 on Standard-0 and 500 on larger Standard and Premium plans. When the app opens more than the plan allows, new requests fail.

  2. Every process keeps its own pool

    Web dynos, workers, schedulers and one-off scripts each open connections. Adding dynos multiplies them. Heroku describes the limit as hit when an app opens connections faster than they are released.

  3. Connections leak or are held too long

    Code that forgets to release a connection, or keeps one open during a slow external call, uses up slots without doing work. The raw database error is explained on the technical fix pages.

  4. Pooling exists but is not switched on or not available

    Heroku's server-side pooling uses PgBouncer so the app can open many connections to the pooler while fewer reach the database. It is available on Standard, Premium, Private and Shield databases, not Essential or Advanced, and the app must be pointed at the pool's own connection setting.

What can I do about it today?

  1. Note the exact error and the timeCopy the error line from the app's Logs and write down what ran at that time, such as a campaign, an import or a scheduled job.
  2. Do not keep adding dynosMore dynos mean more connections, so scaling up can make this error more frequent.
  3. Find out your database planIn the dashboard open the database add-on and note its plan name. The connection limit depends on it.
  4. Pause heavy manual scriptsAvoid running big reports or exports against the live database during busy hours until the cause is clear.
  5. Do not change database settings or delete data to free spaceConnection limits are not fixed by deleting rows. Leave data and credentials alone.

When should I bring someone in?

  • Customers see errors at peak times.
  • The app uses background workers and scheduled jobs next to the website.
  • Your plan does not offer pooling and traffic is growing.

How do I handle it?

  1. Count who holds connectionsI list every process that connects, web, workers and jobs, and multiply by what each is configured to open.
  2. Look for leaks and long holdsI check the code for connections not released and for connections held during slow outside calls.
  3. Size pools to the planApp-side pool sizes are set so the total stays under the limit with room kept for admin use and migrations.
  4. Use server-side pooling where it fitsIf the plan allows it, I route the app through the pooler and check which features it does not support before changing anything.
  5. Test under load firstI run a load test on a copy, then release with a rollback ready.

The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.

What do owners ask about this?

Do I need to upgrade my database plan?

Sometimes, but often the app opens far more connections than it needs. Count first, because a bigger plan raises the cost.

Is pooling safe to switch on?

Heroku documents limits, such as no advisory locks and a cap on prepared statements, so it has to be checked against the app before switching.

Will I lose data when this error happens?

The error blocks new connections. It does not by itself delete stored data, but a request that failed halfway may not have been saved.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.

For your developer: the technical fixes

Next step

Want this off your desk?

Send me a few lines on where things stand. I reply within 24 hours.