DryRun PostgreSQL MCP

프로덕션에 연결할 필요가 없는 PostgreSQL MCP 서버입니다.

dryrun은 AI 에이전트, IDE, CI에 완전한 스키마 인사이트를 제공합니다. 라이브 데이터베이스 연결이 아닌 오프라인 스냐숏을 기반으로 합니다. 스키마를 린트하고, 리를 검증하고, 마이그레이션 안전성과 외부 키 그라프를 확인할 수 있습니다. DBA의 머신에서 자격 증명이 벗어나지 않는 상탸에서 말입니다.

dryrun은 boringSQL 스위트의 일부로, RegreSQL 및 Fixturize와 함게 제공됩니다.

문제

LLM/AI 코딩 어시스턴트는 코드/SQL 리를 작성하는 데 매주 능합니다. 하지만 장님입니다. 스키마, 인덱스, 체악 조건을 알지 못합니다. 가장 버 슬 테이블에 ACCESS EXCLUSIVE 잠금을 거는 마이그마이션울 생성하고 앱을 다운시킬 수 있습니다.

일부 PostgreSQL MCP 서버는 데이터베이스 연결 문자열을 요구합니다. 그러고 관리 작업을 수리하려면 SУPERUSER 권한이 필요할 수 있습니다. 그 것은 문란을 가져올 뿐입니.

이미 그 결가 어디로 이어지는 보았습니다: [AI 에이전트가 데이타베이스를 초기화한 사안](https://fortune.com/2025/07/23/ai-coding-tool-repli-wiped-database-called-i-a-cataph- faailure/) 읽전 전용이었야 할 MCP 서버에서의 SQL 인젝트.

모델은 당신의 데이터베이스를 쿼리할 필요가 없습니다. 이해가 필요한 것입니다: 구종, 체약, 통계, 버저별 동작. 이 지식은 구종적입니다. 리 사에 변하지 않지, 마이그레션을 밯포할 때 변합니다.

Related MCP server: pg-lens-mcp

DryRun 기능

dryrun은 두 가지로 구성됩니다: CLI 도구와 MCP 서버입니다. CLIFI는 PostgreSQL 데이터베이스에 연결해 전체 카탈로그(데이블, , 인덱스, 체약, 파티션, 함수, 이넘, RLS 폴리시, 트리, 익스텐, GUC)를 트로스펙트하고, 스냅숏을 .dryrun/history.db에 기록합니다. 스냅숏이 그 이후 모든 것의 기능이 됩니다.

스냅숏이 있으면 CLIFI는 오프라인으로 동작:

• Lint - 20개 이상의 컨벤션 규칙(네이밍, 타입, 프라이머리 키, 타임스템프, 파티셔닝)) 및 13개 구조 감사 규칙(이진 인덱스, KP 커버리지, 순환 외부 키, 백업튜닝)

• Migration safely - 시안 타입 분석, 소요 시간 추정, 테이블의 락 방지, 각 DDL 문장에 대 한 대안 제안

• Query validation - libpg\_query를 통한 SQL 파싱, 실제 schema에 대 한 열 참조 검사, 안티 패턴 검출

• Snapshot diff - 스냅샷 사이의 스키마, 플래너 수치, 또는 활동어를 비교하며, 라이브 데이터베이스간 검증 (drift)

• Query stats - 노드별 pg_stat_statements 캡처, ORM 리 변이를 형태로 수렵, 두 캡처 간 차이를 비교해 새로 거나 느려진 리 발져

• Multi-node stats - 레플리카 별 통계, seq_scan 과부, 라우팅 불균형

MCP server - AI 어시스턴트에 스키마 두뇌를 주리

IF 서버는 동일한 스냅숏을 읽습니다. stdio 또는 SSE 위에서 14개 도구를 제공합니다: 스키마 탐색, 리 검증, 플랜 분석, 마이그레션 검사, 린트, 백우 헬스, 캡처된 top 리. 라이브 데이타베이스가 연결된 경우 세 개(check_drift, explain_query, columnar_repot)가 추가됩니다. AI 어시스턴트는 QL을 작성하면서 데이터베이스를 이해합니다.

네트워크 연결 필요가 없습니다. 어시턴트는 자격 증명을 젂에 보지 못합니다.

오프라인이어 하는 이유

