health_check

​

Features

• Connection pool state: Total/active/idle session counts, idle-in-transaction sessions, the configured connection ceiling, and how long the longest-running query or idle-in-transaction session has been open
• Buffer cache hit ratio: Percentage of reads served from cache vs disk, useful for spotting an undersized cache before it becomes a production incident
• Per-engine support: Implemented for PostgreSQL, MySQL, MariaDB, and SQL Server. SQLite has no connection pool or cache-hit concept to report, so health_check returns an UNSUPPORTED error there
• Graceful degradation: On MySQL/MariaDB/SQL Server, some metrics require an elevated privilege the connected user may not have. Rather than failing outright, health_check returns whatever it can and adds a notes entry explaining what’s missing
• Opt-in only: Not part of the default tool pair — must be explicitly enabled per source

​

Usage

{
  "success": true,
  "data": {
    "source_id": "production",
    "connections": {
      "total": 12,
      "active": 2,
      "idle": 9,
      "idle_in_transaction": 1,
      "idle_in_transaction_aborted": 0,
      "max_connections": 100,
      "longest_idle_in_transaction_seconds": 42.1,
      "longest_active_query_seconds": 0.03
    },
    "buffer_cache": {
      "hit_ratio_pct": 99.12,
      "blocks_hit": 8452193,
      "blocks_read": 74301
    }
  }
}

​

Reduced-privilege output

{
  "success": true,
  "data": {
    "source_id": "production",
    "connections": { "...": "..." },
    "buffer_cache": { "...": "..." },
    "notes": [
      "Connected user lacks the PROCESS privilege: PROCESSLIST visibility is restricted to the connecting user's own sessions, and this diagnostic session is excluded from the count, so connection counts and active-query duration may under-report (down to 0). Idle-in-transaction detection is unavailable."
    ]
  }
}

​

Enabling health_check

[[sources]]
id = "production"
dsn = "postgres://user:pass@localhost:5432/mydb"

[[tools]]
name = "execute_sql"
source = "production"
readonly = true

[[tools]]
name = "search_objects"
source = "production"

[[tools]]
name = "health_check"
source = "production"