diskUsage

read-onlyany connectionsweeps replication groupsweeps group

Synopsis

diskUsage()

Description

Report what PostgreSQL is holding on disk without needing a shell on the server: WAL directory size and file count, the archive status backlog, temporary files currently on disk, log directory size, per-tablespace sizes and per-database sizes across the whole cluster. Answers "what is filling the disk" from SQL alone, which otherwise needs df. IT CANNOT SAY HOW MUCH ROOM IS LEFT: PostgreSQL exposes no function for total or free space, so this reports what is consuming space and how it divides, never the headroom.

A climbing .ready count in archive_status is a failing archive_command retaining every segment it has not archived -- indistinguishable from an abandoned replication slot by size alone, and this is what tells them apart. Two different privilege gates, not one: the pg_ls_* sections need pg_monitor, and the tablespace and database sizes need CREATE on the tablespace or pg_read_all_stats (except the current database's default tablespace) and CONNECT or pg_read_all_stats respectively.

A pg_monitor role clears both since it holds pg_read_all_stats; a bare role can get the cheap directory sections and be refused the expensive size ones, which is easy to misread as success. Each section is guarded independently, so one refusal returns an error in that key and leaves the rest answered rather than failing the call. Costs: the four directory sections are trivial, and the tablespace and database sizes are the whole cost -- they walk the directory tree and stat every segment file, so they scale with FILE COUNT rather than with bytes.

Measured at 314 ms for the whole call against a cluster of roughly a terabyte, where a bare databaseSize is already 163 ms. Nothing is read, no relation is opened and no lock is taken -- this is metadata rather than I/O -- but it was measured with directory entries warm in the page cache, and a filling disk is exactly when they are not. statement_timeout bounds it, so the failure mode is a timeout that names itself.

Parameters

None of its own.

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

Output

What PostgreSQL is holding on disk, by directory and by tablespace. Never how much room is left. An absent extension or a missing grant is reported as {error, hint} instead.

Field	Type
archive_status	object \| null
databases	object \| null
log_files	object \| null
note	string \| null
tablespaces	object \| null
temp_files	object \| null
wal	object \| null

Scope

This reading is instance-wide -- every database on the same postmaster returns it identically, so asking each of them in turn repeats one answer. 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.

Example mocked data

Request

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

Result

{
  "wal": {
    "files": 42,
    "bytes": 704643072
  },
  "archive_status": {
    "archive_mode": "on",
    "ready": 0,
    "done": 3
  },
  "temp_files": {
    "files": 1,
    "bytes": 268435456
  },
  "log_files": {
    "logging_collector": true,
    "directory": "log",
    "files": 14,
    "bytes": 91231002
  },
  "tablespaces": {
    "pg_default": {
      "location": "(default)",
      "bytes": 38402912256
    }
  },
  "databases": {
    "shop": {
      "bytes": 36120010752
    },
    "reports": {
      "bytes": 2282901504
    }
  },
  "note": "Free space on the filesystem is not exposed by PostgreSQL and is not reported."
}

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.