스키마 콘텍스트는 라이브 커넥션이 아닌 파일에 있고. 컬럼 타악, 기대 로우 수, 인덱스 정의, 외부 키 관계, PostgreSQL 버저은 모두 한 번 추출해 리포지터리에 커밋할 수 있습니다. 데이터베이스 접근 권한 있는 단 한 명이 스키마를 덤프합니다. 나머지 모든 사람, 인간과 AI 에이전트는 자격 증명 없이 풀 스키마 인사이트를 얻습니다.

자격 증명은 DBA의 ă신을 벗나서는 안 됩니다. MCP 서버가 무엇인가 이살 하려면 DATABASE_URL 필요하다면, 그 것을 사요하는 모든 개밯자는 프로덕션 자격 증명이 필요합니다. 그것은 AI와 무관한 보안 문제입니다.

서버는 단순 전달이 아니고 분성여야 합니다. 원시 \d+ 출력률 그대2019 트에 볼여넣는 것보다 조금 나을 뿝니다. 가치는 데이타를 해석하는 데 있습니다: PostgreSQL 버저에서 마이그레이션이 안전한지, 누락된 FK 인덱스가 없는지, 열 참조가 실제 스키마와 일치하는지 확인하는 것.

설치

Homebrew:

Homebrew 6.0에서는 서드라티 탭을 신망한 후에 포를 로드할 수 있습니다:

brew trust --tap boringsql/boringsql
brew install boringsql/boringsql/dryrun

Homebrew 5.x 및 이전 버전에서는 brew trust 단계를 건너니다. 전체 탭을 신하지 않으려면 brew trust --formula boringsql/boringsql/dryun 포만 신하면 됩니다.

npm / npx:

Node.js가 이미 있다며 dryrun 실행르 버은 것 없이 사용할 수 있습니다:

npx @boringsql/dryrun --version

이 명령어는 플랏폼에 맞는 프리빌트 바이너리(darr-arm64, linux-x64, linux-arm64)를 가져와 캐에 저장하고 버저을 출려합니다. dryrun을 PATH에 영구히 등록하려면:

npm install -g @boringsql/dryrun
dryrun --version

이 npm 패키지 기반의 바이너리를 기타적으로 사용하여 동일한 기능을 제공합니다. lint 같은 명령어는 스냅샷을 필요로 합니다 — Quickstart 참조. 프리빌트 바이너리는 macOS (Apple Silicon + Intel), Linux (x64 + arm64), Windows x64를 포함합니다. 그 외 플랫폼 (Alpine/mu**, 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 설치한 후, 리포지터리의 준비된 스키마 스냅숏을 린트할 수 있습니다. 데이터베이스도 저도 없이:

git clone https://github.com/boringsql/dryrun.git
cd dryrun/examples/demo
dryrun lint

(npm이 Trend Homebrew로 설치했습니다 없지만 리포지터리를 클론하지 수도 있나요? 그럼 examples/demo가 없습니다 — Quickstart로 가서 dryrun을 자신의 스카마가리를 지정하세요. 아래 예시 출력은 lint 명령의 결과입니다.)

[ERROR] public.audit_log: table has no primary key
       fix: add a primary key (bigint GENERATED ALWAYS AS IDENTITY recommended)
[WARN ] public.audit_log: gap in range partitions: ends at '2024-07-01' but next starts at '2024-10-01'
       fix: inserts into the gap will fail unless a DEFAULT partition exists
[ERROR] public.task_comments: table has no primary key
       fix: add a primary key (bigint GENERATED ALWAYS AS IDENTITY recommended)
[WARN ] public.projects.created_at: timestamp column uses timestamp without time zone instead of timestamptz
       fix: use timestamptz for timestamp columns
[ERROR] public.tasks.project_id: FK 'tasks_project_id_fkey' on column(s) (project_id) has no covering index
       fix: add an index on FK columns to avoid sequential scans on DELETE/UPDATE
[WARN ] public.users.email: column 'email' uses character varying(255), prefer text
       fix: VARCHAR(n) adds a hidden CHECK constraint with no performance benefit
[WARN ] public.user_notifications: table is missing 'created_at' column
       fix: add: created_at timestamptz NOT NULL DEFAULT now()

26 finding(s): 6 error, 20 warning, 0 info (13 tables checked)

데이터베이스가 필요 없습니다. 전혀 오프라인 스냅숏으로만 동작합니다.

같은 데모를 MCP로도 해볼 수 있습니다. examples/demo에서 서버를 클라이어인트에 등록하세요:

claude mcp add dryrun -- npx -y @boringsql/dryrun mcp-serve

그런 다음 그 디렉터리에서 이렇고 물어보세요: "어면 테이블이 있고, どこ가 문재가 된가?"

MCP 서버

하나의 명렬으로 AI 어시스를 합니다. setup는 Claude Code, Cursor, Codex, Zed를 찾아내고, 에이전트의 MCP 설정을 만들며, AGENTS.md/CLAUDE.md에 지침을 추가하여 에이전트가 SQL을 작성기 전의 스키마를 확인하도록 합니다:

dryrun setup

에이전트를 직접 선택하거나 비대화형 에서 사요하려면 --agents를 전달하세요:

dryrun setup --agents=claude,cursor   # or: all

서버를 직접 등록하고 싶을 경우:

# for claude code
claude mcp add dryrun -- dryrun mcp-serve

# for codex
codex 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": {
      "command": "npx",
      "args": ["-y", "@boringsql/dryrun", "mcp-serve"]
    }
  }
}

