pg-bloat-detective
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BLOAT_DB | No | Path to the timeline database file, e.g. "/abs/path/pg-bloat-detective/timeline.db" | |
| BLOAT_DSN | No | Postgres DSN for the read-only connection, e.g. "dbname=bloatdemo user=postgres host=localhost port=5433" |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| bloat_checkA | Diagnose PostgreSQL bloat from a collected timeline. Read-only: only reads the local SQLite timeline file, never touches Postgres. Args: db: Path to the SQLite timeline file (default: BLOAT_DB env, 'timeline.db'). Collect one first with bloat_collect, or pass any timeline.db path. Returns: findings: list of {table, verdict, evidence, action} — verdict is one of normal | vacuum-starved | blocked-by-idle-xact | blocked-by-slot | blocked-by-prepared | blocked-by-active-xact | needs-rewrite | index-bloated | index-unused. Evidence carries dead/live counts, pgstattuple approx %, pgstatindex %, blocker pid+query. |
| bloat_collectA | Take a read-only Postgres snapshot into the timeline, then return fresh verdicts. Safe on prod: read-only transaction, 5s statement timeout, needs only pg_stat_* views + optional pgstattuple extension. No writes, no agents. Args: dsn: Postgres DSN, e.g. 'dbname=app user=readonly host=db.internal'. Default: BLOAT_DSN env. Never logs the password. Returns: {snapshot: 'saved', db: path, findings: [...with action per table/index]}. |
| bloat_timelineA | Dead-tuple + approx + index-bloat time series: when the bloat started. Read-only on the local timeline file. Args: table: Table name to filter (e.g. 'churn'). Empty = all tables. db: Path to the SQLite timeline file (default: BLOAT_DB env). Returns: {table: {dead: [{ts, live, dead}], approx_pct: [{ts, dead_pct}]}, index_bloat: {index: [{ts, bloat_pct}]}}. Rising dead = vacuum-starved; spike-then-zero = was blocked, blocker left. |
| bloat_blockersA | Who is pinning VACUUM: blocker pid + query + xmin age + slot. Read-only on the local timeline file. Priority: prepared-xact > stale-slot
|
| bloat_live_diagnoseA | One-shot live diagnosis without touching your timeline file. Snapshots into a throwaway temp DB, diagnoses, discards it. Read-only on Postgres (read-only tx, 5s timeout). Safest option for prod DSNs. Args: dsn: Postgres DSN (default: BLOAT_DSN env). Password never logged. Returns: {findings: [...with action], blockers: [...]} — same verdict set as bloat_check, plus the current xmin-holder evidence. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 5 tools
The set separates live collection (bloat_collect) from one-shot live diagnosis (bloat_live_diagnose) and from timeline readers (bloat_check, bloat_blockers, bloat_timeline). bloat_collect and bloat_live_diagnose return similar findings but descriptions clearly state saving vs discarding the snapshot. bloat_check and bloat_blockers overlap since check already reports blockers, though blockers adds focused pid/slot detail.
All names use snake_case with a consistent 'bloat_' prefix, making the domain and tool family immediately obvious. The pattern is predictable and no naming ambiguity exists.
Five tools is well-scoped for a focused diagnostic server: collect snapshot, check current state, live one-shot diagnosis, identify blockers, and show timeline. Each tool earns its place without redundant or missing core operations.
Coverage is strong for read-only PostgreSQL bloat diagnosis: collection, live diagnosis, timeline analysis, blocker identification, and current verdicts. Minor gaps exist around timeline management (pruning, export, listing snapshots) and remediation, though read-only safety appears intentional.