DryRun PostgreSQL MCP
프로덕션(production) 연결이 필요 없는 PostgreSQL MCP 서버입니다.
dryrun은 AI 에이전트, IDE, CI에 완전한 스키마 인식(schema awareness)을 제공합니다. 라이브 데이터베이스 연결이 아닌 오프라인 스냅샷으로부터 작동합니다. 스키마를 린팅(lint)하고, 쿼리를 검증하며, 마이그레이션 안전성을 확인하고, 외래 키 그래프(foreign key graphs)를 탐색할 수 있습니다. 모든 과정에서 자격 증명(credentials)이 DBA의 장치를 벗어날 필요가 없습니다.
dryrun은 boringSQL 제품군에 속하며, RegreSQL 및 Fixturize와 함께 제공됩니다.
문제점 (The problem)
LLM/AI 코딩 어시스턴트는 코드/SQL 쿼리를 작성하는 데 매우 능숙합니다. 하지만 이들은 시각 장애인과 같습니다. 그들은 사용자의 스키마, 인덱스 또는 제약 조건(constraints)을 알지 못합니다. 이들은 가장 바쁜 테이블에 ACCESS EXCLUSIVE 잠금(lock)을 거는 마이그레이션을 생성하여 애플리케이션을 다운시킬 수도 있습니다.
일부 PostgreSQL MCP 서버는 데이터베이스 연결을 요청합니다. 그리고 관리 작업을 수행하려면 SUPERUSER 권한이 필요할 수 있습니다. 하지만 이는 마치 문제를 일으키는 것을 요구하는 것과 같습니다.
우리는 이미 이것이 어디로 이어지는지 목격했습니다: AI 에이전트에 의해 프로덕션 데이터베이스가 삭제된 사례, 그리고 읽기 전용(read-only)이어야 했던 PostgreSQL MCP 서버의 SQL 인젝션 사례들입니다.
모델은 데이터베이스를 쿼리할 필요가 없습니다. 모델이 필요한 것은 스키마, 즉 구조, 제약 조건, 통계 및 버전별 동작을 이해하는 것입니다. 그 지식은 구조적인 것입니다. 이는 쿼리 간에 변화하는 것이 아니라 마이그레이션을 배포할 때 변화합니다.
DryRun 기능 (DryRun features)
dryrun은 두 가지입니다: CLI 도구와 MCP 서버입니다. CLI는 스키마를 추출하고 분석합니다. MCP 서버는 그 분석 결과를 AI 어시스턴트에게 노출합니다. 이 둘은 의도적으로 분리되어 있습니다.
CLI - 추출 및 분석
CLI는 PostgreSQL 데이터베이스에 연결하여 전체 카탈로그(테이블, 뷰, 인덱스, 제약 조건, 파티션, 함수, 열거형(enums), RLS 정책, 트리거, 확장 기능, GUCs)의 내부 구조를 분석하고 스냅샷을 .dryrun/history.db에 작성합니다. 이 스냅샷이 다른 모든 것의 진실 공급원(source of truth)입니다.
스냅샷을 확보하면 CLI는 오프라인으로 작동합니다:
- Lint - 20가지 이상의 컨벤션 규칙(명명 규칙, 데이터 타입, 기본 키, 타임스탬프, 파티셔닝)과 13가지 구조 감사 규칙(중복 인덱스, FK 커버리지, 순환 FK, vacuum 튜닝)
- 마이그레이션 안전성(Migration safety) - 잠금 유형 분석, 지속 시간 추정, 테이블 재작성 감지, 각 DDL 구문에 대한 안전한 대안 제시
- 쿼리 검증(Query validation) - libpg_query를 통한 SQL 파싱, 실제 스키마에 대한 컬럼 참조 확인, 안티 패턴 탐지
- 스냅샷 비교(Snapshot diff) - 스냅샷 간의 스키마, 플래너 통계 또는 활동을 비교하고 라이브 데이터베이스 대비 드리프트(drift) 감지
- 쿼리 통계 - 노드별
pg_stat_statements를 캡처하고, ORM 쿼리 변형을 형태로 통합하며, 두 개의 캡처를 비교하여 새롭거나 느려진 쿼리를 표면화
- 다중 노드 통계 - 복제본별 통계, seq_scan 핫스팟, 라우팅 불균형
MCP 서버 - AI 어시스턴트에게 스키마 지능을 부여하세요
MCP 서버는 동일한 스냅샷을 읽습니다. 이 서버는 stdio 또는 SSE를 통해 9가지 도구를 노출합니다: 스키마 탐색 및 검색, 쿼리 검증, 플랜 분석, 마이그레이션 확인, 린팅(linting), vacuum 상태 점검, 그리고 캡처된 pg_stat_statements 상위 쿼리입니다. 라이브 데이터베이스에 연결하면 세 가지 도구(explain_query, check_drift, columnar_report)가 추가됩니다. 사용자의 AI 어시스턴트는 SQL을 작성하는 동안 데이터베이스를 이해하게 됩니다.
데이터베이스 연결이 필요하지 않습니다. 어시스턴트는 절대로 자격 증명(credentials)을 볼 수 없습니다.
오프라인 작동의 이점
스키마 컨텍스트는 라이브 연결이 아닌 파일에 있어야 합니다. 컬럼 타입, 행 추정치(row estimates), 인덱스 정의, 외래 키(FK) 관계, 그리고 PostgreSQL 버전 등 모든 정보를 한 번 내보내서 저장소(repo)에 커밋할 수 있습니다. 데이터베이스 접근 권한을 가진 사람 한 명이 스키마를 덤프하면 됩니다. 이후의 모든 사용자들(인간이든 AI 에이전트든)은 자격 증명 없이도 전체 스키마 지능을 얻게 됩니다.
자격 증명(Credentials)은 DBA의 장비에서 벗어나서는 안 됩니다. MCP 서버가 유용하게 작동하려면 DATABASE_URL이 필요하다면, 이를 사용하는 모든 개발자는 프로덕션 자격 증명을 갖추어야 합니다. 이는 AI와는 전혀 관련 없는 보안 문제입니다.
서버는 분석을 수행해야 하며, 단순 전달(pass-through)만 해서는 안 됩니다. 원시 \d+ 출력을 반환하는 것은 직접 채팅창에 붙여넣는 것보다 약간 나은 수준입니다. 진정한 가치는 그 데이터를 해석하는 데 있습니다. 즉, 마이그레이션이 사용자의 PostgreSQL 버전에 안전한지 확인하고, 누락된 FK 인덱스를 플래그 지정하며, 실제 스키마와 컬럼 참조를 검증하는 것입니다.
설치 (Install)
PostgreSQL 14 이상이 필요합니다. 이전 버전의 서버는 거부되지는 않지만—dryrun은 경고 메시지를 표시하고 가능한 것을 포착하지만—테스트되지 않았으며, 일부 스트림(특히 플래너 통계)은 사용할 수 없습니다. 아래 표는 업스트림에서 여전히 지원되는 가장 오래된 릴리스를 추적합니다.
Homebrew:
Homebrew 6.0에서는 포뮬러가 로드되려면 타사 탭(third-party taps)에 대한 신뢰 설정이 필요합니다:
brew trust --tap boringsql/boringsql
brew install boringsql/boringsql/dryrun
Homebrew 5.x 이하 버전에서는 brew trust 단계를 건너뛰세요. 만약 전체 탭을 신뢰하고 싶지 않다면, brew trust --formula boringsql/boringsql/dryrun 명령어로 해당 포뮬러만 신뢰할 수 있습니다.
npm / npx:
이미 Node가 설치되어 있다면, 아무것도 설치하지 않고도 dryrun을 실행할 수 있습니다:
npx @boringsql/dryrun --version
이 명령어는 사용자의 플랫폼(darwin-arm64, linux-x64, linux-arm64)에 맞는 미리 빌드된 바이너리를 가져와 캐시하고 버전을 출력합니다. dryrun을 영구적으로 PATH에 추가하려면 다음 단계를 따르세요:
npm install -g @boringsql/dryrun
dryrun --version
npm 패키지는 동일한 Go 바이너리를 래핑하며, 모든 CLI 명령어는 동일하게 작동합니다. lint와 같은 명령어는 먼저 스키마 스냅샷이 필요하므로 Quickstart를 참조하세요. 미리 빌드된 바이너리는 macOS (Apple Silicon + Intel), Linux (x64 + arm64), Windows x64를 지원합니다. 다른 플랫폼(Alpine/musl, Windows arm64)에서는 Homebrew를 사용하거나 소스에서 빌드해야 합니다.
소스에서 빌드:
Go 1.26 이상이 필요합니다. 설치되어 있지 않다면 go.dev/dl을 통해 설치하세요.
git clone https://github.com/boringsql/dryrun.git
cd dryrun
go build -o bin/dryrun ./cmd/dryrun
바이너리는 bin/dryrun에 있습니다.
30초 데모
dryrun을 설치한 후, 데이터베이스나 설정 없이 이 리포지토리의 클론에서 준비된 스키마 스냅샷을 검사(lint)해 보세요:
git clone https://github.com/boringsql/dryrun.git
cd dryrun/examples/demo
dryrun lint
(npm이나 Homebrew로 설치했지만 리포지토리를 클론하지 않은 경우, examples/demo가 없습니다. Quickstart로 이동하여 dryrun이 사용자의 스키마를 가리키도록 설정하세요. 아래 샘플 출력은 lint가 생성하는 결과입니다.)
[ERROR] public.audit_log: 테이블에 기본 키(primary key)가 없습니다
수정: 기본 키 추가 (bigint GENERATED ALWAYS AS IDENTITY 권장)
[WARN ] public.audit_log: 범위 파티션 간의 공백이 있습니다: '2024-07-01'에서 끝나고 다음은 '2024-10-01'에서 시작합니다
...
데이터베이스가 필요하지 않습니다. 오프라인 스냅샷만으로 완전히 작동합니다.
이 데모는 MCP(Multi-Cloud Platform)를 통해서도 동일하게 작동합니다. examples/demo에서 서버를 사용자의 어시스턴트와 등록하세요:
claude mcp add dryrun -- npx -y @boringsql/dryrun mcp-serve
그런 다음 해당 디렉토리에서 다음과 같이 질문하세요: "제가 가진 테이블은 무엇이며, 어떤 문제가 있나요?"
MCP 서버
단 하나의 명령어로 서버를 AI 에이전트에 연결합니다. setup은 Claude Code, Cursor, Codex, Zed를 감지하고, 에이전트의 MCP 설정을 작성하며, 에이전트가 SQL을 작성하기 전에 스키마를 확인하도록 지침을 AGENTS.md/CLAUDE.md에 추가합니다:
직접 에이전트를 선택하거나 비대화형 셸에서 실행하려면 --agents를 전달하세요:
dryrun setup --agents=claude,cursor
서버를 수동으로 등록하는 방법:
claude mcp add dryrun -- dryrun mcp-serve
...
소스에서 빌드한 경우, 바이너리의 전체 경로를 사용하십시오:
claude mcp add dryrun -- /path/to/dryrun mcp-serve
또는 설치 과정 없이 클라이언트가 npx를 가리키도록 할 수 있습니다:
claude mcp add dryrun -- npx -y @boringsql/dryrun mcp-serve
이 형태에 대한 원시 클라이언트 설정은 다음과 같습니다:
{
"mcpServers": {
"dryrun": {
...
서버는 현재 프로젝트의 .dryrun/history.db에서 최신 스냅샷을 읽어옵니다. 데이터베이스 자격 증명이 필요하지 않으며, 어시스턴트는 오프라인 스냅샷으로부터 전체 스키마 인텔리전스를 얻습니다.
스냅샷이 없더라도 서버는 시작되며, 도구들은 스키마가 로드되지 않았다고 응답합니다. dryrun init --db "$DATABASE_URL"로 하나를 캡처하거나 팀원이 푸시한 것(dryrun snapshot pull --from-path ./snapshots, Quickstart 참조)을 가져오면, 서버는 재시작 없이 다음 도구 호출에서 이를 인식합니다.
여러 데이터베이스가 있는 프로젝트의 경우, 데이터베이스당 dryrun mcp-serve를 실행하고 클라이언트 설정에 서버 항목을 추가해야 합니다. 단일 MCP 프로세스 내에서의 네이티브 다중 데이터베이스 서비스는 #7에서 추적됩니다.
실시간 데이터베이스 설정, SSE 전송, Claude Desktop 구성에 대한 내용은 튜토리얼을 참조하십시오.
Quickstart
시작하는 방법은 두 가지가 있으니, 환경에 맞는 것을 선택하세요.
옵션 A: 데이터베이스 접근 권한이 있는 경우
PostgreSQL 인스턴스(로컬, 개발 또는 프로덕션)에 연결할 수 있다면, 하나의 명령어로 모든 것이 처리됩니다:
dryrun init --db "$DATABASE_URL"
이는 dryrun.toml (여기에 [project] id 및 기본 프로필 포함), .dryrun/ 데이터 디렉토리를 생성하고, 데이터베이스를 .dryrun/history.db에 캡처합니다. 스냅샷은 (project_id, database_id)로 키가 지정됩니다. 프로젝트에 여러 데이터베이스가 있는 경우, 각 프로필별로 database_id를 설정하십시오 (예: auth, billing). 전체 구성 참조는 docs/dryrun-toml.md를 참조하십시오.
옵션 B: 다른 사람이 데이터베이스에 접근하는 경우
자격 증명을 가진 사용자가 한 번 캡처하여 공유 디렉터리(저장소 내 또는 양쪽에서 접근 가능한 모든 곳)에 푸시합니다:
dryrun init --db "$DATABASE_URL"
dryrun snapshot push --to-path ./snapshots
그들은 dryrun.toml과 ./snapshots를 모두 커밋합니다. 다른 모든 사용자는 다음을 풀(pull)합니다:
dryrun snapshot pull --from-path ./snapshots
snapshot pull은 스냅샷을 .dryrun/history.db에 로드하며, 이 경우 해당 장치에서 데이터베이스가 필요하지 않습니다.
dryrun.toml을 커밋하는 것은 선택 사항이 아닙니다: 스냅샷은 (project_id, database_id)로 키가 지정되며, dryrun init은 실시간 데이터베이스 이름에서 database_id를 생성합니다. --db 없이 dryrun init을 실행한 팀원은 다른 database_id를 얻게 되며, 이 경우 소스에 없는 키를 찾았기 때문에 pull이 0 copied로 보고합니다.
푸시된 스냅샷은 스키마와 함께 플래너(planner) 및 활동 통계(activity stats)를 포함하므로, 크기 조정(sizing) 및 비큐움 데이터(vacuum data)가 필요한 오프라인 도구들도 작동합니다. 이는 일반 JSON 내보내기(export)로는 불가능한 것입니다. 디렉터리 대신 레지스트리를 사용하려면 dryrun remote add와 snapshot push --remote를 참조하십시오. 사람이나 에이전트가 읽을 수 있는 JSON을 전달하려면, 여전히 dryrun dump-schema가 이를 작성합니다. 이것은 입력(input)이 아니라 내보내기(export)입니다.
사용하기
모든 명령어는 .dryrun/history.db에서 오프라인으로 작동합니다. 각 프로젝트는 자체의 dryrun.toml과 .dryrun/을 가지며, 전역 상태(global state)가 없습니다. .dryrun/를 .gitignore에 추가하십시오.
스냅샷은 .dryrun/history.db에 존재하며, (project_id, database_id)로 키가 지정됩니다. 이것이 유일한 스키마 소스입니다: MCP 서버, lint, 그리고 drift 모두 여기서 읽습니다. 이전 dryrun에서 남겨진 .dryrun/schema.json은 무시됩니다.
저장된 스냅샷을 읽는 명령어들은 최신 데이터가 [history] stale_after (기본값 72시간, "0"은 비활성화)보다 오래되었을 때 경고하며, 따라서 오래된 사본이 현재 상태로 인식되지 않습니다. dryrun.toml를 참조하십시오.
히스토리를 프로젝트 외부로 유지하려면, DRYRUN_HISTORY_DB를 절대 경로(absolute path)로 설정하십시오. 모든 명령어는 어떤 디렉토리에서든 .dryrun/history.db 대신 해당 파일을 사용합니다. 이는 공유 리더(shared reader)에게 적합한데, 타이머가 하나의 파일에 snapshot pull을 실행하고, 어느 체크아웃(checkout)에서 시작된 MCP 서버도 이를 읽을 수 있습니다. --history-db 옵션이 여전히 가장 좋습니다. 먼저 타이머를 시작하십시오. 파일이 존재하기 전에 시작된 서버는 pull이 파일을 생성한 후 나중에 도구 호출(tool call)을 통해 이를 가져옵니다. 상대 경로 값은 거부됩니다. 확장되지 않은 ~(MCP JSON 설정에서 흔함)는 ./~를 생성하는 대신 명확하게 오류를 발생시킵니다.