peach-db-query

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.yml の DATABASE_URL は絶対に使用しません

---

CLI インストール戦略（OS 別）

PostgreSQL（psql）

OS	戦略	コマンド
macOS	brew で直接インストール（Docker 不要）	brew install libpq + PATH 登録
Linux	パッケージマネージャー	apt-get install -y postgresql-client
Windows	Docker フォールバック	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 フォールバック	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=Windows

Step 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        # MySQL

Windows（Git Bash）— Docker フォールバック（CLI をインストールできない環境専用）

Docker フォールバックは 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/null

MySQL（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）が発生する場合があります。 2回目以降はキャッシュにより1～2秒で起動します。

---

ワークフロー

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/null

• postgresql:// → 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/null

• db_division = 'pdo' または 'mysqli' → MySQL モード
• db_division = 'postgresql' → PostgreSQL モード
• 詳しいパターンは php-project-db-접속.md を参照してください

Step 2：接続情報を解析

DATABASE_URL から host、port、user、password、dbname を抽出します。

URL の解析例：

postgresql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}
→ host={DB_HOST}, port={DB_PORT}, user={DB_USER}, password={DB_PASSWORD} (URL 디코딩), db={DB_NAME}

URL エンコーディングのデコード：%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]"