{
  "license": "CC BY 4.0",
  "recipe": {
    "slug": "database-connection-pool-saturation",
    "title": "Measure Database Connection-Pool Saturation",
    "testedWith": "Apache DataFusion 45.2.0",
    "lastReviewed": "2026-07-28"
  },
  "contract": {
    "tableName": "database_pool_samples",
    "schema": [
      {
        "name": "timestamp_utc",
        "type": "Timestamp",
        "description": "Pool sample time in UTC."
      },
      {
        "name": "service",
        "type": "Utf8",
        "description": "Application service that owns the pool."
      },
      {
        "name": "pool_name",
        "type": "Utf8",
        "description": "Stable logical pool name."
      },
      {
        "name": "active_connections",
        "type": "Int64",
        "description": "Connections currently checked out."
      },
      {
        "name": "idle_connections",
        "type": "Int64",
        "description": "Open connections currently idle."
      },
      {
        "name": "max_connections",
        "type": "Int64",
        "description": "Configured maximum pool size."
      },
      {
        "name": "wait_ms",
        "type": "Float64",
        "description": "Observed connection-acquisition wait for this sample."
      },
      {
        "name": "timed_out",
        "type": "Boolean",
        "description": "Whether acquisition exceeded the client timeout."
      },
      {
        "name": "environment",
        "type": "Utf8",
        "description": "Deployment environment."
      }
    ]
  },
  "query": "SELECT\n  service,\n  pool_name,\n  COUNT(*) AS samples,\n  100.0 * AVG(active_connections)\n    / NULLIF(MAX(max_connections), 0) AS average_utilization_pct,\n  SUM(CASE WHEN wait_ms > 0 THEN 1 ELSE 0 END) AS waited_samples,\n  100.0 * SUM(CASE WHEN wait_ms > 0 THEN 1 ELSE 0 END)\n    / NULLIF(COUNT(*), 0) AS wait_rate_pct,\n  AVG(wait_ms) AS average_wait_ms,\n  SUM(CASE WHEN timed_out THEN 1 ELSE 0 END) AS timeouts\nFROM database_pool_samples\nWHERE timestamp_utc >= now() - INTERVAL '24 hours'\n  AND environment = 'production'\nGROUP BY service, pool_name\nHAVING COUNT(*) >= 10\nORDER BY wait_rate_pct DESC, average_utilization_pct DESC;",
  "fixtureKind": "reproducible",
  "inputRows": [
    {
      "timestamp_utc": "2026-07-28T18:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 8,
      "idle_connections": 2,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T17:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 9,
      "idle_connections": 1,
      "max_connections": 10,
      "wait_ms": 45,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T16:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 10,
      "idle_connections": 0,
      "max_connections": 10,
      "wait_ms": 180,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T15:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 10,
      "idle_connections": 0,
      "max_connections": 10,
      "wait_ms": 320,
      "timed_out": true,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T14:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 9,
      "idle_connections": 1,
      "max_connections": 10,
      "wait_ms": 65,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T13:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 8,
      "idle_connections": 2,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 7,
      "idle_connections": 3,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 9,
      "idle_connections": 1,
      "max_connections": 10,
      "wait_ms": 90,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T10:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 10,
      "idle_connections": 0,
      "max_connections": 10,
      "wait_ms": 240,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T09:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 10,
      "idle_connections": 0,
      "max_connections": 10,
      "wait_ms": 410,
      "timed_out": true,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T08:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 9,
      "idle_connections": 1,
      "max_connections": 10,
      "wait_ms": 75,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T07:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 8,
      "idle_connections": 2,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T16:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 3,
      "idle_connections": 7,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T15:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 4,
      "idle_connections": 6,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T14:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 5,
      "idle_connections": 5,
      "max_connections": 10,
      "wait_ms": 25,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T13:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 4,
      "idle_connections": 6,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 6,
      "idle_connections": 4,
      "max_connections": 10,
      "wait_ms": 40,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 5,
      "idle_connections": 5,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T10:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 4,
      "idle_connections": 6,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T09:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 5,
      "idle_connections": 5,
      "max_connections": 10,
      "wait_ms": 30,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T08:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 6,
      "idle_connections": 4,
      "max_connections": 10,
      "wait_ms": 55,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T07:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 5,
      "idle_connections": 5,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T06:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 4,
      "idle_connections": 6,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T05:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 3,
      "idle_connections": 7,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    }
  ],
  "illustrativeInputRows": [
    {
      "timestamp_utc": "2026-07-28T18:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 8,
      "idle_connections": 2,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T17:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 9,
      "idle_connections": 1,
      "max_connections": 10,
      "wait_ms": 45,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T16:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 10,
      "idle_connections": 0,
      "max_connections": 10,
      "wait_ms": 180,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T15:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 10,
      "idle_connections": 0,
      "max_connections": 10,
      "wait_ms": 320,
      "timed_out": true,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T14:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 9,
      "idle_connections": 1,
      "max_connections": 10,
      "wait_ms": 65,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T13:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 8,
      "idle_connections": 2,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 7,
      "idle_connections": 3,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 9,
      "idle_connections": 1,
      "max_connections": 10,
      "wait_ms": 90,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T10:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 10,
      "idle_connections": 0,
      "max_connections": 10,
      "wait_ms": 240,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T09:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 10,
      "idle_connections": 0,
      "max_connections": 10,
      "wait_ms": 410,
      "timed_out": true,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T08:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 9,
      "idle_connections": 1,
      "max_connections": 10,
      "wait_ms": 75,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T07:00:00.000Z",
      "service": "checkout-api",
      "pool_name": "primary",
      "active_connections": 8,
      "idle_connections": 2,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T16:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 3,
      "idle_connections": 7,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T15:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 4,
      "idle_connections": 6,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T14:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 5,
      "idle_connections": 5,
      "max_connections": 10,
      "wait_ms": 25,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T13:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 4,
      "idle_connections": 6,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 6,
      "idle_connections": 4,
      "max_connections": 10,
      "wait_ms": 40,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 5,
      "idle_connections": 5,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T10:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 4,
      "idle_connections": 6,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T09:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 5,
      "idle_connections": 5,
      "max_connections": 10,
      "wait_ms": 30,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T08:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 6,
      "idle_connections": 4,
      "max_connections": 10,
      "wait_ms": 55,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T07:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 5,
      "idle_connections": 5,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T06:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 4,
      "idle_connections": 6,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    },
    {
      "timestamp_utc": "2026-07-28T05:00:00.000Z",
      "service": "analytics-api",
      "pool_name": "reporting",
      "active_connections": 3,
      "idle_connections": 7,
      "max_connections": 10,
      "wait_ms": 0,
      "timed_out": false,
      "environment": "production"
    }
  ],
  "expectedOutput": {
    "columns": [
      "service",
      "pool_name",
      "samples",
      "average_utilization_pct",
      "waited_samples",
      "wait_rate_pct",
      "average_wait_ms",
      "timeouts"
    ],
    "rows": [
      {
        "service": "checkout-api",
        "pool_name": "primary",
        "samples": 12,
        "average_utilization_pct": 89.17,
        "waited_samples": 8,
        "wait_rate_pct": 66.67,
        "average_wait_ms": 118.75,
        "timeouts": 2
      },
      {
        "service": "analytics-api",
        "pool_name": "reporting",
        "samples": 12,
        "average_utilization_pct": 45,
        "waited_samples": 4,
        "wait_rate_pct": 33.33,
        "average_wait_ms": 12.5,
        "timeouts": 0
      }
    ]
  },
  "notes": [
    "The included synthetic input rows generate the expected output when timestamps are shifted into the documented query window.",
    "Run this fixture in the public browser SQL playground; the selected query executes locally with DuckDB-Wasm.",
    "Adapt time windows, thresholds, identities, and business definitions before operational use."
  ]
}