Skip to content
Telemetry
Database reliability SQL recipe

Measure database connection-pool saturation

Measure average pool utilization, queued acquisition waits, timeouts, and idle capacity by application service.

Beginnerdatabase_pool_samplesReviewed 2026-07-28Tested with Apache DataFusion 45.2.0

Reviewed by the Telemetry product team on . We checked the SQL syntax, required event fields, sample results, and limits on using the query. Who reviews this page

Question answered

Which application pools are making callers wait for a database connection?

A full pool alone does not mean requests are delayed. Check whether callers are also waiting for connections or timing out.

Event schema

Fields the query expects

FieldTypeWhy it exists
timestamp_utcTimestampPool sample time in UTC.
serviceUtf8Application service that owns the pool.
pool_nameUtf8Stable logical pool name.
active_connectionsInt64Connections currently checked out.
idle_connectionsInt64Open connections currently idle.
max_connectionsInt64Configured maximum pool size.
wait_msFloat64Observed connection-acquisition wait for this sample.
timed_outBooleanWhether acquisition exceeded the client timeout.
environmentUtf8Deployment environment.
DataFusion SQL

Copy the query

sql
SELECT
  service,
  pool_name,
  COUNT(*) AS samples,
  100.0 * AVG(active_connections)
    / NULLIF(MAX(max_connections), 0) AS average_utilization_pct,
  SUM(CASE WHEN wait_ms > 0 THEN 1 ELSE 0 END) AS waited_samples,
  100.0 * SUM(CASE WHEN wait_ms > 0 THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS wait_rate_pct,
  AVG(wait_ms) AS average_wait_ms,
  SUM(CASE WHEN timed_out THEN 1 ELSE 0 END) AS timeouts
FROM database_pool_samples
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
  AND environment = 'production'
GROUP BY service, pool_name
HAVING COUNT(*) >= 10
ORDER BY wait_rate_pct DESC, average_utilization_pct DESC;

This read-only query is planned and executed against an empty typed table with Apache DataFusion 45.2.0. We review the synthetic sample output separately. Check field types, thresholds, and counting rules against your own data. Read the testing methodology.

Query result

Connection acquisition wait rate

Checkout callers wait in two-thirds of the samples and also experience acquisition timeouts.

servicepool_namesamplesaverage_utilization_pctwaited_sampleswait_rate_pctaverage_wait_mstimeouts
checkout-apiprimary1289.17866.67118.752
analytics-apireporting1245433.3312.50

Synthetic example output. Run the query against your own event schema and thresholds before using it for operational decisions.

Connection acquisition wait rate: static chart of synthetic wait_rate_pct values from the Measure database connection-pool saturation example result
Download this SVG chart of the sample results for an article, runbook, or design review. Please credit Telemetry.

Reproduce the example

Download the sample data

The JSON bundle includes the event schema with field types, reproducible input rows, exact SQL, expected output, review notes, and engine version. The CSV contains the displayed result.

How the SQL works

  1. 1Use average utilization to check capacity. It does not establish a failure on its own.
  2. 2The waited-sample rate shows how frequently callers encounter contention even when the wait remains short.
  3. 3Timeouts remain explicit because an average can hide a smaller set of requests that never acquire a connection.

Edge cases to check

  • Sampling frequency must remain stable before comparing rates across services.
  • Serverless concurrency can create many independent pools; include an instance or runtime dimension when aggregation would hide that shape.
  • Increasing pool size can move contention into the database. Check database capacity before changing the client limit.

Recommended dashboard

  • Bars: wait_rate_pct and average_utilization_pct by service
  • Trend: active, idle, and waiting connections
  • Stat: connection-acquisition timeouts

Alert guidance

Alert when wait rate and timeouts remain elevated across consecutive samples, then validate database capacity before increasing the pool.

Read alert setup

Set up the events this query needs

Related instrumentation and guides

Continue the analysis

Run it on your events

Create a table, adapt the fields, and save the result

Start free, send structured events, and use the query result as a chart, shared dashboard widget, or alert input.

Get an API key