Schema Tools 使用说明

1. 功能概述

Schema Tools 提供两个主要功能：

1.1 DDL和MD文档生成

自动连接PostgreSQL数据库
批量处理表清单
使用LLM生成中文注释
自动检测枚举字段
生成标准化的DDL和MD文档

1.2 Question-SQL训练数据生成

验证DDL和MD文件完整性
分析表结构提取业务主题
为每个主题生成高质量的Question-SQL对
支持中断恢复和并行处理

1.3 一键工作流编排器（推荐）

端到端自动化执行完整流程
DDL/MD生成 → Question-SQL生成 → SQL验证修复
详细的执行报告和性能指标
支持灵活配置和错误恢复

2. 安装与配置

2.1 依赖安装

pip install asyncpg asyncio

2.2 基本配置

Schema Tools 使用项目现有的 LLM 配置，无需额外配置数据库连接。

3. 一键执行完整工作流（推荐）

3.1 工作流编排器概述

SchemaWorkflowOrchestrator 是 Schema Tools 的核心组件，提供端到端的自动化处理流程：

DDL和MD文档生成 - 连接数据库，生成表结构文档
Question-SQL对生成 - 基于文档生成训练数据
SQL验证和修复 - 验证SQL有效性并自动修复错误

3.2 命令行使用

基本使用（完整工作流）

python -m schema_tools.schema_workflow_orchestrator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统" \
  --db-name highway_db \
  --output-dir ./output

跳过SQL验证

python -m schema_tools.schema_workflow_orchestrator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --table-list tables.txt \
  --business-context "电商系统" \
  --db-name ecommerce_db \
  --skip-validation

禁用LLM修复

python -m schema_tools.schema_workflow_orchestrator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --table-list tables.txt \
  --business-context "管理系统" \
  --db-name management_db \
  --disable-llm-repair

不修改原始文件（仅生成报告）

python -m schema_tools.schema_workflow_orchestrator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --table-list tables.txt \
  --business-context "业务系统" \
  --db-name business_db \
  --no-modify-file

3.3 编程方式使用

import asyncio
from schema_tools.schema_workflow_orchestrator import SchemaWorkflowOrchestrator

async def run_complete_workflow():
    # 创建工作流编排器
    orchestrator = SchemaWorkflowOrchestrator(
        db_connection="postgresql://user:pass@localhost:5432/dbname",
        table_list_file="tables.txt",
        business_context="高速公路服务区管理系统",
        db_name="highway_db",
        output_dir="./output",
        enable_sql_validation=True,      # 启用SQL验证
        enable_llm_repair=True,          # 启用LLM修复
        modify_original_file=True        # 修改原始JSON文件
    )
    
    # 执行完整工作流程
    report = await orchestrator.execute_complete_workflow()
    
    # 处理结果
    if report["success"]:
        print(f"✅ 工作流程执行成功！")
        print(f"📄 最终输出文件: {report['final_outputs']['primary_output_file']}")
        print(f"❓ 最终问题数量: {report['final_outputs']['final_question_count']}")
        print(f"⏱️  总耗时: {report['performance_metrics']['total_duration']} 秒")
    else:
        print(f"❌ 工作流程执行失败: {report['error']['message']}")
        print(f"💥 失败步骤: {report['error']['failed_step']}")

# 运行工作流程
asyncio.run(run_complete_workflow())

3.4 工作流参数说明

参数	说明	默认值
`--db-connection`	数据库连接字符串	必需
`--table-list`	表清单文件路径	必需
`--business-context`	业务上下文描述	必需
`--db-name`	数据库名称（用于文件命名）	必需
`--output-dir`	输出目录	`./output`
`--skip-validation`	跳过SQL验证步骤	`False`（默认执行SQL验证）
`--disable-llm-repair`	禁用LLM修复功能	`False`（默认启用LLM修复）
`--no-modify-file`	不修改原始JSON文件	`False`（默认修改原文件）
`--verbose`	启用详细日志	`False`
`--log-file`	日志文件路径	无

3.5 工作流执行报告

