Back to Details

database

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Database Skill — Entrypoint & Router

数据库技能 — 入口与路由

🎯 Mục đích

🎯 目的

Skill này hướng dẫn CLI Agent thao tác đúng với SQLite, MySQL, PostgreSQL. Entrypoint duy nhất — không load toàn bộ thư mục vào context. Chỉ load file theo trigger rules bên dưới.
本技能指导CLI Agent正确操作SQLite、MySQL、PostgreSQL。仅提供单一入口——无需将整个目录加载到上下文。仅根据下方触发规则加载对应文件。

⛔ Quy tắc nạp file (bắt buộc)

⛔ 文件加载规则（强制要求）

Chỉ 
view
/đọc file trong 
dialects/
hoặc file 
00-
–
40-
khi đã xác định rõ trigger tương ứng ở bảng dưới. Không liệt kê thư mục rồi đọc lần lượt "cho chắc". Nếu task không khớp trigger nào, chỉ dùng 6 Golden Rules + Compatibility Matrix ngay trong file này — không mở thêm file.
仅在确定匹配下表中的对应触发器后，才
view
/读取
dialects/
目录下的文件或
00-
–
40-
前缀的文件。禁止先列出目录再逐一读取以“确保覆盖”。若任务不匹配任何触发器，仅使用本文档中的6条黄金规则和兼容性矩阵——不得打开其他文件。

⚠️ 6 Golden Rules (luôn áp dụng, không cần load thêm file)

⚠️ 6条黄金规则（始终适用，无需加载额外文件）

  1. Never guess schema — nếu chưa inspect hoặc không chắc chắn schema/kiểu dữ liệu thực tế, cấm viết DDL/DML. Bắt buộc chạy 
    PRAGMA table_info
    / 
    SHOW CREATE TABLE
    / 
    \d+
    trước, không suy đoán từ tên cột hay convention "thường thấy"
  2. Environment isolation — 
    NODE_ENV=production
    cần 
    --force
    + human confirm + backup
  3. Parameterized only — cấm string concatenation trong SQL
  4. No FLOAT for money — INTEGER cents / DECIMAL / NUMERIC
  5. Idempotence required — migration & seed chạy lại được nhiều lần không lỗi
  6. Always have down path — mọi migration phải có rollback script (hoặc lý do rõ ràng tại sao không rollback được)
  1. 绝不猜测数据库模式 — 若尚未检查或不确定实际的模式/数据类型，禁止编写DDL/DML语句。必须先执行
    PRAGMA table_info
    / 
    SHOW CREATE TABLE
    / 
    \d+
    ，不得根据列名或常见惯例猜测。
  2. 环境隔离 — 
    NODE_ENV=production
    环境下需要
    --force
    参数 + 人工确认 + 备份。
  3. 仅使用参数化查询 — 禁止在SQL中使用字符串拼接。
  4. 金钱数据禁止使用FLOAT — 需使用INTEGER（分）/ DECIMAL / NUMERIC类型。
  5. 必须具备幂等性 — 迁移与数据生成脚本可多次执行而不报错。
  6. 始终保留回滚路径 — 所有迁移必须包含回滚脚本（或明确说明无法回滚的原因）。

🚦 Trigger Rules (khi nào load file nào)

🚦 触发规则（何时加载对应文件）

