When Golang database connections are exhausted, the issue may be slow queries, long transactions, leaked resources, or concurrency patterns that overwhelm the pool faster than expected.
That is why “the database is out of connections” is not yet the root cause. Sometimes the pool is simply too small for the new workload. In other cases, the real bug is that rows, statements, or transactions stay open longer than the team assumes.
This guide focuses on the practical path:
- how to separate pool sizing pressure from connections held too long
- what to inspect first when callers start waiting behind
database/sql - how query time, hold time, and concurrency shape combine into exhaustion
The short version: first compare active connections with waiting callers, then inspect whether queries are slow or resources stay open too long, and finally decide whether the issue is workload growth, cleanup bugs, or pool assumptions that no longer fit production.
If you want the broader Go routing view first, go to the Golang Troubleshooting Guide.
Start with active versus waiting
The first useful comparison is:
- how many connections are active
- how many callers are waiting
- whether query time or hold time grew first
That split matters because two incidents can look the same externally:
- the database is genuinely slower, so connections stay busy longer
- the application holds connections too long even after the query work is effectively done
Without that split, it is easy to blame pool size when the real issue is a resource lifecycle bug.
Pool pressure vs resource retention
A connection pool can become exhausted for at least three broad reasons:
- demand increased and the pool assumptions are outdated
- each connection is busy for too long because queries are slow
- connections are not being released promptly due to application behavior
Those reasons overlap, but they are not the same operational problem.
The useful question is not only “are we out of connections?” It is “why are callers waiting longer than before?”
Common causes to check
1. Slow queries
Connections stay busy too long and queue callers behind them.
Typical signs:
- query duration increased first
- waiting callers grow after query latency rises
- one query path dominates pool occupancy
When query time is the main driver, the pool symptom is real but secondary. The underlying issue usually lives in the query, the database, or the dependency path around it.
2. Transactions or rows are not released promptly
Resources stay open longer than intended.
This often happens when:
rows.Close()is missed- transactions stay open across too much application work
- error paths exit early before cleanup
- callers hold a connection while doing non-database work
In those cases the pool looks too small, but the bigger issue is that connections are being held longer than the team expects.
3. Pool size no longer matches concurrency
Sometimes the workload simply outgrew the original pool assumptions.
Examples:
- more API concurrency than before
- more workers hitting the same DB
- larger job batches
- a new fan-out or retry behavior increasing query volume
In those cases the pool may need adjustment, but only after you confirm that slow queries and long hold time are not the deeper problem.
A practical debugging order
When DB connections run out, this order usually narrows the issue quickly:
- inspect active connections and waiting callers
- compare query time against connection hold time
- inspect cleanup paths for rows, transactions, and statements
- compare recent traffic or job concurrency changes
- decide whether the main issue is slow work, long hold time, or outdated pool assumptions
This order matters because it prevents two common mistakes:
- increasing pool size before understanding why connections are busy
- blaming slow queries before checking whether the app holds connections too long
If timeouts are the first visible symptom, compare with Golang Context Deadline Exceeded.
A small example of pool pressure
db.SetMaxOpenConns(10)
for i := 0; i < 100; i++ {
go query(db)
}If callers outpace the pool and each connection is held too long, waiting builds quickly behind database/sql.
The example is simple, but the real question is always the same: are you doing too much concurrent work for the pool, or is each unit of work keeping the connection longer than necessary?
A good question for every DB path
For each query or transaction path, ask:
- when is the connection acquired
- what work happens while it is held
- what event releases it
- do all success and error paths release it
This framing helps because many pool incidents are lifecycle bugs disguised as capacity problems.
When increasing the pool is the wrong first fix
Increasing MaxOpenConns may help, but it is the wrong first move when:
- one query path got slower
- transactions stay open longer than expected
- connections remain held during extra application work
- the database itself is already under pressure
A bigger pool may reduce waiting for a while, but it can also push more pressure into the database and make the real bottleneck worse.
Increase the pool only after you understand why callers are waiting.
FAQ
Q. Does pool exhaustion always mean the DB is slow?
No. It may also mean the application is holding connections too long, leaking rows, or generating more concurrent demand than the pool was designed for.
Q. What should I inspect first?
Compare active connections, waiting callers, query time, and hold time before changing pool size.
Q. Can rows or transactions really cause this even when query count is not huge?
Yes. A modest amount of concurrency can still exhaust the pool if each path keeps connections open longer than intended.
Read Next
- If you want the broader Go routing view first, go to the Golang Troubleshooting Guide.
- If timeouts are the first visible symptom, compare with Golang Context Deadline Exceeded.
- If memory or workers are also under pressure, compare with Golang Memory Usage High.
Related Posts
Sources:
While AdSense review is pending, related guides are shown instead of ads.
Start Here
Continue with the core guides that pull steady search traffic.
- Middleware Troubleshooting Guide: Redis vs RabbitMQ vs Kafka A practical middleware troubleshooting guide for developers covering when to reach for Redis, RabbitMQ, or Kafka symptoms first, and which problem patterns usually belong to each tool.
- Kubernetes CrashLoopBackOff: What to Check First A practical Kubernetes CrashLoopBackOff troubleshooting guide covering startup failures, probe issues, config mistakes, and what to inspect first.
- Kafka Consumer Lag Increasing: Troubleshooting Guide A practical Kafka consumer lag troubleshooting guide covering what lag usually means, which consumer metrics to check first, and how poll timing, processing speed, and fetch patterns affect lag.
- Kafka Rebalancing Too Often: Common Causes and Fixes A practical Kafka troubleshooting guide covering why consumer groups rebalance too often, what poll timing and group protocol settings matter, and how to stop rebalances from interrupting useful work.
- Docker Container Keeps Restarting: What to Check First A practical Docker restart-loop troubleshooting guide covering exit codes, command failures, environment mistakes, health checks, and what to inspect first.
While AdSense review is pending, related guides are shown instead of ads.