工作流编排器会生成详细的执行报告，包括：

{
    "success": True,
    "workflow_summary": {
        "total_duration": 245.67,
        "completed_steps": ["ddl_md_generation", "question_sql_generation", "sql_validation"],
        "total_steps": 3
    },
    "processing_results": {
        "ddl_md_generation": {
            "total_tables": 8,
            "processed_successfully": 8,
            "duration": 89.23
        },
        "question_sql_generation": {
            "total_questions": 50,
            "total_themes": 5,
            "duration": 123.45
        },
        "sql_validation": {
            "success_rate": 0.94,
            "valid_sql_count": 47,
            "invalid_sql_count": 3,
            "duration": 32.99
        }
    },
    "final_outputs": {
        "primary_output_file": "./output/qs_highway_db_20240123_143052_pair.json",
        "final_question_count": 47
    },
    "performance_metrics": {
        "step1_duration": 89.23,
        "step2_duration": 123.45,
        "step3_duration": 32.99,
        "total_duration": 245.67
    }
}

3.6 优势特性

自动化流程：一个命令完成所有步骤
错误恢复：失败时保留已完成步骤的输出
灵活配置：可选择跳过验证、禁用修复等
详细报告：提供完整的执行状态和性能指标
向后兼容：支持所有现有参数和配置

4. 生成DDL和MD文档（分步执行）

4.1 命令格式

python -m schema_tools \
  --db-connection <数据库连接字符串> \
  --table-list <表清单文件> \
  --business-context <业务上下文> \
  [可选参数]

4.2 必需参数说明

参数	说明	示例
`--db-connection`	PostgreSQL数据库连接字符串	`postgresql://user:pass@localhost:5432/dbname`
`--table-list`	表清单文件路径	`./tables.txt`
`--business-context`	业务上下文描述	`"高速公路服务区管理系统"`

4.3 可选参数说明

参数	说明	默认值
`--output-dir`	输出目录路径	`training/generated_data`
`--pipeline`	处理链类型	`full`
`--max-concurrent`	最大并发表数量	`1`
`--verbose`	启用详细日志	`False`
`--log-file`	日志文件路径	`无`
`--no-filter-system-tables`	禁用系统表过滤	`False`
`--check-permissions-only`	仅检查数据库权限	`False`

4.4 处理链类型

full: 完整处理链（默认）- 生成DDL和MD文档
ddl_only: 仅生成DDL文件
analysis_only: 仅分析不生成文件

4.5 使用示例

基本使用

python -m schema_tools \
  --db-connection "postgresql://postgres:postgres@localhost:6432/highway_db" \
  --table-list ./schema_tools/tables.txt \
  --business-context "高速公路服务区管理系统"

指定输出目录和启用详细日志

python -m schema_tools \
  --db-connection "postgresql://postgres:postgres@localhost:6432/highway_db" \
  --table-list ./schema_tools/tables.txt \
  --business-context "高速公路服务区管理系统" \
  --output-dir ./output \
  --verbose

仅生成DDL文件

python -m schema_tools \
  --db-connection "postgresql://postgres:postgres@localhost:6432/highway_db" \
  --table-list ./schema_tools/tables.txt \
  --business-context "高速公路服务区管理系统" \
  --pipeline ddl_only

权限检查

python -m schema_tools \
  --db-connection "postgresql://postgres:postgres@localhost:6432/highway_db" \
  --check-permissions-only

4.6 表清单文件格式

创建一个文本文件（如 tables.txt），每行一个表名：

# 这是注释行
public.bss_service_area
public.bss_company
bss_car_day_count  # 默认为public schema
hr.employees       # 指定schema

4.7 输出文件

生成的文件都放在输出目录下（不创建子目录）：

output/
├── bss_service_area.ddl              # DDL文件
├── bss_service_area_detail.md        # MD文档
├── bss_company.ddl
├── bss_company_detail.md
├── filename_mapping.txt              # 文件名映射
└── logs/                            # 日志目录
    └── schema_tools_20240123.log

5. 生成Question-SQL训练数据（分步执行）

5.1 前置条件