Khi agent nhận yêu cầuLoad các file
Tạo bảng / thiết kế schema
00-safety.md
+ 
10-schema-design.md
+ 
dialects/{db}.md
ALTER / DROP / migration
00-safety.md
+ 
20-migration.md
+ 
dialects/{db}.md
Transaction / logic tiền / giao dịch
11-transactions.md
+ 
12-concurrency.md
Query chậm / tối ưu hiệu năng
21-indexing-query.md
+ 
dialects/{db}.md
Code review (bất kỳ)
30-review.md
Seed / test dữ liệu
31-testing-seed.md
Cần pattern phổ biến
40-patterns.md
Mọi DDL nguy hiểm
00-safety.md
bắt buộc trước khi load bất kỳ file nào khác
当Agent收到请求时加载文件
创建表 / 设计数据库模式
00-safety.md
+ 
10-schema-design.md
+ 
dialects/{db}.md
ALTER / DROP / 迁移
00-safety.md
+ 
20-migration.md
+ 
dialects/{db}.md
事务 / 付款逻辑 / 交易
11-transactions.md
+ 
12-concurrency.md
查询缓慢 / 性能优化
21-indexing-query.md
+ 
dialects/{db}.md
代码审核（任意类型）
30-review.md
生成测试数据 / 测试数据
31-testing-seed.md
需要常见模式
40-patterns.md
所有危险DDL操作必须先加载
00-safety.md
，再加载其他任何文件

🔷 Compatibility Matrix (tra cứu nhanh, không cần load dialect)

🔷 兼容性矩阵（快速查询，无需加载方言文件）

FeatureSQLiteMySQL 8+PostgreSQL 16+
RETURNING✔✔ (8.0.14+)✔
JSONTEXT (qua JSON functions)JSONJSONB (luôn dùng)
Partial Index✔✘✔
Concurrent Index BUILD✘✔ (chậm)
CREATE INDEX CONCURRENTLY
DDL in TransactionKhông (implicit commit)Không (implicit commit)✔ (rollback được)
SKIP LOCKED
✘✔✔
Native UUIDTEXT
BINARY(16)
/ 
CHAR(36)
UUID
Generated Identity
AUTOINCREMENT
AUTO_INCREMENT
GENERATED ... AS IDENTITY
FK constraintCần 
PRAGMA foreign_keys=ON
Tự độngTự động
ALTER COLUMN
❌ (phải recreate table)✔ (hạn chế)✔
Materialized View✘✘✔
Advisory Lock✘✔ (
GET_LOCK()
)		✔ (
pg_advisory_lock
)
特性SQLiteMySQL 8+PostgreSQL 16+
RETURNING✔✔ (8.0.14+)✔
JSONTEXT（通过JSON函数）JSONJSONB（始终使用）
部分索引✔✘✔
并发索引构建✘✔（较慢）
CREATE INDEX CONCURRENTLY
事务内执行DDL不支持（隐式提交）不支持（隐式提交）✔（支持回滚）
SKIP LOCKED
✘✔✔
原生UUIDTEXT
BINARY(16)
/ 
CHAR(36)
UUID
生成式自增
AUTOINCREMENT
AUTO_INCREMENT
GENERATED ... AS IDENTITY
外键约束需要
PRAGMA foreign_keys=ON
自动生效自动生效
ALTER COLUMN
❌（需重建表）✔（有限制）✔
物化视图✘✘✔
咨询锁✘✔ (
GET_LOCK()
)		✔ (
pg_advisory_lock
)

🔐 Agent Capability & Permission Boundary

🔐 Agent能力与权限边界

Thao tácDev / StagingProductionGhi chú
Inspect / EXPLAIN / SELECT✅ Auto✅ AutoProduction bắt buộc 
LIMIT ≤ 100
Generate migration / DDL✅ Output file✅ Output fileChỉ ghi file, không tự execute
Execute migration (
up
)		⚠️ Cần 
--dry-run
trước		🛑 Cần human confirm + 
--force
+ backup
Execute 
down
/ rollback		⚠️ Cần 
--dry-run
trước		🛑 Cần human confirm
DROP
/ 
TRUNCATE
/ xoá hàng loạt không 
WHERE
⚠️ Cần 
--dry-run
+ xác nhận		⛔ NEVER tự độngChỉ khi human gõ rõ lệnh xác nhận, không suy diễn từ "gấp"/"nhanh lên"
Seed / fixture data✅⛔ NEVERXem 
31-testing-seed.md
操作开发/ Staging环境生产环境备注
检查 / EXPLAIN / SELECT✅ 自动执行✅ 自动执行生产环境必须满足
LIMIT ≤ 100
生成迁移脚本 / DDL✅ 输出文件✅ 输出文件仅生成文件，不自动执行
执行迁移（
up
）		⚠️ 需先执行
--dry-run
🛑 需人工确认 + 
--force
+ 备份
执行
down
/ 回滚		⚠️ 需先执行
--dry-run
🛑 需人工确认
DROP
/ 
TRUNCATE
/ 无
WHERE
条件批量删除		⚠️ 需
--dry-run
+ 确认		⛔ 绝不自动执行仅当人工明确输入确认指令时执行，不得根据“加急”/“快点”等表述推断执行
生成测试数据 / 测试夹具✅⛔ 绝不执行参见
31-testing-seed.md

