db-free

识别并规避基础数据库连接、事务、查询与数据完整性陷阱。Use when 需要数据库操作、SQL查询、数据存储管理时使用。不适用于数据库架构设计决策。适用于独立开发者、企业团队和自动化工作流场景。支持中文交互，无需复杂配置即开即用。输出结果可直接使用，减少二次加工成本。提供结构化输出和错误处理机制。支持多场景应用和灵活配置。

核心功能: 本技能提供中文交互、时使用、化工作流场景等能力。

数据库设计与运维（免费版）

概述

帮助识别和规避数据库使用中的基础陷阱，覆盖连接管理、事务、查询性能与数据完整性四大领域。

核心能力

基础连接管理

陷阱	表现	规避方案
连接池耗尽	应用静默挂起	设置最大连接数，监控连接池使用率
空闲连接占用内存	大量空闲连接耗尽内存	设置 idle_in_transaction_session_timeout，定期清理

升级提示：Serverless连接泄漏处理（RDS Proxy、PgBouncer）、连接阻塞Schema变更的 lock_timeout 策略为付费版专享功能。

输出: 返回基础连接管理的执行结果,包含操作状态和输出数据。

基础事务陷阱

陷阱	表现	规避方案
死锁	多事务以不同顺序锁定相同资源	统一加锁顺序，使用 SELECT FOR UPDATE 预锁定
丢失更新	读-改-写无锁导致并发覆盖	使用 SELECT FOR UPDATE 悲观锁或乐观锁（版本号）
隐式自动提交差异	不同数据库自动提交行为不一致	显式使用 BEGIN/COMMIT，不依赖隐式行为

升级提示：长事务MVCC锁膨胀、只读事务阻塞 VACUUM 清理等高级事务陷阱为付费版专享功能。

输出: 返回基础事务陷阱的执行结果,包含操作状态和输出数据。

基础查询优化

问题	原因	优化方案
N+1查询	ORM懒加载关联关系	预加载（eager load）或批量查询
外键缺索引	JOIN和级联删除全表扫描	为外键列创建索引
无界SELECT	SELECT * FROM huge_table 导致OOM	必须加 LIMIT，或使用游标分批读取

升级提示：大IN子句拆分优化、COUNT(*) 近似计数（pg_class.reltuples）为付费版专享功能。

基础数据完整性

陷阱	后果	保障方案
应用层唯一检查竞态	并发下产生重复数据	使用数据库唯一约束（UNIQUE）
时区混乱	跨时区显示错误	存储 UTC，显示时转换（TIMESTAMPTZ）
浮点数存金额	舍入误差导致账目不平	使用 DECIMAL 或整数分（INTEGER 存分）

升级提示：CHECK约束管理、外键缺失致孤儿行处理为付费版专享功能。Schema变更安全策略（带默认值加列、CREATE INDEX CONCURRENTLY、列重命名与删除顺序）、备份恢复优选实践（PITR、备份验证）、复制陷阱预防（脑裂、故障转移）、扩展性限制规划（1亿行分片、Autovacuum监控）为付费版专享功能。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（ Code / Cursor / Codex / CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。

使用流程

1. 场景识别：判断当前属于连接、事务、查询还是完整性问题
2. 陷阱匹配：在对应类别中查找匹配的陷阱描述与规避方案
3. 方案选择：根据数据库类型选择具体实现命令
4. 执行验证：按方案执行后验证结果

示例

示例1：避免丢失更新

sql

-- 错误: 读-改-写无锁，并发下丢失更新
SELECT balance FROM accounts WHERE id = 1;  -- 读到 balance=100
UPDATE accounts SET balance = 80 WHERE id = 1;  -- 丢失了另一事务的扣减

-- 正确: 使用 SELECT FOR UPDATE 悲观锁
BEGIN;
SELECT balance FROM accounts WHERE id = 1 FOR UPDATE;  -- 加行锁
UPDATE accounts SET balance = balance - 20 WHERE id = 1;
COMMIT;

示例2：金额存储

sql

-- 错误: 浮点数存金额（舍入误差）
CREATE TABLE bad_orders (total FLOAT);  -- 0.1+0.2 = 0.30000000000000004

-- 正确: DECIMAL 精确存储
CREATE TABLE good_orders (total DECIMAL(10,2));  -- 0.10+0.20 = 0.30

示例3：避免N+1查询

python

# 错误: N+1查询（100个订单 = 101次查询）
orders = Order.objects.all()
for order in orders:
    print(order.customer.name)  # 每次循环1次查询

# 正确: 预加载（2次查询）
orders = Order.objects.select_related('customer').all()
for order in orders:
    print(order.customer.name)  # 无额外查询

错误处理

错误场景	原因	处理方式
deadlock detected 死锁	多事务以不同顺序锁定相同资源	统一加锁顺序，捕获死锁异常后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令事务
too many connections 连接耗尽	连接池配置过小	设置 max_connections 上限，监控连接数
out of memory 查询OOM	SELECT * 无界查询加载全表	添加 LIMIT，或使用游标分批读取
duplicate key value 唯一约束冲突	应用层检查与插入之间存在竞态	使用数据库唯一约束（UNIQUE）替代应用层检查
integer out of range 整数溢出	INT 最大值 2147483647 不足	改用 BIGINT（最大 9223372036854775807）

常见问题

Q1: 为什么浮点数不能存金额？

A: IEEE 754浮点数无法精确表示十进制小数。0.1 + 0.2 在浮点数中等于 0.30000000000000004。必须使用 DECIMAL(10,2) 或整数分存储。

Q2: 如何避免N+1查询？

A: 使用ORM的预加载功能（如Django的 select_related / prefetch_related），将关联数据通过JOIN一次性查出，避免循环中逐条查询。

Q3: 连接池应该设置多大？

A: 建议从 pool_size = 10 开始，根据监控调整。Serverless环境的高级连接池方案（RDS Proxy、PgBouncer）为付费版专享功能。

Q4: 如何安全地修改表结构？

A: Schema变更安全策略（带默认值加列的三步法、CREATE INDEX CONCURRENTLY、列重命名与删除顺序）为付费版专享功能。免费版建议在低峰期执行Schema变更，并做好备份。

Q5: 单表超过1亿行怎么办？

A: 扩展性限制规划（分片策略、Autovacuum监控、统计信息更新）为付费版专享功能。免费版建议先尝试按时间或哈希分区表。

已知限制

• 免费版不包含Schema变更安全策略
• 免费版不包含备份与恢复优选实践
• 免费版不包含复制陷阱预防（脑裂、故障转移重连）
• 免费版不包含扩展性限制规划（1亿行分片、IOPS瓶颈监控）
• 免费版不包含高级事务陷阱（MVCC锁膨胀、只读事务阻塞清理）
• 免费版不包含大IN子句与COUNT(*)优化
• 升级至付费版可解锁全部8大类陷阱与规避方案

安全注意事项

风险类型	防范措施
API密钥泄露	通过环境变量配置，禁止硬编码到代码或配置文件中
命令执行风险	仅执行白名单命令，避免拼接用户输入到命令行参数中
网络通信安全	使用HTTPS协议，验证SSL证书有效性
敏感数据暴露	输出结果中不包含密钥、令牌等敏感信息

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

效率量化分析

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

差异化对比

对比维度	本技能	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	核心功能	通用场景	通用场景

核心功能

• 自动化执行: 基于指令驱动的自动化流程
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据