listTableStats

read-onlyany connectionsweeps instancesweeps replication groupsweeps group

Synopsis

listTableStats(schema)

Description

Return the statistics PostgreSQL keeps for every table in a schema: estimated row count, seq_scan and idx_scan counts, live and dead tuples, rows modified since the last analyze, rows inserted since the last vacuum, and the manual and automatic vacuum and analyze times as four separate fields (last_vacuum and last_analyze are the manual ones, exactly as in pg_stat_user_tables -- a recent last_vacuum beside a null last_autovacuum means the table is being kept alive by hand and autovacuum is not reaching it).

Reads the catalog and the statistics collector only -- no relation is opened and no file is measured. Carries no per-column histograms; name one table to tableStats for those. size_estimate is relpages*block_size (the server's BLCKSZ, 8192 unless it was built otherwise) and is only as fresh as estimated_from says: for measured sizes call listTableSizes.

Parameters

schema requiredstring

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

Output

Keyed by table name; each value is that table's statistics counters and size estimate. An absent extension or a missing grant is reported as {error, hint} in place of the map.

Scope

The counters here are each server's own, so members of a replication group legitimately disagree and the answer is their sum, not the primary's copy. Dead tuples and the last vacuum and analyze times describe work that only happens on a primary; on a replica they are noise, not a second opinion.

Example mocked data

Request

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

Result

{
  "orders": {
    "rows": 1204388,
    "size_estimate": 187351040,
    "seq_scan": 41,
    "idx_scan": 9832117,
    "n_dead_tup": 18344,
    "last_autovacuum": "2026-09-14T22:05:12Z"
  },
  "customers": {
    "rows": 88213,
    "size_estimate": 13705216,
    "seq_scan": 12,
    "idx_scan": 1200443,
    "n_dead_tup": 211,
    "last_autovacuum": "2026-09-13T08:40:01Z"
  }
}

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.