必须先执行DDL和MD文档生成，确保输出目录中有完整的DDL和MD文件。

5.2 命令格式

python -m schema_tools.qs_generator \
  --output-dir <输出目录> \
  --table-list <表清单文件> \
  --business-context <业务上下文> \
  [可选参数]

5.3 必需参数说明

参数	说明	示例
`--output-dir`	包含DDL和MD文件的目录	`./output`
`--table-list`	表清单文件路径（用于验证）	`./tables.txt`
`--business-context`	业务上下文描述	`"高速公路服务区管理系统"`

5.4 可选参数说明

参数	说明	默认值
`--db-name`	数据库名称（用于文件命名）	`db`
`--verbose`	启用详细日志	`False`
`--log-file`	日志文件路径	`无`

5.5 使用示例

基本使用

python -m schema_tools.qs_generator \
  --output-dir ./output \
  --table-list ./schema_tools/tables.txt \
  --business-context "高速公路服务区管理系统" \
  --db-name highway_db

启用详细日志

python -m schema_tools.qs_generator \
  --output-dir ./output \
  --table-list ./schema_tools/tables.txt \
  --business-context "高速公路服务区管理系统" \
  --db-name highway_db \
  --verbose

5.6 SQL验证和修复

生成Question-SQL对后，可以使用SQL验证功能。注意：命令行使用时，默认启用LLM修复和文件修改功能。

python -m schema_tools.sql_validator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --input-file ./qs_highway_db_20240123_143052_pair.json \
  --output-dir ./validation_reports

SQL验证参数说明

参数	说明	默认值
`--db-connection`	数据库连接字符串	必需
`--input-file`	Question-SQL文件路径	必需
`--output-dir`	验证报告输出目录	输入文件同目录
`--disable-llm-repair`	禁用LLM修复功能	`False`（默认启用修复）
`--no-modify-file`	不修改原始JSON文件	`False`（默认修改原文件）
`--max-concurrent`	最大并发验证数	`5`
`--batch-size`	批处理大小	`10`
`--timeout`	单个验证超时时间（秒）	`30`
`--verbose`	启用详细日志	`False`
`--dry-run`	仅解析文件不执行验证	`False`
`--save-json`	保存详细JSON报告	`False`

SQL验证使用示例

# 基本验证（默认：启用LLM修复和文件修改）
python -m schema_tools.sql_validator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --input-file ./data.json

# 仅生成报告，不修改文件
python -m schema_tools.sql_validator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --input-file ./data.json \
  --no-modify-file

# 启用文件修改，但禁用LLM修复（仅删除无效SQL）
python -m schema_tools.sql_validator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --input-file ./data.json \
  --disable-llm-repair

# 性能调优参数
python -m schema_tools.sql_validator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --input-file ./data.json \
  --max-concurrent 10 \
  --batch-size 20 \
  --timeout 60 \
  --verbose

5.7 执行流程

文件验证：检查DDL和MD文件数量是否正确
表数量限制：最多处理20个表（可配置）
主题提取：LLM分析表结构，提取5个业务分析主题
Question-SQL生成：每个主题生成10个问题
结果保存：输出到 qs_<db_name>_<时间戳>_pair.json
SQL验证：验证生成的SQL语句有效性
自动修复：使用LLM修复无效的SQL语句（可选）

5.8 输出文件

output/
├── qs_highway_db_20240123_143052_pair.json  # 最终结果
├── qs_highway_db_20240123_143052_pair.json.backup  # 原文件备份（如果启用文件修改）
├── qs_intermediate_20240123_143052.json     # 中间结果（成功后自动删除）
├── qs_recovery_20240123_143052.json         # 恢复文件（异常中断时生成）
├── sql_validation_20240123_150000_summary.txt  # SQL验证报告
└── file_modifications_20240123_150000.log  # 文件修改日志（如果启用文件修改）

5.9 输出格式示例

