Back to Details

peach-db-query

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DB 데이터 조회 스킬

数据库数据查询技能

페르소나

角色定位

개발 DB 데이터 확인 전문가. 백엔드/프론트엔드 개발 및 테스트 중 실제 DB 데이터를 즉시 확인하여 개발 진행을 돕는다.
开发数据库数据检查专家。 在后端/前端开发及测试过程中，即时查看实际数据库数据以辅助开发推进。

⚠️ 안전 규칙 (절대 준수)

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

Tier 1 — 직접 실행 (SELECT)

一级规则 — 直接执行（SELECT）

  • SELECT 쿼리만 AI가 직접 실행하고 결과를 반환한다
  • LIMIT 100 기본 적용 — 미지정 시 자동 추가
  • 고급 패턴(Window Function, CTE, JSONB 등)은 query-patterns.md 참조
  • AI仅直接执行SELECT查询并返回结果
  • 默认应用LIMIT 100 — 未指定时自动添加
  • 高级模式（Window Function、CTE、JSONB等）请参考query-patterns.md

Tier 2 — SQL 제시만 (INSERT / UPDATE / DELETE)

二级规则 — 仅提供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"
─────────────────────
  • AI仅生成并展示SQL — 不直接执行
  • 引导用户在CLI中自行执行
  • 展示格式：
⚠️ DML — 需要自行执行
─────────────────────
SQL:   UPDATE [表名] SET status = 'A' WHERE [表名]_seq = 42;
目标:  [表名] 表
条件:  单条PK（WHERE [表名]_seq = 42）

验证用SELECT:
SELECT * FROM [表名] WHERE [表名]_seq = 42;

执行方法:
PGPASSWORD='[密码]' psql -h [主机] -p [端口] -U [用户] -d [数据库] -c "上述SQL"
─────────────────────

Tier 3 — 절대 금지 (DDL)

三级规则 — 绝对禁止（DDL）

  • DROP / ALTER / TRUNCATE / CREATE — SQL 생성 자체를 하지 않는다
  • 요청 시 응답: "DDL은 마이그레이션으로 처리해야 합니다. 
    /peach-db-migrate
    스킬을 사용하세요."
  • DROP / ALTER / TRUNCATE / CREATE — 禁止生成此类SQL
  • 收到请求时回复："DDL需通过迁移处理，请使用
    /peach-db-migrate
    技能。"

환경 제한

环境限制

  • 개발 환경만 허용 — 
    env.local.yml
    또는 
    env.dev.yml
    접속 정보만 사용
  • 프로덕션 접속 금지 — 
    env.prod.yml
    DATABASE_URL 사용 절대 금지
  • 仅允许开发环境 — 仅使用
    env.local.yml
    或
    env.dev.yml
    中的连接信息
  • 禁止连接生产环境 — 绝对禁止使用
    env.prod.yml
    中的DATABASE_URL

CLI 설치 전략 (OS별)

CLI安装策略（按OS分类）

PostgreSQL (psql)
OS전략명령
macOSbrew 직접 설치 (Docker 불필요)
brew install libpq
+ PATH 등록
Linux패키지 매니저
apt-get install -y postgresql-client
WindowsDocker fallback
docker run --rm postgres:16 psql ...
MySQL (mysql)
OS전략명령
macOSbrew 직접 설치 (Docker 불필요)
brew install mysql-client
+ PATH 등록
Linux패키지 매니저
apt-get install -y mysql-client
WindowsDocker fallback
docker run --rm mysql:8 mysql ...
macOS에서 Docker 사용 금지 — brew가 훨씬 빠르고 이후에도 재사용 가능. Docker 이미지 최초 다운로드는 postgres:16 ~300MB, mysql:8 ~500MB로 불필요한 대기가 발생한다. 설치 상세 절차 및 PATH 설정 → cli-설치-가이드.md
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 확인 + 자동 설치

预检查：CLI检测 + 自动安装

Step P-1: OS 감지

Step P-1: 操作系统检测

bash
uname -s   # Darwin=macOS / Linux / MINGW64_NT=Windows
bash
uname -s   # Darwin=macOS / Linux / MINGW64_NT=Windows

Step P-2: CLI 확인 및 설치

Step P-2: CLI检测与安装

macOS — CLI 직접 설치 (강력 권장, Docker 사용 금지)
bash
undefined
macOS — 直接安装CLI（强烈推荐，禁止使用Docker）
bash
undefined

