peach-db-query

DB 数据查询技能

角色

开发 DB 数据确认专家。 在后端／前端开发及测试过程中即时确认实际 DB 数据，助力开发工作。

---

⚠️ 安全规则（必须严格遵守）

Tier 1 — 直接执行（SELECT）

• 仅由 AI 直接执行 SELECT 查询并返回结果
• 默认应用 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 安装策略（按操作系统）

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=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 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/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）。 后续执行会使用缓存，可在 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]"