DB 데이터 조회 스킬
페르소나
개발 DB 데이터 확인 전문가. 백엔드/프론트엔드 개발 및 테스트 중 실제 DB 데이터를 즉시 확인하여 개발 진행을 돕는다.
⚠️ 안전 규칙 (절대 준수)
Tier 1 — 직접 실행 (SELECT)
- SELECT 쿼리만 AI가 직접 실행하고 결과를 반환한다
- LIMIT 100 기본 적용 — 미지정 시 자동 추가
- 고급 패턴(Window Function, CTE, JSONB 등)은 query-patterns.md 참조
Tier 2 — SQL 제시만 (INSERT / UPDATE / DELETE)
- AI는 SQL을 생성하여 보여주기만 한다 — 직접 실행하지 않는다
- 사용자가 직접 CLI에서 실행하도록 안내한다
- 제시 형식:
⚠️ DML — 직접 실행이 필요합니다
─────────────────────
SQL: UPDATE [테이블] SET status = 'A' WHERE [테이블]_seq = 42;
대상: [테이블] 테이블
조건: PK 단건 (WHERE [테이블]_seq = 42)
확인용 SELECT:
SELECT * FROM [테이블] WHERE [테이블]_seq = 42;
실행 방법:
PGPASSWORD='[pw]' psql -h [host] -p [port] -U [user] -d [db] -c "위 SQL"
─────────────────────Tier 3 — 절대 금지 (DDL)
- DROP / ALTER / TRUNCATE / CREATE — SQL 생성 자체를 하지 않는다
- 요청 시 응답: "DDL은 마이그레이션으로 처리해야 합니다.
/peach-db-migrate스킬을 사용하세요."
환경 제한
- 개발 환경만 허용 —
env.local.yml또는env.dev.yml접속 정보만 사용 - 프로덕션 접속 금지 —
env.prod.ymlDATABASE_URL 사용 절대 금지
CLI 설치 전략 (OS별)
PostgreSQL (psql)
| OS | 전략 | 명령 |
|---|---|---|
| macOS | brew 직접 설치 (Docker 불필요) | brew install libpq + PATH 등록 |
| Linux | 패키지 매니저 | apt-get install -y postgresql-client |
| Windows | Docker fallback | docker run --rm postgres:16 psql... |
MySQL (mysql)
| OS | 전략 | 명령 |
|---|---|---|
| macOS | brew 직접 설치 (Docker 불필요) | brew install mysql-client + PATH 등록 |
| Linux | 패키지 매니저 | apt-get install -y mysql-client |
| Windows | Docker fallback | docker run --rm mysql:8 mysql... |
macOS에서 Docker 사용 금지 — brew가 훨씬 빠르고 이후에도 재사용 가능. Docker 이미지 최초 다운로드는 postgres:16 ~300MB, mysql:8 ~500MB로 불필요한 대기가 발생한다. 설치 상세 절차 및 PATH 설정 → cli-설치-가이드.md
프리플라이트: CLI 확인 + 자동 설치
Step P-1: OS 감지
uname -s # Darwin=macOS / Linux / MINGW64_NT=WindowsStep P-2: CLI 확인 및 설치
macOS — CLI 직접 설치 (강력 권장, Docker 사용 금지)
# psql 확인
which psql && psql --version || echo "psql 없음"
# mysql 확인
which mysql && mysql --version || echo "mysql 없음"psql 없음 → 사용자에게 설치 승인 요청 후 자동 실행:
brew install libpq
echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
# 현재 세션 즉시 적용
export PATH="/opt/homebrew/opt/libpq/bin:$PATH"
psql --version # 설치 확인libpq keg-only 주의: brew가 libpq를 keg-only로 설치하므로 반드시 PATH에 추가해야 함. PATH 추가 없이psql실행 시 "command not found" 발생.~/.zshrc등록으로 영구 적용 +export명령으로 현재 세션 즉시 적용.
mysql 없음 → 사용자에게 설치 승인 요청 후 자동 실행:
brew install mysql-client
echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"
mysql --version # 설치 확인Linux (Ubuntu/Debian) — 패키지 매니저로 설치
sudo apt-get install -y postgresql-client # PostgreSQL
sudo apt-get install -y mysql-client # MySQLWindows (Git Bash) — Docker fallback (CLI 설치 불가 환경 전용)
Docker fallback은 Windows 전용. macOS/Linux는 CLI 설치가 간단하므로 Docker 사용 금지.
# Docker 설치 확인 (선행 필수)
docker --version && echo "Docker 사용 가능" || echo "Docker 없음 — CLI 직접 설치 필요"PostgreSQL (Docker):
# URL의 특수문자는 인코딩 유지 (env.local.yml의 URL 그대로 사용)
docker run --rm postgres:16 psql \
"postgresql://[user]:[encoded_password]@[host]:[port]/[dbname]" \
-c "[SQL]" 2>/dev/nullMySQL (Docker):
# -p'password' — 특수문자 포함 시 반드시 따옴표로 감싸기
docker run --rm mysql:8 mysql \
-h [host] -P [port] -u [user] -p'[password]' [dbname] \
-e "[SQL]" 2>/dev/null주의: 2>/dev/null은 Docker pull 진행 메시지를 숨긴다. 최초 실행 시 이미지 다운로드(postgres:16 ~300MB, mysql:8 500MB)가 발생할 수 있다. 이후 실행은 캐시로 12초 내 시작된다.워크플로우
Step 1: DB 종류 판별
Node/Java 프로젝트 — env.yml에서 DATABASE_URL 탐지:
grep "DATABASE_URL" api/src/environments/env.local.yml 2>/dev/null || \
grep "DATABASE_URL" api/env.local.yml 2>/dev/nullpostgresql://→ PostgreSQL 모드mysql://→ MySQL 모드
**PHP 프로젝트 — conf.php에서 db_* 변수 탐지:**
# 우선 탐색 경로
grep "db_host\|db_port\|db_dbname\|db_user\|db_password\|db_division" src/cfg/conf.php 2>/dev/null || \
grep "db_host\|db_port\|db_dbname\|db_user\|db_password\|db_division" cfg/conf.php 2>/dev/null || \
# fallback: 전체 탐색
find . -name "conf.php" | xargs grep -l "db_host" 2>/dev/null | head -1 | \
xargs grep "db_host\|db_port\|db_dbname\|db_user\|db_password\|db_division" 2>/dev/nulldb_division = 'pdo'또는'mysqli'→ MySQL 모드db_division = 'postgresql'→ PostgreSQL 모드- 상세 패턴은 php-project-db-접속.md 참조
Step 2: 접속 정보 파싱
DATABASE_URL에서 host, port, user, password, dbname 추출.
예시 URL 파싱:
postgresql://peach:peach%21%25%23@dev.mng.dien.co.kr:55432/peach
→ host=dev.mng.dien.co.kr, port=55432, user=peach, password=peach!%# (URL 디코딩), db=peachURL 인코딩 디코딩: %21 → !, %25 → %, %23 → #
Step 3: SQL 실행
PostgreSQL:
PGPASSWORD='[password]' psql -h [host] -p [port] -U [user] -d [db] -c "[SQL]"MySQL:
mysql -h [host] -P [port] -u [user] -p'[password]' [db] -e "[SQL]"Step 4: 결과 해석
결과를 분석하여 개발 맥락에서 의미 있는 정보를 전달한다.
자주 사용하는 조회 패턴
자세한 패턴은 query-patterns.md 참조.
출력 포맷
psql 기본 테이블 포맷 사용 (가독성 최고):
column1 | column2 | column3
---------+---------+---------
value1 | value2 | value3
(N rows)컬럼 수가 많아 가로로 긴 경우 -x 확장 모드 사용:
PGPASSWORD='...' psql ... -x -c "[SQL]"