tableSize

Measure one table on disk: main fork, total table size including TOAST and the free space and visibility maps, index size, grand total, the TOAST relation and each index individually.

read-onlyany connectionsweeps instancesweeps group

Synopsis

tableSize(schema, table)

Description

Measure one table on disk: main fork, total table size including TOAST and the free space and visibility maps, index size, grand total, the TOAST relation and each index individually. COSTS MORE THAN IT LOOKS: these functions open the relation with AccessShareLock, so on a table an ALTER TABLE is rewriting the call waits behind AccessExclusiveLock until statement_timeout fires. Prefer size_estimate from tableStats, which is free, and call this when the estimate is too stale to act on.

A partitioned table reports its own storage, which is zero -- measure the partitions, which partitionDetails names.

Parameters

schema requiredstring
table requiredstring

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

Output

One table's measured size. An absent extension or a missing grant is reported as {error, hint} instead.

Field	Type
indexes	object \| null
indexes_size	integer \| null
kind	string \| null
main_size	integer \| null
size	integer \| null
table	string \| null
total_size	integer \| null

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": "tableSize",
    "arguments": {
      "schema": "shop",
      "table": "orders"
    }
  }
}

Result

{
  "table": "shop.orders",
  "kind": "table",
  "main_size": 186300416,
  "size": 192848896,
  "indexes_size": 60489728,
  "total_size": 253338624,
  "indexes": {
    "orders_pkey": {
      "index_size": 27025408
    },
    "orders_customer_id_idx": {
      "index_size": 33464320
    }
  }
}

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.