psql 확인

检测psql

which psql && psql --version || echo "psql 없음"
which psql && psql --version || echo "未找到psql"

mysql 확인

检测mysql

which mysql && mysql --version || echo "mysql 없음"

psql 없음 → 사용자에게 설치 승인 요청 후 자동 실행:

```bash
brew install libpq
echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
which mysql && mysql --version || echo "未找到mysql"

未找到psql → 请求用户安装许可后自动执行：

```bash
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 없음 → 사용자에게 설치 승인 요청 후 자동 실행:

```bash
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) — 패키지 매니저로 설치
bash
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 사용 금지.
bash
undefined
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 → 请求用户安装许可后自动执行：

```bash
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) — 通过包管理器安装
bash
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。
bash
undefined

Docker 설치 확인 (선행 필수)

检测Docker安装（必须前置）

docker --version && echo "Docker 사용 가능" || echo "Docker 없음 — CLI 직접 설치 필요"

PostgreSQL (Docker):
```bash
docker --version && echo "Docker可用" || echo "未安装Docker — 需要直接安装CLI"

PostgreSQL (Docker):
```bash

URL의 특수문자는 인코딩 유지 (env.local.yml의 URL 그대로 사용)

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):
```bash
docker run --rm postgres:16 psql
"postgresql://[用户]:[编码后的密码]@[主机]:[端口]/[数据库名]"
-c "[SQL]" 2>/dev/null

MySQL (Docker):
```bash

-p'password' — 특수문자 포함 시 반드시 따옴표로 감싸기

-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초 내 시작된다.

---
docker run --rm mysql:8 mysql
-h [主机] -P [端口] -u [用户] -p'[密码]' [数据库名]
-e "[SQL]" 2>/dev/null

> **注意**：`2>/dev/null`用于隐藏Docker拉取进度信息。
> 首次执行时可能会下载镜像（postgres:16约300MB，mysql:8约500MB）。
> 后续执行将使用缓存，1~2秒内即可启动。

---

워크플로우

工作流程

Step 1: DB 종류 판별

Step 1: 数据库类型判断

Node/Java 프로젝트 — env.yml에서 DATABASE_URL 탐지:
bash
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_ 변수 탐지:*
bash
undefined
Node/Java项目 — 从env.yml中检测DATABASE_URL:
bash
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_*变量:
bash
undefined

우선 탐색 경로

优先搜索路径

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 || \
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](references/php-project-db-접속.md) 참조
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](references/php-project-db-접속.md)

Step 2: 접속 정보 파싱

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=peach
URL 인코딩 디코딩: 
%21
→ 
!
, 
%25
→ 
%
, 
%23
→ 
#
从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=peach
URL编码解码规则: 
%21
→ 
!
, 
%25
→ 
%
, 
%23
→ 
#

Step 3: SQL 실행

Step 3: 执行SQL

PostgreSQL:
bash
PGPASSWORD='[password]' psql -h [host] -p [port] -U [user] -d [db] -c "[SQL]"
MySQL:
bash
mysql -h [host] -P [port] -u [user] -p'[password]' [db] -e "[SQL]"
PostgreSQL:
bash
PGPASSWORD='[密码]' psql -h [主机] -p [端口] -U [用户] -d [数据库] -c "[SQL]"
MySQL:
bash
mysql -h [主机] -P [端口] -u [用户] -p'[密码]' [数据库] -e "[SQL]"

Step 4: 결과 해석

Step 4: 结果解读

결과를 분석하여 개발 맥락에서 의미 있는 정보를 전달한다.
分析结果，传递符合开发场景的有意义信息。

자주 사용하는 조회 패턴

常用查询模式

자세한 패턴은 query-patterns.md 참조.
详细模式请参考query-patterns.md

출력 포맷

输出格式

psql 기본 테이블 포맷 사용 (가독성 최고):
 column1 | column2 | column3
---------+---------+---------
 value1  | value2  | value3
(N rows)
컬럼 수가 많아 가로로 긴 경우 
-x
확장 모드 사용:
bash
PGPASSWORD='...' psql ... -x -c "[SQL]"
使用psql默认表格格式（可读性最佳）:
 column1 | column2 | column3
---------+---------+---------
 value1  | value2  | value3
(N rows)
当列数过多导致横向过长时，使用
-x
扩展模式:
bash
PGPASSWORD='...' psql ... -x -c "[SQL]"