[
  {
    "question": "按服务区统计每日营收趋势（最近30天）？",
    "sql": "SELECT service_name AS 服务区, oper_date AS 营业日期, SUM(pay_sum) AS 每日营收 FROM bss_business_day_data WHERE oper_date >= CURRENT_DATE - INTERVAL '30 day' AND delete_ts IS NULL GROUP BY service_name, oper_date ORDER BY 营业日期 ASC;"
  },
  {
    "question": "哪个服务区的车流量最大？",
    "sql": "SELECT service_area_id, SUM(customer_count) AS 总车流量 FROM bss_car_day_count WHERE delete_ts IS NULL GROUP BY service_area_id ORDER BY 总车流量 DESC LIMIT 1;"
  }
]

6. 配置详解

6.1 主要配置项

配置文件位于 schema_tools/config.py：

# DDL/MD生成相关配置
"output_directory": "training/generated_data",     # 输出目录
"create_subdirectories": False,                    # 不创建子目录
"max_concurrent_tables": 1,                        # 最大并发数（避免LLM并发问题）
"sample_data_limit": 20,                          # 数据采样量
"large_table_threshold": 1000000,                 # 大表阈值（100万行）
"filter_system_tables": True,                      # 过滤系统表
"continue_on_error": True,                         # 错误后继续

# Question-SQL生成配置
"qs_generation": {
    "max_tables": 20,                             # 最大表数量限制
    "theme_count": 5,                             # 主题数量
    "questions_per_theme": 10,                    # 每主题问题数
    "max_concurrent_themes": 1,                   # 并行主题数（避免LLM并发问题）
    "continue_on_theme_error": True,              # 主题失败继续
    "save_intermediate": True,                    # 保存中间结果
}

# SQL验证配置
"sql_validation": {
    "max_concurrent_validations": 5,              # 并发验证数
    "validation_timeout": 30,                     # 单个验证超时(秒)
    "batch_size": 10,                             # 批处理大小
    "enable_sql_repair": False,                   # SQL修复功能（命令行覆盖为True）
    "modify_original_file": False,                # 文件修改功能（命令行覆盖为True）
    "readonly_mode": True,                        # 启用只读模式
}

6.2 修改配置

可以通过编辑 schema_tools/config.py 文件来修改默认配置。

7. 常见问题

7.1 表数量超过20个怎么办？

错误信息：

表数量(25)超过限制(20)。请分批处理或调整配置中的max_tables参数。

解决方案：

分批处理：将表清单分成多个文件，每个不超过20个表
修改配置：在 config.py 中增加 max_tables 限制

7.2 DDL和MD文件数量不一致

错误信息：

DDL文件数量(5)与表数量(6)不一致

解决方案：

检查是否有表处理失败
查看日志文件找出失败的表
重新运行DDL/MD生成

7.3 LLM调用失败

可能原因：

网络连接问题
API配额限制
Token超限

解决方案：

检查网络连接
查看中间结果文件，从断点继续
减少表数量或分批处理

7.4 权限不足

错误信息：

数据库查询权限不足

解决方案：

使用 --check-permissions-only 检查权限
确保数据库用户有SELECT权限
Schema Tools支持只读数据库

7.5 如何处理大表？

Schema Tools会自动检测大表（超过100万行）并使用智能采样策略：

前N行采样：使用 SELECT * FROM table LIMIT N 获取前N行
随机中间采样：使用 TABLESAMPLE SYSTEM 进行随机采样（失败时回退到OFFSET采样）
后N行采样：使用ROW_NUMBER窗口函数获取最后N行
三段采样确保数据的代表性，有效处理大表的多样性

大表阈值：默认为100万行（可在config.py中修改large_table_threshold）

7.6 生成的SQL语法错误

目前生成的SQL使用PostgreSQL语法。如果需要其他数据库语法：

在业务上下文中明确指定目标数据库
未来版本将支持MySQL等其他数据库

7.7 工作流编排器相关问题

Q: 工作流中途失败，如何恢复？ A: 工作流编排器会保留已完成步骤的输出文件，可以手动从失败步骤开始重新执行。

Q: 如何只执行部分步骤？ A: 使用 --skip-validation 跳过SQL验证，或使用分步执行方式调用各个模块。

