TL;DR

pgbot은 PostgreSQL 통계 뷰를 읽어 상태 점수와 장애 징후를 계산하는 독립형 Go CLI 도구입니다. `pg_monitor` 역할과 읽기 전용 트랜잭션을 사용하고 별도 서비스나 데이터베이스 변경 없이 connections, locks, queries, indexes, vacuum, replication 등을 점검합니다. 로컬 baseline과 버전 관리되는 `--json` 계약으로 변화 추적과 CI 게이트를 지원하며, SARIF·JUnit·Prometheus 출력도 제공합니다. MCP 서버와 Claude Code plugin을 연결할 수 있지만 AI 호출은 선택 사항이고, 실제 finding은 항상 로컬 Go 코드에서 결정론적으로 산출됩니다.

핵심 포인트

• pgbot은 PostgreSQL 14~18에 연결하는 독립형 Go CLI 도구로, 별도 Agent나 서버 없이 통계 뷰를 읽어 건강 상태를 계산합니다. `pg_monitor` 로그인 역할과 최대 4개의 연결만 사용하며 각 조회를 `BEGIN READ ONLY`와 제한 시간 안에서 처리합니다. 운영 데이터베이스를 변경하지 않고 수 초 안에 장애 징후를 확인하려는 상황에 적합합니다.
• 핵심 진단은 SQL 통계에서 Go 코드로 결정론적으로 계산하며, `inspect`가 점수와 CRITICAL·WARNING·NOTE·GOOD 항목을 함께 출력합니다. `queries`, `indexes`, `tables`, `vacuum` 명령은 느린 쿼리, 미사용 인덱스, 대형 테이블, autovacuum 상태를 각각 좁혀 읽습니다. `pg_stat_statements`가 없으면 해당 영역을 사용 불가로 표시하고 설치 절차를 안내하므로 부분적인 결과를 정상 상태로 오인할 가능성을 줄입니다.
• 각 실행은 로컬 baseline을 저장하고 이후 실행에서 쿼리 지연, 순차 스캔, 인덱스 사용 변화 같은 차이를 비교합니다. `--json`은 현재 버전 1.2.0의 PII-free 계약과 `sampled`, `cumulative`, `scraped`, `unavailable` exactness 정보를 제공하며, `diff`는 실제 비교 시간과 통계 초기화 여부를 함께 기록합니다. CI에서는 exit code, SARIF, JUnit, Prometheus 형식과 `--fail-on-new`를 이용해 새 스키마 문제나 운영 장애만 게이트할 수 있습니다.
• MCP 서버와 Claude Code plugin을 통해 동일한 읽기 전용 결과를 AI Agent의 도구로 연결할 수 있습니다. `advise`는 `hypopg`로 가상 인덱스를 만들고 `EXPLAIN (GENERIC_PLAN)` 비용 변화를 확인할 뿐 실제 인덱스나 쿼리를 실행하지 않습니다. AI 기능인 `ask`와 `explain`만 PII-free Context를 OpenAI 또는 Gemini로 보내며, 그 외 명령은 외부 서비스 없이 로컬에서 동작합니다.

이미지 분석