poolerStatus

read-onlyany connectionsweeps groupcan return data values

Synopsis

poolerStatus([database])

Description

Return how a PgBouncer pooler's pools are coping, per database: clients active and waiting, the longest current wait, servers active, idle, used and logging in, against the pool_size, reserve and max_connections each database is allowed, with PgBouncer's own averages per transaction, per query and per wait. clients_waiting above zero is the pooler being the bottleneck: a client is queued for a server connection, and longest_wait_s says for how long.

The raw SHOW POOLS, SHOW STATS and SHOW DATABASES rows are returned beside the summary, keyed by the columns this PgBouncer version reports, and SHOW LISTS as totals. The admin database 'pgbouncer' is left out unless named. A SHOW this PgBouncer does not know is named under 'unavailable' and the rest still answered. Reads the admin console with SHOW commands only, no transaction, each bounded by the section's statement_timeout_ms: configure the section with kind = pgbouncer and a user from stats_users, which PgBouncer allows to run SHOW and nothing else -- this server cannot verify which list the user is in.

Reads a PgBouncer admin console, not a database: 'connection' names a section with kind = pgbouncer, or a database section declaring pooler = <that section>, which is answered by its console about its own pool; 'group' asks every pooler carrying that label, one result each.

This operation can return values that came from your data. It never changes anything and never returns rows, but read what reaches the caller before connecting it to a database whose contents are sensitive.

Parameters

database optionalstring: only this pooler database, as named in its [databases] section

Also accepts connection, group, described once under arguments every tool takes.

Output

PgBouncer's pools per database: waiting clients, servers in use, averages. An absent extension or a missing grant is reported as {error, hint} instead.

Field	Type
databases	array \| null
lists	object \| null
pooler	string \| null
pools	array \| null
stats	array \| null
summary	array \| null
unavailable	object \| null
version	string \| null

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "poolerStatus",
    "arguments": {
      "connection": "pooler_prod",
      "database": "shop"
    }
  }
}

Result

{
  "version": "PgBouncer 1.25.2",
  "summary": [
    {
      "database": "shop",
      "clients_active": 20,
      "clients_waiting": 7,
      "longest_wait_s": 1.84,
      "servers_active": 20,
      "servers_idle": 0,
      "servers_used": 0,
      "servers_login": 0,
      "saturated": true,
      "pool_mode": "transaction",
      "pool_size": 20,
      "reserve_pool_size": 0,
      "max_connections": 0,
      "current_connections": 20,
      "paused": 0,
      "disabled": 0,
      "avg_xact_time": 41250,
      "avg_query_time": 39870,
      "avg_wait_time": 612000,
      "total_xact_count": 18244102,
      "total_query_count": 20118933
    }
  ],
  "lists": {
    "databases": 2,
    "users": 2,
    "pools": 2,
    "free_clients": 173,
    "used_clients": 27,
    "login_clients": 0,
    "free_servers": 30,
    "used_servers": 20
  },
  "databases": [
    {
      "name": "shop",
      "host": "db01",
      "port": 5432,
      "database": "shop",
      "pool_size": 20,
      "reserve_pool_size": 0,
      "max_connections": 0,
      "current_connections": 20,
      "paused": 0,
      "disabled": 0
    }
  ],
  "pools": [
    {
      "database": "shop",
      "user": "app_rw",
      "cl_active": 20,
      "cl_waiting": 7,
      "sv_active": 20,
      "sv_idle": 0,
      "sv_used": 0,
      "sv_login": 0,
      "maxwait": 1,
      "maxwait_us": 840000,
      "pool_mode": "transaction"
    }
  ],
  "stats": [
    {
      "database": "shop",
      "total_xact_count": 18244102,
      "total_query_count": 20118933,
      "avg_xact_time": 41250,
      "avg_query_time": 39870,
      "avg_wait_time": 612000
    }
  ]
}

Invented values on a fictional shop database, shaped by and checked against this tool's output schema. Real output is returned as structuredContent to clients that negotiate MCP 2025-06-18 or later.