---
name: db-query
version: "1.0.0"
category: database
description: "数据库查询与操作 / SQL 执行、语法校验、安全审查 — 集成方言检查和危险操作拦截"
triggers:
  zh: ["查询", "SQL", "建表", "DDL", "DML", "select", "insert", "update", "数据库", "表", "字段"]
  en: ["query", "SQL", "DDL", "DML", "select", "insert", "update", "database", "table", "schema"]
license: MIT
compatibility: opespro-opencode >= 2.3.0
dependencies:
  - mysql2 (npm)
  - scripts/db-validate.js
metadata:
  author: "OpesPro Team"
  created: "2026-06-29"
  status: "stable"
  agent_profile: db-master
---

# DB Query / 数据库查询

## Changelog

| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-06-29 | 1.0.0 | 初始版本 |

---

## Core Concept

**Input:** SQL 语句 / 表名 / 查询需求 | **Output:** 校验后的 SQL + 执行结果 | **不负责:** 数据迁移方案、Schema 设计

---

## Iron Law

1. **铁律 1**: 所有 SQL 必须先通过 `scripts/db-validate.js` 安全校验，绝不直接执行
2. **铁律 2**: 危险操作（DROP/TRUNCATE/DELETE without WHERE）必须用户确认
3. **铁律 3**: 执行的 SQL 必须记录到 `.opop/tasks/tracking/` 日志
4. **铁律 4**: 数据库密码/凭证使用 `.opop/credentials/` 存储，绝不硬编码

---

## Workflow

```
用户请求 → 解析 SQL/表名
    ├→ 1. 方言检查: scripts/db-validate.js --dialect=mysql
    ├→ 2. 安全校验: scripts/db-validate.js --safety
    ├→ 3. 危险操作确认 (if DROP/DELETE)
    └→ 4. 执行 SQL → 返回结果
```

## Scripts

| Script | 用途 |
|--------|------|
| `scripts/db-validate.js` | SQL 安全校验 + 方言检查 |
| `scripts/db-exec.js` | SQL 执行（参数化查询） |

## Usage

```bash
# 验证 SQL 安全性
node scripts/db-validate.js --sql "SELECT * FROM users" --dialect=mysql

# 执行查询（需要连接配置）
node scripts/db-exec.js --sql "SELECT * FROM users WHERE id=?" --params "[1]"

# 方言转换
node scripts/db-validate.js --sql "LIMIT 10" --dialect=mysql --check-dialect
```

## Red Flags

| Flag | 条件 | 动作 |
|------|------|------|
| 🔴 | SQL 包含 DROP/TRUNCATE | 中断 + 请求确认 |
| 🔴 | DELETE 无 WHERE 子句 | 中断 + 请求确认 |
| 🟡 | 语法错误 | 继续 + 修正建议 |
| 🟡 | 方言不匹配 | 继续 + 自动转换 |