mcpField
T
text-to-sql

text-to-sql

github.com/oimiragieo数据与数据库44156 次安装17 周前更新
代码仓库

关于 text-to-sql

text-to-sql 是供 Agent 使用的提示驱动技能，依据自然语言请求和数据库结构生成 SQL。它强调参数化查询、结构校验，并提供评估方法。

主要功能

  1. 01根据自然语言生成 SQL
  2. 02结合数据库结构与关系
  3. 03生成优化后的参数化查询
  4. 04校验语法并测试样例数据
  5. 05支持 Promptfoo 评估

适用场景

  1. 01按注册时间筛选用户
  2. 02按产品汇总营收
  3. 03查询重复记录

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oimiragieo/agent-studio --skill text-to-sql

安装后在 Claude Code 中输入/text-to-sql确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

commands/
text-to-sql.md
hooks/
post-execute.cjs
pre-execute.cjs
references/
research-requirements.md
rules/
text-to-sql.md
schemas/
input.schema.json
output.schema.json
scripts/
main.cjs
templates/
implementation-template.md

详细介绍

模式：认知/提示词驱动 — 没有独立的实用脚本；通过 Agent 上下文使用。

Text-to-SQL 技能

身份

Text-to-SQL — 根据数据库架构上下文和查询模式，将自然语言查询转换为 SQL。

能力

  • 查询生成：将自然语言转换为 SQL
  • 架构感知：使用数据库架构生成准确的查询
  • 查询优化：生成经过优化的 SQL 查询
  • 参数化查询：创建安全的参数化查询

用法

基本 SQL 生成

适用场景：

  • 根据自然语言查询数据库
  • 数据分析请求
  • 报告查询
  • 临时数据库查询

调用方式：

"Generate SQL to find all users who signed up in the last month"
"Create a query to calculate total revenue by product"
"Write SQL to find duplicate records"

功能说明：

  • 分析自然语言查询
  • 参考数据库架构
  • 生成 SQL 查询
  • 验证查询语法
  • 返回参数化查询
高级功能

架构集成：

  • 加载数据库架构
  • 理解表之间的关系
  • 使用列类型和约束
  • 处理联接和聚合

查询优化：

  • 生成高效查询
  • 使用适当的索引
  • 优化联接
  • 尽量减少数据传输

安全性：

  • 参数化查询（防止 SQL 注入）
  • 验证查询语法
  • 使用示例数据进行测试
  • 错误处理

最佳实践

  1. 架构上下文：提供完整的数据库架构
  2. 查询验证：执行前验证 SQL
  3. 参数化：始终使用参数化查询
  4. 测试：使用示例数据测试查询
  5. 优化：检查查询性能

集成

与 Database Architect 集成

Text-to-SQL 使用 database-architect 提供的架构：

  • 表定义
  • 关系
  • 约束
  • 索引
与 Developer 集成

Text-to-SQL 为开发者生成查询：

  • 查询模板
  • 参数化查询
  • 查询优化
  • 错误处理

示例

示例 1：简单查询
User: "Find all users who signed up in the last month"

Text-to-SQL:
1. Analyzes query
2. References users table schema
3. Generates SQL:
   SELECT * FROM users
   WHERE created_at >= DATE_SUB(NOW(), INTERVAL 1 MONTH)
4. Returns parameterized query
示例 2：复杂查询
User: "Calculate total revenue by product for Q4"

Text-to-SQL:
1. Analyzes query
2. References orders and products tables
3. Generates SQL:
   SELECT p.name, SUM(o.total) as revenue
   FROM orders o
   JOIN products p ON o.product_id = p.id
   WHERE o.created_at >= '2024-10-01'
     AND o.created_at < '2025-01-01'
   GROUP BY p.id, p.name
4. Returns optimized query

评估

评估框架

根据 Claude Cookbooks 的模式，Text-to-SQL 评估包括：

语法验证：

  • SQL 语法正确性
  • 架构合规性
  • 查询结构验证

功能测试：

  • 在测试数据库上执行查询
  • 结果正确性
  • 性能验证

Promptfoo 集成：

  • 多种提示词变体（基础、少样本、思维链、RAG）
  • 温度扫描
  • 模型对比（Haiku 与 Sonnet）

评估配置： 为评估设置创建 promptfoo 配置文件（例如，text_to_sql_config.yaml）。

运行评估
# Run text-to-SQL evaluation (create config first)
npx promptfoo@latest eval -c text_to_sql_config.yaml
评估指标
  • 语法准确率：SQL 语法有效的查询所占百分比
  • 功能正确性：返回正确结果的查询所占百分比
  • 架构合规性：使用正确架构的查询所占百分比
  • 性能：查询执行时间和优化情况

Cookbooks 中的最佳实践

1. 提供架构上下文

始终包含完整的数据库架构：

  • 包含列类型的表定义
  • 关系和外键
  • 约束和索引
  • 示例数据模式
2. 使用少样本示例

提供类似查询的示例：

  • 简单查询
  • 包含联接的复杂查询
  • 聚合查询
  • 子查询模式
3. 对复杂查询使用思维链

对于复杂查询，使用思维链推理：

  • 将查询分解为多个步骤
  • 确定所需的表
  • 规划联接和聚合
  • 逐步生成 SQL
4. 使用 RAG 理解架构

使用 RAG 检索相关架构信息：

  • 查找与查询相关的表
  • 理解关系
  • 获取列详情
  • 检索查询模式

相关技能

  • classifier：对数据库查询进行分类
  • database-architect：用于架构设计
  • developer：生成查询代码

相关文档

铁律

  1. 始终在生成 SQL 前，根据提供的架构验证所有表名和列名
  2. 绝不对查询值使用字符串插值——必须无例外地使用参数化查询
  3. 始终为 SELECT 查询添加 LIMIT 子句（默认值为 100），除非用户明确要求覆盖此限制
  4. 绝不在未获得用户明确确认的情况下执行 DROP、DELETE、TRUNCATE 或 UPDATE 语句
  5. 始终用通俗易懂的语言解释生成的查询逻辑，让用户了解将要执行的内容

反模式

反模式失败原因正确做法
对值使用字符串插值存在 SQL 注入漏洞使用带有 ? 或 $N 占位符的参数化查询
SELECT 查询未添加 LIMIT 子句返回所有行，存在内存不足和超时风险默认使用 LIMIT 100，需要用户明确要求才能覆盖
未经确认执行破坏性 SQL会造成不可逆的数据丢失执行 DROP/DELETE/TRUNCATE 前必须获得用户确认
未验证架构引用了不存在的表或列根据提供的架构验证所有标识符
SELECT * 未指定列名结果不可预测且浪费性能始终明确指定列名

记忆协议（强制）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

  • 新模式 -> .claude/context/memory/learnings.md
  • 发现问题 -> .claude/context/memory/issues.md
  • 做出决策 -> .claude/context/memory/decisions.md

评论

支持 Markdown