文本转SQL技能：自然语言生成SQL查询，支持模式感知与查询优化

text-to-sql by oimiragieo/agent-studio

96 周安装量

23 GitHub Stars

GitHub

安装命令

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

AI/机器学习数据库自然语言处理

🇨🇳中文介绍

模式：认知/提示驱动 — 无独立实用脚本；需通过智能体上下文使用。

文本转 SQL 技能

身份

文本转 SQL - 利用数据库模式上下文和查询模式，将自然语言查询转换为 SQL。

能力

查询生成 : 将自然语言转换为 SQL
模式感知 : 使用数据库模式以生成准确的查询
查询优化 : 生成优化的 SQL 查询
参数化查询 : 创建安全的参数化查询

使用方法

基础 SQL 生成

使用时机 :

从自然语言生成数据库查询
数据分析请求
报表查询
临时数据库查询

如何调用 :

"生成 SQL 以查找过去一个月内注册的所有用户"
"创建一个查询来计算各产品的总收入"
"编写 SQL 以查找重复记录"

功能说明 :

分析自然语言查询
参考数据库模式
生成 SQL 查询
验证查询语法
返回参数化查询

高级功能

模式集成 :

加载数据库模式
理解表关系

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

与数据库架构师集成

文本转 SQL 使用来自 database-architect 的模式：

表定义
关系
约束
索引

文本转 SQL 为开发者生成查询：

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

示例 1：简单查询

用户："查找过去一个月内注册的所有用户"

文本转 SQL：
1. 分析查询
2. 参考 users 表模式
3. 生成 SQL：
   SELECT * FROM users
   WHERE created_at >= DATE_SUB(NOW(), INTERVAL 1 MONTH)
4. 返回参数化查询

示例 2：复杂查询

用户："计算第四季度各产品的总收入"

文本转 SQL：
1. 分析查询
2. 参考 orders 和 products 表
3. 生成 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. 返回优化后的查询

基于 Claude Cookbooks 模式，文本转 SQL 评估包括：

SQL 语法正确性
模式合规性
查询结构验证

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

Promptfoo 集成 :

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

评估配置 : 为您的评估设置创建一个 promptfoo 配置文件（例如，text_to_sql_config.yaml）。

# 运行文本转 SQL 评估（需先创建配置）
npx promptfoo@latest eval -c text_to_sql_config.yaml

语法准确率 : 具有有效 SQL 语法的查询百分比
功能正确性 : 返回正确结果的查询百分比
模式合规性 : 使用正确模式的查询百分比
性能 : 查询执行时间和优化情况

Cookbooks 最佳实践

1. 提供模式上下文

始终包含完整的数据库模式：

包含列类型的表定义
关系和主外键
约束和索引
样本数据模式

2. 使用少样本示例

提供类似查询的示例：

简单查询
带连接的复杂查询
聚合查询
子查询模式

3. 对复杂查询使用思维链

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

将查询分解为步骤
识别所需的表
规划连接和聚合
逐步生成 SQL

4. 使用 RAG 理解模式

使用 RAG 检索相关的模式信息：

查找查询相关的表
理解关系
获取列详细信息
检索查询模式

classifier : 对数据库查询进行分类
database-architect : 用于模式设计
developer : 生成查询代码

始终在生成 SQL 前，根据提供的模式验证所有表和列名
绝不对查询值使用字符串插值 — 参数化查询是强制要求，绝无例外
始终对 SELECT 查询应用 LIMIT 子句（默认 100），除非用户明确覆盖
绝不在没有明确用户确认的情况下执行 DROP、DELETE、TRUNCATE 或 UPDATE 语句
始终用通俗易懂的语言解释生成的查询逻辑，以便用户理解将要执行的内容

反模式	失败原因	正确方法
对值使用字符串插值	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

🇺🇸English

Mode: Cognitive/Prompt-Driven — No standalone utility script; use via agent context.

Text-to-SQL Skill

Identity

Text-to-SQL - Converts natural language queries to SQL using database schema context and query patterns.

Capabilities

Query Generation : Convert natural language to SQL
Schema Awareness : Uses database schema for accurate queries
Query Optimization : Generates optimized SQL queries
Parameterized Queries : Creates safe, parameterized queries