Q: 工作流执行时间过长怎么办？ A: 可以通过减少表数量、调整并发参数、或分批处理来优化执行时间。

7.8 SQL验证器默认行为说明

重要：SQL验证器的命令行模式与配置文件中的默认值不同：

配置文件默认：enable_sql_repair=False, modify_original_file=False
命令行默认：启用LLM修复和文件修改功能
原因：命令行使用时通常期望完整的修复功能，而配置文件提供保守的默认值

如需禁用，请明确使用 --disable-llm-repair 或 --no-modify-file 参数。

8. 最佳实践

8.1 推荐工作流程

方式一：一键执行（推荐）

# 完整工作流程，一个命令搞定
python -m schema_tools.schema_workflow_orchestrator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统" \
  --db-name highway_db \
  --output-dir ./output

方式二：分步执行（调试时使用）

第一步：生成DDL和MD文档

python -m schema_tools --db-connection "..." --table-list tables.txt --business-context "..." --output-dir ./output

第二步：人工检查
检查DDL文件的表结构是否正确
确认MD文档中的注释是否准确
根据需要手动调整

第三步：生成Question-SQL

python -m schema_tools.qs_generator --output-dir ./output --table-list tables.txt --business-context "..."

第四步：验证SQL（可选）
```
python -m schema_tools.sql_validator --db-connection "..." --input-file ./qs_xxx.json
```
8.2 表清单组织
- 按业务模块分组
- 每组不超过15-20个表
- 使用注释说明每组的用途
8.3 业务上下文优化
- 提供准确的业务背景描述
- 包含行业特定术语
- 说明主要业务流程
8.4 输出文件管理
- 定期备份生成的文件
- 使用版本控制管理DDL文件
- 保留中间结果用于调试
8.5 工作流编排器最佳实践
- 首次使用：建议启用详细日志（--verbose）观察执行过程
- 生产环境：使用默认参数，启用SQL验证和修复
- 调试阶段：可以使用 --skip-validation 跳过验证步骤加快执行
- 质量要求高：使用 --no-modify-file 仅生成报告，手动审查后再决定是否修改

Schema Tools 使用说明.md 20 KB 文件歷史 原始文件

Schema Tools 使用说明

目录

1. 功能概述

1.1 DDL和MD文档生成

1.2 Question-SQL训练数据生成

1.3 一键工作流编排器（推荐）

2. 安装与配置

2.1 依赖安装

2.2 基本配置

3. 一键执行完整工作流（推荐）

3.1 工作流编排器概述

3.2 命令行使用

基本使用（完整工作流）

跳过SQL验证

禁用LLM修复

不修改原始文件（仅生成报告）

3.3 编程方式使用

3.4 工作流参数说明

3.5 工作流执行报告

3.6 优势特性

4. 生成DDL和MD文档（分步执行）

4.1 命令格式

4.2 必需参数说明

4.3 可选参数说明

4.4 处理链类型

4.5 使用示例

基本使用

指定输出目录和启用详细日志

仅生成DDL文件

权限检查

4.6 表清单文件格式

4.7 输出文件

5. 生成Question-SQL训练数据（分步执行）

5.1 前置条件

5.2 命令格式

5.3 必需参数说明

5.4 可选参数说明

5.5 使用示例

基本使用

启用详细日志

5.6 SQL验证和修复

SQL验证参数说明

SQL验证使用示例

5.7 执行流程

5.8 输出文件

5.9 输出格式示例

6. 配置详解

6.1 主要配置项

6.2 修改配置

7. 常见问题

7.1 表数量超过20个怎么办？

7.2 DDL和MD文件数量不一致

7.3 LLM调用失败

7.4 权限不足

7.5 如何处理大表？

7.6 生成的SQL语法错误

7.7 工作流编排器相关问题

7.8 SQL验证器默认行为说明

8. 最佳实践

8.1 推荐工作流程

8.2 表清单组织

8.3 业务上下文优化

8.4 输出文件管理

8.5 工作流编排器最佳实践

Schema Tools 使用说明.md 20 KB

文件歷史原始文件