서버는 현재 프로젝트의 .dryun/history.db에 가장 최신 스냅숏을 읽습니다. 데이터베이스 인퓨터 정보가 필요 없습니다; 어시스턴트는 오프라인 스냅숏에서 완전한 스키마 인포를 얻습니다.

스냅숏이 없이도 서버는 시작하며, 도구는 스킈마가 로드되지 않았다고 응합니다. dryrun init --db "$DATABASE_URL"로 스냅숏을 생성하거나 팀원이 시하에 올린 것(dryrun snapshot pull --path ./snapsht Quickstart 참조)을 가져온 후에 어시스턴트에서 reload_schema 도구를 호출하세요. 새 스킈마를 서버 재시작 없이 반영됩니다.

여러 데이터베이스가 있있다면, 데이터베이스별로 dryun mcp-serve 를 설동하고 각각 클라이언트 설정에서든 엔트 serieses in #7을 참조하세요. 하나의 MCP 프로세서에서 다중 데이터베이스를 자원하는 것이 이슈트랙에서 추저되고 있습니다: #7.

라이브 데이터베이스 설치, SS 전송 그리고 Claude Desktop 설정은 Tutorial을 참조하세요.

저 스타트

두 가지 방버이 있습니다. 자신의 환경에 맛는 것을 선택하세요.

옵션 A: 데이터베이스 접근 권한이 있는 case

PostgreSQL 인스톤가스(로컬, 개벟, 프로덕션)에 연결할 수 있이, 하나의 dryrun 명렬이면 충분합니다:

dryrun init --db "$DATABASE_URL"

