pg_cache_hit_ratio — Der schnellste Health-Check für PostgreSQL — Blog

Was macht dieses Tool?

pg_cache_hit_ratio berechnet die Buffer-Cache-Trefferquote der aktuellen Datenbank: das Verhältnis von Datenblöcken, die aus dem Shared Buffer Cache gelesen wurden, zu denen, die von der Festplatte gelesen werden mussten. Eine Quote über 99% ist ideal — unter 95% deutet auf zu wenig Arbeitsspeicher oder ein falsches shared_buffers-Setting hin.

Wie wird es aufgerufen?

Verbindung herstellen

Bevor ein Performance-Tool aufgerufen werden kann, muss eine Verbindung zur Zieldatenbank hergestellt werden. mcp-postgres unterstützt mehrere Datenbankprofile — ideal für Multi-Cluster-Setups:

● ● ● Claude CLI — Verbindung

claude> Verbinde mit Profil "production-db"

▶ Calling tools...
→ pg_connect { "profile": "production-db" }

{
"status": "connected",
"database": "mcp_test",
"version": "PostgreSQL 16.x",
"host": "db.example.com"
}

Claude CLI (natürliche Sprache)

● ● ● Claude CLI — Cache-Analyse

claude> Wie effizient ist mein Buffer Cache?

▶ Calling tools...
→ pg_cache_hit_ratio {}

Buffer Cache Hit Ratio für mcp_test: 99.10%

Details:
Blocks Hit: 1.596.791
Blocks Read: 14.581

Bewertung: EXCELLENT — Datenbank arbeitet fast vollständig aus dem RAM.

MCP Protocol (programmatisch)

● ● ● MCP Protocol — Cache-Analyse

// Programmatic invocation via MCP SDK
const result = await client.callTool("pg_cache_hit_ratio", {});

// Response:
[
{
    "datname": "mcp_test",
    "cache_hit_ratio": "99.10",
    "blocks_hit": "1596791",
    "blocks_read": "14581"
}
]

Was passiert unter der Haube?

Das Tool führt eine einzige, effiziente Query gegen pg_stat_database aus:

-- Buffer Cache Hit Ratio aus pg_stat_database
SELECT sum(blks_hit) AS heap_hit, sum(blks_read) AS heap_read, CASE WHEN sum(blks_hit) + sum(blks_read) = 0 THEN 0 ELSE sum(blks_hit)::float / (sum(blks_hit) + sum(blks_read)) END AS ratio FROM pg_stat_database WHERE datname = current_database();

Die Statistiken in pg_stat_database sind kumulativ seit dem letzten Statistik-Reset. Der Wert repräsentiert also die Gesamtleistung, nicht einen Momentaufnahme-Snapshot.

Ausgabe im Detail

datname — Name der Datenbank
cache_hit_ratio — Trefferquote als Prozentzahl (z.B. "99.10")
blocks_hit — Anzahl der aus dem Shared Buffer Cache gelesenen Blöcke
blocks_read — Anzahl der von der Festplatte gelesenen Blöcke

Praxis-Tipp: Eine niedrige Hit Ratio direkt nach einem PostgreSQL-Neustart ist normal — der Buffer Cache muss erst gefüllt werden. Warten Sie mindestens eine Stunde unter normaler Last, bevor Sie die Ratio bewerten.

Was testet die Testsuite?

Die Testsuite validiert pg_cache_hit_ratio gegen eine aktive PostgreSQL-Instanz — die Ratio wird aus den kumulativen Statistiken berechnet und erfordert keine speziellen Seed-Daten:

● ● ● vitest run — Testsuite

✓ pg_cache_hit_ratio > returns ratio between 0 and 1
✓ pg_cache_hit_ratio > includes percentage field

Test Files 1 passed (1)
Tests 2 passed (2)
Duration 124ms

Testdaten-Szenario

Für dieses Tool werden keine speziellen Seed-Daten benötigt. Die Ratio wird aus den kumulativen pg_stat_database-Statistiken berechnet, die bei jeder Datenbank-Aktivität aktualisiert werden. Die Tests stellen sicher, dass:

Die cache_hit_ratio ein numerischer Prozentwert ist
Das Ergebnis datname, blocks_hit und blocks_read Felder enthält

Zusammenfassung

pg_stat_database

Datenquelle

Ausgabefelder

Tests

read-only

Typ

pg_cache_hit_ratio ist der einfachste und schnellste Health-Check für PostgreSQL. Ein einziger Aufruf liefert eine klare Bewertung, ob der Arbeitsspeicher ausreicht. Ideal als erster Schritt in jedem Performance-Troubleshooting.

Zusammen mit pg_slow_query_digest und pg_index_advisor bildet es den Kern des /pg-perf Workflow-Skills.

pg_cache_hit_ratio — Der schnellste Health-Check für PostgreSQL