poolerConnections

Return the connections a PgBouncer pooler holds: every client connected to it (SHOW CLIENTS) and every server connection it has open to PostgreSQL (SHOW SERVERS), each with its state, database, user, application_name, address and how long it has waited, plus counts by state…

read-onlyany connectionsweeps groupcan return data values

Synopsis

poolerConnections([database], [limit], [state])

Description

Return the connections a PgBouncer pooler holds: every client connected to it (SHOW CLIENTS) and every server connection it has open to PostgreSQL (SHOW SERVERS), each with its state, database, user, application_name, address and how long it has waited, plus counts by state, taken after 'database' narrows the rows and before 'state' and 'limit' do. A client in state 'waiting' has no server yet -- the queue behind a saturated pool.

No statement text is here, since PgBouncer does not keep it, but client IP addresses and ports, user and database names and application_name are. Reads the admin console with SHOW commands only; see poolerStatus. 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 connections to this pooler database
limit optionalinteger
at most this many clients and this many servers, 100 by default and at most 1000; *_truncated says when more matched
state optionalstring
only this state, e.g. "active", "waiting" or "idle"; the counts by state still cover all of them

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

Output

PgBouncer's client and server connections. An absent extension or a missing grant is reported as {error, hint} instead.

FieldType
clientsarray | null
clients_by_stateobject | null
clients_truncatedboolean | null
poolerstring | null
serversarray | null
servers_by_stateobject | null
servers_truncatedboolean | null
unavailableobject | null

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "poolerConnections",
    "arguments": {
      "connection": "pooler_prod",
      "database": "shop",
      "state": "waiting",
      "limit": 2
    }
  }
}

Result

{
  "clients": [
    {
      "type": "C",
      "user": "app_rw",
      "database": "shop",
      "state": "waiting",
      "addr": "10.0.4.17",
      "port": 51526,
      "application_name": "checkout-api",
      "connect_time": "2026-09-25 14:02:11 +00",
      "request_time": "2026-09-25 14:07:43 +00",
      "wait": 1,
      "wait_us": 840000
    },
    {
      "type": "C",
      "user": "app_rw",
      "database": "shop",
      "state": "waiting",
      "addr": "10.0.4.18",
      "port": 49870,
      "application_name": "checkout-api",
      "connect_time": "2026-09-25 14:02:12 +00",
      "request_time": "2026-09-25 14:07:43 +00",
      "wait": 0,
      "wait_us": 910000
    }
  ],
  "clients_by_state": {
    "active": 20,
    "waiting": 7,
    "idle": 3
  },
  "clients_truncated": true,
  "servers": [],
  "servers_by_state": {
    "active": 20
  },
  "servers_truncated": false
}

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.

See also

poolerStatus, poolerConfig