이 명령은 dryun.tom (project)id와 기본 프롷일)과.dryun/데이타 디렉터리를 만들고, 데이터베이스를.dryun/history.db에 스냅숏하여 저장합니다. 스냅숏은 (project_i, database_i)키로 구분됩니다; 여러 데이터베이스가 있는 프로젝트(예:auth, biing)에 database_id를 포로필들 설정하세요. 전체 저는 [docs/dryun-tom.md` 참조.

옵션 B: 다른 사라미가 데이타베이스 접근 권한이 있는 데분

자격 증명이 있는 사라미가 한 변 스냅숏을 생출하고 공유 디렉터리(리포지터리 또는 양쪽이 접근 가능한 어는 곳)에 브션에서 업로드:

dryrun init --db "$DATABASE_URL"
dryrun snapshot push --to-path ./snapshots

그 사라미은 dryun.toml 두 개와 ./snapshots/을 함게 커밋합니다. 다른 모든 사람은 가В기 (pull) 합니다:

dryrun snapshot pull --from-path ./snapshots

snapshot pull은 스냅숏을 .dryun/history.db에 로드합니다. 그 사함은 는 데이터베이스 없이 다 됩니다.

dryun.toml을 커밋하는 느 선택이 아닙니다: 스냅숏은 (project_id, database_id)로 인젝트되며, dryun init은 라이브 데이터베이스 새 이름에서 dabase_id를 만들니다. --db 없이 dryun init을 실행한 팀원은 다른 database_id를 가지므로 snap pull은 소스에서 해당 키를 조회하지 못해 0 copied라고 출력합니다.

사된 스냅숏은 플랜 통계와 활동 통계를 함께 전달하므로, 사이즈나 버큠 정보가 필요한 라이브 데이터베이스는 있지만 일반 JSON 출력과는 다른 속합니다. 레지스터리 형식을 원할 우 dryun remote add 및 snapshot push --remote을 참조하세요. 사람이 읽을 수 있는 JSON을 원할 경우 dryun dump-schema가 여전히 사용 가능합니다. 이것은 공유용이지, 입력 방식은 아닙니다.

사요법

dryrun lint

모든 명령어는 .dryrun/history.db에서 오프라인으로 작동합니다. 각 프로젝트는 고유한 dryun.toml/.dryrun/을 가지고서 하니 어러 전역 상태가 없습니다. .dryrun/을.gitignore에 추가하고.

스냅숏은 .dryun/history.db에 (project_id, database_id) 키로 저장됩니다. 이것만 유일한 스카마 소스입니다: MCP 서버, lint, drift 모두 이 파일을 읽습니다. 이전 버저의 .dryun/schema.json은 무시됩니다.

다중: snap take를 레플리카 액티트 수집

snapshot take는 프라머리에서 실행되어 스키마와 플랙 통계를 출력합니다. 액티비티 카운터(idx_scan, n_dead_tup, 라스트 버큠)는 각 레플리카의 로컬 상태이므로 별로 획득합니다:

dryrun --profile primary  snapshot take
dryrun --profile replica1 snapshot activity --from "$REPLICA1_URL" --label replica1
dryrun --profile replica2 snapshot activity --from "$REPLICA2_URL" --label replica2

그 다음 MCP desclit_table (노드 별 geopn) 및 detect kind=anoamlies 도구가 노드당 idx_scan을 노출해 핵 nah불을 발견할 수 있습니다. [docs/multi-node-stats.md]를 참조하세요.

프로젝트당 여러 데이터베이스

dryun snapshot take은 스냅숏을 (project_id, database_id) 기로 저장합니다. 기본 실행은 동작합니다 — project_id는 폴더 이름이고, database_id는 current_database()가 반환하는 데이타베이스 이름 입니다:

dryrun init --db "$AUTH_DB"            # captures auth
dryrun snapshot take --db "$BILLING_DB" # captures billing into its own stream
dryrun snapshot list --db "$AUTH_DB"    # only auth snapshots

명확한 참조를 위해 그리고 list/diff를 URL을 다시입력하지 않고 사용할수 있기 끝에, dryun.toml에 프로파일을 저의하세요:

[project]
id = "myapp"

[profiles.auth]
db_url = "${AUTH_DATABASE_URL}"
database_id = "auth"

[profiles.billing]
db_url = "${BILLING_DATABASE_URL}"
database_id = "billing"

그리고 나서:

dryrun --profile billing snapshot list
dryrun --profile billing snapshot diff --latest

모든 프로파일 옵선은 docs/dryun-tom.md을 참고하세요.

모든 DB 관련 명좌 (init, probe, dump-schema, drift, stats appy, 모든 snapshot 하위 명좌)는 --profile을 습인하며, --db가 없을 때 레저된 프로필이 db_url을 사합니다. lint는 오프린 명령으로 .dryun/history.db을 읽고 --db가 명시적으로 지정될 때만 라이브 DB에 접속합니다.

참고: MCP 서버는 현재 단일 데이터베이스입니다. 기본 프로파일을 사용합니다. 또는 데이터베이스당 하나의 dryrun mcp-serve 프로세서를 실하는 옸션입니다. 하나의 MCP 프로세스에서 네이티브데이터베이스 지원은 이슈 #7에서 추적됩니다.

팀에서 스냅숏 공유하기

DryRun의 가치는 팀 환경에서 증가합니다. 여러 개발자는 POSIX 규준 디렉토리에서 스냅숏을 받을 수 있습니다.

스냅숏을 제출하려면으 following 코드를 실행합니다.

GXP22 개발자는 로컬 히스토리에서 스냅숏을 가져올 수 있습니다.

dryrun snapshot pull --from-path ./shared/snapshots --all

스냅샷은 고유 하디한(단일분 일치) {project}/{database}/{ts}-{hash}.json.zst 형식이며, 같은 스냅숏을 두 번 올려도 변하지 않습니다 (idempotent).

기본 배포는 전용 git 리포입니다. snapshots 리포를 만들고, *.json.zst binary를 .gitattributes에 추가해 Git가 번드들을 비교하지 않게 하세요.

lint, check_migration, drift 같은 오프라인 도구는 pull 바로 를작할 수 있습니다.

No server, no credentials. 이전과 같은 약속입니다.

OCI 레지스트리에 스냅샷 푸시

어떤 OCI 레지스트리든 스냅샷을 저장할 수 있습니다: GitHub Container Registry, Google Artifact Registry, Amazon ECR, Docker Hub, Harbor, 또는 자체 호스팅 OCI 레지스트리. 레지스트리가 인증, 보존, 접근 제어를 처리하므로 실행할 서버가 없습니다.

docker push를 할 때와 같은 방법으로 인증하고, 원격 저장소를 등록한 뒤 푸시합니다:

docker login ghcr.io
dryrun remote add ghcr --ref ghcr.io/myorg/dryrun --default
dryrun snapshot take --push

snapshot take --push는 한 단계로 캡처와 게시를 수행합니다. 소비자는 pull로 받아옵니다:

dryrun snapshot pull --remote ghcr

pull은 기본적으로 가장 최근의 테이크만 가져옵니다. 따라서 레지스트리에 기록이 얼마나 많이 쌓여 있어도 콜드 풀(새 CI, 빈 history.db)은 비용이 낮습니다. --full을 쓰면 전체 기록을 백필하고, --since 7d(2w, 24h, 또는 2026-01-01 같은 UTC 날짜)를 쓰면 특정 기간만 가져옵니다. push는 항상 로컬 전체 기록을 보냅니다. 콘텐츠 해시 기준으로 증분 전송되므로, 일정한 주기로 푸시하는 쪽은 실행할 때마다 새 관측치만 업로드합니다.

--ref는 레지스트리 베이스입니다. 각 데이터베이스는 그 아래에 <ref>/<project_id>/<database_id> 저장소를 갖게 되며, myapp의 auth 데이터베이스는 ghcr.io/myorg/dryrun/myapp/auth에 저장됩니다. 스냅샷은 콘텐츠 해시로 주소가 지정된 OCI artifact로 매핑되므로, 같은 스냅샷을 두 번 푸시해도 변화가 없고 공유 blob은 레지스트리에서 중복이 제거됩니다. Google Artifact Registry에서는 docker login 대신 gcloud auth configure-docker us-docker.pkg.dev를 실행하면 되며 나머지는 동일합니다.

인증(Authentication). 기본적으로 dryrun은 Docker 자격 증명(~/.docker/config.json 및 credential helpers)을 다시 사용합니다. 따라서 docker login이 가능한 레지스트리라면 추가 설정 없이 동작합니다. remote add에 있는 두 가지 오버라이드로 나머지 상황을 처리할 수 있습니다.

• --token-env VAR은 환경 변수에서 정적 bearer 토큰을 읽습니다. 단기 토큰을 발급하는 레지스트리를 위한 옵션입니다(예: -token-env GAR_TOKEN에 gcloud auth print-access-token을 supply).

• --auth gcp은 Google Application Default Credentials을 직접 사용합니다. gcloud auth login(또는 GOOGLE_APPLICATION_CREDENTIALS를 통해 지정한 서비스 계정 키) 후 configure-docker 없이도 Google Artifact Registry / Container Registry에서 동작하며, ADC 토큰은 자동으로 갱신됩니다.

프로필별 원격 저장소와 프로젝트 간 스트림 공유에 대한 내용은 docs/dryrun-tomod.md를 참조하세요.

더 보기

• 튜토리얼 — 오프라인 및 멀티노드 워크플로와 함께 전체 도구 참조

• 멀티노드 통계 — 클러스터 전체의 통계 수집, 집계 규칙, 복제 불균형 탐지

• 쿼리 통계 — pg_stat_statements 캡처, 형태 그룹화, diff 비교

• 구성 참조 — dryrun.toml 프로필, 구성, 원격 저장소, lint 규칙

• CLI 안정성 — 안정 명령과 실험 명령 비교

• 보안 개요 — CLI/MCP 분리와 마스킹

• boringSQL — 블로그 및 프로젝트 홈

• dryrun 프로젝트 페이지 — 개요 및 문서

• AI가 프로덕션 데이터베이스에 닿지 않게 하기 — 대부분의 Postgres MCP가 안전하지 않은 이유와 dryrun이 달리 접근하는 방법

• RegreSQL — SQL 회귀 테스트와 **dryrun**의 동반 도구

• Fixturize — 개발/테스트를 위한 프로덕션 데이터 집합 축소(subset) 및 마스킹

라이선스

BSD 2-Clause License