🔢 Version check bắt buộc

🔢 必须检查版本

Trước khi dùng bất kỳ tính năng nào trong Compatibility Matrix bên dưới (ví dụ RETURNING, JSONB, CONCURRENTLY), chạy 
SELECT VERSION()
/ 
SELECT version()
/ 
PRAGMA user_version
để xác nhận version thật của server đang kết nối. Không giả định "chắc là bản mới" dựa vào tên project hay ngày tạo file.
在使用兼容性矩阵中的任何特性（例如RETURNING、JSONB、CONCURRENTLY）之前，执行
SELECT VERSION()
/ 
SELECT version()
/ 
PRAGMA user_version
以确认当前连接的服务器实际版本。不得根据项目名称或文件创建日期假设“肯定是新版本”。

📂 Cấu trúc thư mục

📂 目录结构

database-skill/
├── SKILL.md                 # <-- file này
├── 00-safety.md             # Env guard, destructive ops, 3 modes
├── 10-schema-design.md      # Schema, constraints, Data Types Matrix
├── 11-transactions.md       # Transaction, isolation, ORM boundary
├── 12-concurrency.md        # Locking, Deadlock Retry Loop
├── 20-migration.md          # Expand-Contract, down.sql, dry-run
├── 21-indexing-query.md     # EXPLAIN, cost-based triggers, N+1
├── 30-review.md             # Checklist review SQL + ORM
├── 31-testing-seed.md       # Seed idempotent + rollback test
├── 40-patterns.md           # Decision trees + common patterns
└── dialects/
    ├── sqlite.md
    ├── mysql.md
    └── postgres.md
database-skill/
├── SKILL.md                 # <-- 本文件
├── 00-safety.md             # 环境防护、破坏性操作、三种模式
├── 10-schema-design.md      # 模式、约束、数据类型矩阵
├── 11-transactions.md       # 事务、隔离级别、ORM边界
├── 12-concurrency.md        # 锁、死锁重试循环
├── 20-migration.md          # 扩展-收缩模式、down.sql、预演运行
├── 21-indexing-query.md     # EXPLAIN、基于成本的触发器、N+1问题
├── 30-review.md             # SQL + ORM审核 Checklist
├── 31-testing-seed.md       # 幂等性测试数据生成 + 回滚测试
├── 40-patterns.md           # 决策树 + 常见模式
└── dialects/
    ├── sqlite.md
    ├── mysql.md
    └── postgres.md

Quy trình khi nhận task

任务处理流程

  1. Xác định DB đang dùng (SQLite / MySQL / PostgreSQL)
  2. Kiểm tra môi trường (
    NODE_ENV
    , 
    DATABASE_URL
    )
  3. Xác định task type → Trigger Rules → load file tương ứng
  4. Tuyệt đối không load toàn bộ thư mục vào context
  1. 确定使用的数据库（SQLite / MySQL / PostgreSQL）
  2. 检查环境（
    NODE_ENV
    、
    DATABASE_URL
    ）
  3. 确定任务类型 → 匹配触发规则 → 加载对应文件
  4. 绝对禁止将整个目录加载到上下文