listTopology

Return the configured topology: which connections share an instance (one postmaster, so they share shared_buffers, WAL, autovacuum workers and disk), which belong to the same replication_group (a primary and its replicas, holding the same data on different servers), and which…

read-only

Synopsis

listTopology([pattern])

Description

Return the configured topology: which connections share an instance (one postmaster, so they share shared_buffers, WAL, autovacuum workers and disk), which belong to the same replication_group (a primary and its replicas, holding the same data on different servers), and which carry each operator group label. Reads the config file only and opens no database connection, so it is cheap to call before deciding how wide a sweep to run.

An instance whose source is "inferred" was derived from an identical host and port rather than declared, and is a hint for grouping output, not evidence of shared memory. Roles are not here: primary or replica is observed per call, never configured -- use verifyTopology. Pass 'pattern' to narrow it: a case-insensitive substring matched against each topology name AND its member connection names, so "where does billing_prod live" and "show me the ha group" are the same argument.

A pattern that matches nothing returns empty lists rather than an error

Parameters

pattern optionalstring

case-insensitive substring of an instance, replication_group or group name, or of a connection name belonging to one

Output

The three configured topology axes. An absent extension or a missing grant is reported as {error, hint} instead.

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listTopology",
    "arguments": {}
  }
}

Result

{
  "instances": [
    {
      "name": "pg-shop-01",
      "source": "declared",
      "connections": [
        "shop_prod",
        "reports_prod"
      ]
    }
  ],
  "replication_groups": [
    {
      "name": "shop-ha",
      "connections": [
        "shop_prod",
        "shop_replica_1"
      ]
    }
  ],
  "groups": [
    {
      "name": "fleet",
      "connections": [
        "shop_prod",
        "shop_replica_1",
        "reports_prod"
      ]
    }
  ],
  "unlabelled": []
}

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

verifyTopology