Usage

Basic SQL Generation

When to Use :

Database queries from natural language
Data analysis requests
Reporting queries
Ad-hoc database queries

How to Invoke :

"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"

What It Does :

Analyzes natural language query
References database schema
Generates SQL query
Validates query syntax
Returns parameterized query

Advanced Features

Schema Integration :

Loads database schema
Understands table relationships
Uses column types and constraints
Handles joins and aggregations

Query Optimization :

Generates efficient queries
Uses appropriate indexes
Optimizes joins
Minimizes data transfer

Safety :

Parameterized queries (prevents SQL injection)
Validates query syntax
Tests on sample data
Error handling

Best Practices

Schema Context : Provide complete database schema
Query Validation : Validate SQL before execution
Parameterization : Always use parameterized queries
Testing : Test queries on sample data
Optimization : Review query performance

Integration

With Database Architect

Text-to-SQL uses schema from database-architect:

Table definitions
Relationships
Constraints
Indexes

With Developer

Text-to-SQL generates queries for developers:

Query templates
Parameterized queries
Query optimization
Error handling

Examples

Example 1: Simple Query

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

Example 2: Complex Query

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

Evaluation

Evaluation Framework

Based on Claude Cookbooks patterns, text-to-SQL evaluation includes:

Syntax Validation :

SQL syntax correctness
Schema compliance
Query structure validation

Functional Testing :

Query execution on test database
Result correctness
Performance validation

Promptfoo Integration :

Multiple prompt variants (basic, few-shot, chain-of-thought, RAG)
Temperature sweeps
Model comparisons (Haiku vs Sonnet)

Evaluation Configuration : Create a promptfoo config file for your evaluation setup (e.g., text_to_sql_config.yaml).

Running Evaluations

# Run text-to-SQL evaluation (create config first)
npx promptfoo@latest eval -c text_to_sql_config.yaml

Evaluation Metrics

Syntax Accuracy : Percentage of queries with valid SQL syntax
Functional Correctness : Percentage of queries returning correct results
Schema Compliance : Percentage of queries using correct schema
Performance : Query execution time and optimization

Best Practices from Cookbooks

1. Provide Schema Context

Always include complete database schema:

Table definitions with column types
Relationships and foreign keys
Constraints and indexes
Sample data patterns

2. Use Few-Shot Examples

Provide examples of similar queries:

Simple queries
Complex queries with joins
Aggregation queries
Subquery patterns

3. Chain-of-Thought for Complex Queries

For complex queries, use chain-of-thought reasoning:

Break down query into steps
Identify required tables
Plan joins and aggregations
Generate SQL step by step

4. RAG for Schema Understanding

Use RAG to retrieve relevant schema information:

Find relevant tables for query
Understand relationships
Get column details
Retrieve query patterns

Related Skills

classifier : Classify database queries
database-architect : Use for schema design
developer : Generate query code

Iron Laws

ALWAYS validate all table and column names against the provided schema before generating SQL
NEVER use string interpolation for query values — parameterized queries are mandatory without exception
ALWAYS apply a LIMIT clause (default 100) to SELECT queries unless the user explicitly overrides it
NEVER execute DROP, DELETE, TRUNCATE, or UPDATE statements without explicit user confirmation
ALWAYS explain the generated query logic in plain language so the user understands what will execute

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
String interpolation for values	SQL injection vulnerability	Use parameterized queries with `?` or `$N` placeholders
No LIMIT clause on SELECT	Returns all rows, risk of OOM and timeout	Default `LIMIT 100`, require explicit user override
Destructive SQL without confirmation	Irreversible data loss	Gate DROP/DELETE/TRUNCATE behind user confirmation
No schema validation	References non-existent tables or columns	Validate all identifiers against the provided schema
SELECT * without column list	Unpredictable results and performance waste	Always specify an explicit column list

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

Weekly Installs

Repository

oimiragieo/agent-studio

GitHub Stars

First Seen

Jan 27, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

github-copilot85

opencode85

codex84

gemini-cli84

cursor84

kimi-cli81

AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具

50,900 周安装