checkpointStats

read-onlyany connectionsweeps replication groupsweeps group

Synopsis

checkpointStats()

Description

Return checkpoint, WAL, and background writer activity (pg_stat_checkpointer and pg_stat_bgwriter on PostgreSQL 17+, pg_stat_bgwriter alone before that, plus pg_stat_wal) with field names normalized across both shapes: timed versus requested checkpoint counts and the ratio between them, write and sync time, buffers written by the checkpointer, by the background writer, and directly by backends, WAL record/FPI/byte counts, and the related settings (checkpoint_timeout, max_wal_size, checkpoint_completion_target, the bgwriter knobs).

Parameters

None of its own.

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

Output

Checkpoint, WAL and background writer activity, normalised across versions. An absent extension or a missing grant is reported as {error, hint} instead.

Field	Type
backend_io	object \| null
bgwriter	object \| null
checkpointer	object \| null
settings	object \| null
source	string \| 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": "checkpointStats",
    "arguments": {}
  }
}

Result

{
  "source": "pg_stat_checkpointer",
  "checkpointer": {
    "checkpoints_timed": 1402,
    "checkpoints_requested": 38,
    "timed_percent": 97.4,
    "write_time_ms": 88203311,
    "sync_time_ms": 120442,
    "buffers_written": 20331022,
    "checkpoints_per_hour": 12.1
  },
  "bgwriter": {
    "buffers_clean": 402211,
    "maxwritten_clean": 12,
    "buffers_alloc": 88201122
  },
  "backend_io": {
    "writes": 12044,
    "fsyncs": 0
  },
  "wal": {
    "wal_records": 902211044,
    "wal_fpi": 20331022,
    "wal_bytes": 1802201133056,
    "wal_buffers_full": 44
  },
  "settings": {
    "checkpoint_timeout": "5min",
    "max_wal_size": "8GB"
  }
}

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.