Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
postgresai는 AI 에이전트가 데이터베이스 문제를 해결하는 데 필요한 구조화된 컨텍스트를 제공하는 도구입니다. 기존 모니터링 대시보드를 넘어, 문제 감지부터 근본 원인 분석 및 해결까지의 전체 흐름을 추적할 수 있도록 설계되었습니다. 이는 LLM 소비에 최적화되어 있으며, 45가지 이상의 상태 검사와 활성 세션 기록 기능을 제공합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기npm
License
PostgreSQL
CLI Coverage
Reporter Coverage
모니터링, 상태 검사(health checks), 근본 원인 분석 — 인간과 AI 에이전트를 위해 구축됨
Live Demo ·
Documentation ·
Get started
GitLab, Miro, Chewy, Suno, Supabase, Gadget 등과 같은 회사에서 PostgresAI 팀의 작업으로 검증되었으며(https://postgres.ai) — 이제 인간과 AI 에이전트가 쉽게 사용할 수 있도록 패키징되었습니다.
기존 모니터링 도구는 대시보드를 제공합니다. postgresai는 AI 에이전트가 실제로 문제를 해결하는 데 필요한 컨텍스트를 제공합니다.
Self-Driving Postgres의 일부입니다. 이는 Postgres를 자율적으로 만들기 위한 PostgresAI의 오픈 소스 이니셔티브입니다.
postgres.ai에서 무료 계정을 만드세요.
npx postgresai auth
이 명령은 브라우저를 열어 로그인하도록 하고 API 키를 로컬에 저장합니다.
PGPASSWORD=secret npx postgresai checkup postgresql://user@host:5432/dbname
Open console.postgres.ai에서 다음을 확인하세요:
<details open> <summary>데모 보기</summary> <div align="center"> <img src="https://raw.githubusercontent.com/postgres-ai/postgresai/HEAD/assets/demo-checkup.gif" alt="postgresai 체크업 데모" width="700"> </div> </details>오프라인 모드:
--no-upload를 추가하여 계정 없이 또는 보고서 데이터를 PostgresAI API로 전송하지 않고 로컬에서 실행할 수 있습니다.
특정 검사를 실행하거나 오프라인에서 작업하세요:
# 특정 검사 실행
npx postgresai checkup --check-id H002 postgresql://...
...
Markdown 변환은 PostgresAI API에 의해 수행되며 전체 보고서 JSON을 전송합니다. 따라서 --markdown과 --no-upload를 함께 사용할 수 없습니다. 로컬 전용 출력을 위해서는 대신 --json 또는 --output을 사용하세요.
팁:
npx pgai checkup도 작동합니다. Bun을 선호한다면bunx postgresai를 사용하세요.
대시보드를 통한 지속적인 모니터링을 위해 Docker가 설치된 Linux 머신에 전체 스택을 설치하세요:
# 샘플 데이터로 빠른 데모 실행
npx postgresai mon local-install --demo
# → http://localhost:3000에서 열기
...
console.postgres.ai에서 API 키를 받거나, 거기서 완전 관리형 버전을 사용하세요.
모든 진단 쿼리는 관찰자 효과(observer effect)를 피하도록 신중하게 설계되었습니다. 이들은 타임아웃, 행 제한(row limits), 비차단 접근 방식을 사용합니다. 수십 TiB의 데이터, 수백 kTPS, 그리고 수백만 개의 DB 객체를 가진 프로덕션 데이터베이스에서 테스트되었습니다.
실행 전에 설정 SQL을 미리보세요:
npx postgresai prepare-db --print-sql postgresql://... # 생성될 내용을 검토합니다
prepare-db 단계는 최소 권한을 가진 읽기 전용 postgres_ai_mon 사용자를 생성하고, pg_stat_statements를 활성화하며, 몇 가지 헬퍼 뷰(helper views)와 함께 postgres_ai 스키마를 생성합니다.
| 구성 요소 | 목적 |
|---|---|
| Express checkup | 즉각적인 상태 확인 — 설정 불필요 |
| ... |
postgresai는 구조화된 PostgreSQL 진단 정보를 AI 에이전트에게 제공하도록 설계되었습니다.
마켓플레이스에서 설치하세요:
claude plugin marketplace add postgres-ai/postgresai
claude plugin install pgai@postgresai
그런 다음 Claude에게 데이터베이스를 확인하도록 요청하세요. postgresai 스킬(SKILL.md)은 PostgresAI 모니터링을 배포하고 정확한 수정 사항과 함께 문제를 보고합니다. 다른 에이전트는 npx skills add postgres-ai/postgresai --skill postgresai로 스킬을 설치합니다.
console.postgres.ai에서 이슈(Issues)를 다루세요:
/pgai:issues
# AI 코딩 도구에 MCP 서버 설치
npx postgresai mcp install
이를 통해 AI 에이전트는 console.postgres.ai의 이슈 및 조치 항목(Action Items)을 IDE 내에서 직접 다룰 수 있게 됩니다.
# 체크업 출력을 모든 LLM으로 파이프하기
npx postgresai checkup --json postgresql://... | llm -s "analyze this Postgres health report"
...
postgresai checkup --check-id H002를 실행하여 사용하지 않는 인덱스를 찾습니다.DROP INDEX를 제안하거나 PR(Pull Request)을 생성합니다.체크업 (express 모드)의 경우:
전체 모니터링 스택의 경우:
pg_stat_statements 확장 기능 활성화npx pgai checkup도 작동합니다.npx postgresai auth는 건너뛰고 다음을 따르세요:
--no-upload 사용--api-key 생략| 데모 | demo.postgres.ai (로그인: demo / demo) |
| ... |
PostgresAI — 자율 주행 Postgres
</div>개발자를 위한 경우:
postgresai mon local-install --demo
2분 이내에 데모 데이터가 포함된 완전한 모니터링 환경을 구축하세요.
운영 환경(Production)의 경우:
postgresai mon local-install --api-key=your_key
# 이후 데이터베이스를 추가합니다
postgresai mon targets add "postgresql://user:pass@host:port/DB"
# 인스턴스 관리
postgresai mon targets add "postgresql://user:pass@host:port/DB"
postgresai mon targets list
...
⚠️ 버전 0.15.0에서 주요 변경 사항 — 번들된 PostgreSQL 15 → 17로의 데이터 마이그레이션 필요.
0.15.0 버전에서는 스택에 포함된 PostgreSQL을 15에서 17로 업그레이드합니다 (sink-postgres, 그리고 데모용 target-db / target-standby). PostgreSQL의 온디스크 형식은 주요 버전 간에 호환되지 않기 때문에, 새로운 이미지는 PostgreSQL 15 데이터 디렉터리에서는 시작을 거부합니다. 인플레이스(in-place) 업그레이드는 데이터를 마이그레이션할 때까지 작동하지 않습니다. 아무것도 자동으로 삭제되지는 않으며, 외부에서 모니터링하는 데이터베이스는 영향을 받지 않지만, 스택을 다시 시작하기 전에 번들된 데이터베이스에 대해서는 조치를 취해야 합니다.
**sink-postgres**는 기록적인 모니터링 측정값을 저장하므로 다음 중 하나를 선택하세요:
# `mon stop`/업그레이드 전에, sink-postgres (PG15)가 실행 중일 때:
docker compose exec sink-postgres pg_dumpall -U postgres > sink-pg15.sql
# 스택이 PG17로 올라온 후 (sink-postgres는 비어있는 상태로 재생성됨):
...
- **새로 시작 (Start fresh)** — 볼륨을 제거하여 PostgreSQL 17이 깨끗한 데이터 디렉터리를 초기화하도록 합니다.
이렇게 하면 **이전에 수집된 모든 모니터링 측정값이 폐기**됩니다 (새로운 메트릭은 처음부터 누적됨). `docker volume ls | grep sink_postgres_data`로 볼륨을 찾은 다음, 스택이 중지된 상태에서 `docker volume rm <name>` 명령어를 실행하세요.
데모용 `target-db` / `target-standby`는 폐기 가능한 샘플 데이터만 포함하고 있으므로, 이들 역시 같은 방식으로 볼륨을 초기화하거나 (또는 `postgresai mon local-install --demo`를 다시 실행하여 재생성) 처리하세요.
PostgreSQL 17을 검증할 때까지 이전 PostgreSQL 15 볼륨을 백업으로 보관하세요. 전체 업그레이드 단계는 아래에 있으며, [모니터링 업그레이드 문서](https://postgres.ai/docs/monitoring/getting-started)도 참고하세요.
`postgres_ai` 모니터링을 새 버전으로 업그레이드하려면:
### 1단계: CLI 업데이트
```bash
npm install -g [email protected]
또는 npx를 사용하는 경우:
npx [email protected] --version # 새 버전 확인
postgresai mon stop
mon update는 .env 파일을 마이그레이션(새로 필요한 키 추가), docker-compose.yml을 새로운 스택 버전으로 새로고침하고, 이미지를 가져옵니다. 이 모든 과정은 사용자가 관리하는 instances.yml을 보존하면서 진행됩니다. 이는 PGAI_TAG를 변경하지 않으므로, 새 이미지 태그를 먼저 직접 설정해야 합니다. 그렇지 않으면 mon update는 이전 버전을 재가져오기하고 재시작만 할 것입니다:
# 모니터링 디렉토리(일반적으로 ~/.postgres_ai/)에서 .env 파일을 편집하여
# PGAI_TAG를 업그레이드하려는 버전으로 설정합니다 (새 CLI 버전에 맞춰야 합니다).
# 예: 0.15 라인의 경우: PGAI_TAG=0.15.0
...
이 과정은 다음을 수행합니다:
.env 키 추가 (기존 값, 비밀 정보, instances.yml 대상은 보존됨)npm install -g)의 경우 새로운 스택 버전에 맞게 docker-compose.yml을 새로고침합니다. 이때 이전 파일은 docker-compose.yml.bak-<oldtag>-<hash>로 백업됩니다 (반복 실행 시 원본이 덮어쓰여지지 않음). 이는 sink-prometheus의 VM_AUTH_*와 같이 새로 필요한 서비스 설정을 연결해주는 역할을 합니다. 가져온 compose 파일은 현재 사용 중인 파일을 대체하기 전에 검증되므로, 네트워크 프록시/로그인 페이지가 이를 망가뜨릴 수 없습니다. 이미 git 체크아웃된 경우 이 과정은 git pull을 통해 처리되므로 건너뜁니다.PGAI_TAG에 대한 Docker 이미지 가져오기참고: .env 파일에는 PGAI_TAG (Docker 이미지 버전 태그), REPLICATOR_PASSWORD (데모 대기 복제 사용자용 생성된 비밀번호), VM_AUTH_USERNAME, VM_AUTH_PASSWORD, 그리고 선택적으로 GF_SECURITY_ADMIN_PASSWORD (Grafana 관리자 비밀번호) 및 PGAI_REGISTRY (사용자 지정 Docker 레지스트리)를 포함한 모니터링 스택의 구성 정보가 담겨 있습니다. postgresai mon local-install은 기존의 REPLICATOR_PASSWORD와 VM_AUTH_* 값을 유지하거나 누락된 경우 새 값을 생성합니다. Docker Compose는 이러한 값들을 필요로 하며 알려진 기본 비밀번호를 사용하지 않습니다. 또한, 이 파일에는 VictoriaMetrics 관리 엔드포인트 키인 VM_DELETE_AUTH_KEY, VM_SNAPSHOT_AUTH_KEY, VM_FORCE_MERGE_AUTH_KEY 및 VM_PPROF_AUTH_KEY (0.17에 추가됨, #359 참조)가 포함되어 있으며, 이들은 동일한 유지 또는 생성 수명 주기를 따르며 메트릭 저장소를 파괴할 수 있는 엔드포인트를 보호합니다.