tableBloat

Return physical storage bloat for a table (pgstattuple/pgstattuple_approx): table size, live/dead tuple counts and percentages, free space and percentage.

read-onlyany connectionsweeps instancesweeps group

Synopsis

tableBloat(schema, table, [exact])

Description

Return physical storage bloat for a table (pgstattuple/pgstattuple_approx): table size, live/dead tuple counts and percentages, free space and percentage. Defaults to the cheap visibility-map-based approximation; set exact=true for a precise but I/O-heavy full table scan. More accurate than the ANALYZE-time estimates in listTableStats/tableStats. Returns a clear error with setup instructions if the pgstattuple extension is not installed.

Parameters

schema requiredstring
table requiredstring
exact optionalboolean

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

Output

Physical storage bloat for one table. An absent extension or a missing grant is reported as {error, hint} instead.

Scope

A physical replica is byte-identical here, so asking each member of a replication group adds nothing.

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tableBloat",
    "arguments": {
      "schema": "shop",
      "table": "orders"
    }
  }
}

Result

{
  "method": "pgstattuple_approx",
  "exact": false,
  "table_len": 192848896,
  "scanned_percent": 3.1,
  "approx_tuple_count": 1204102,
  "dead_tuple_count": 18344,
  "dead_tuple_percent": 1.4,
  "approx_free_space": 12033024,
  "approx_free_percent": 6.2
}

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.