#sql

sqlserver-tidb-replay

Replay SQL Server slow query logs on TiDB to verify compatibility, compare performance, and generate syntax conversion reports during migration.

Dongdong-Bryant@dongdong-bryant

Install

openclaw skills install @dongdong-bryant/sqlserver-tidb-replay

SQL Server → TiDB SQL 回放工具

工具简介

参考 Bowen-Tang/sql-replay（MySQL → TiDB 流量回放工具），实现 SQL Server → TiDB 的 SQL 回放能力。

核心用途：

数据库迁移前：验证 SQL 兼容性
迁移后：对比性能差异 + 生成语法转换建议
压测：模拟真实业务负载

参考来源：GitHub - Bowen-Tang/sql-replay: mysql slow query replay

工作流程

text

┌─────────────────────────────────────────────────────────────┐
│  ① 采集 (collect)                                          │
│  SQL Server 慢查询日志 → CSV（非标准 XE 格式）             │
│  ⚠️ 需要转换为标准 SQL 格式                                │
│  目标：sqlserver.sql_statement_completed 事件              │
└─────────────────────────────────────────────────────────────┘
                            ↓ CSV 文件
┌─────────────────────────────────────────────────────────────┐
│  ② CSV 转标准 SQL (csv_to_sql)                            │
│  解析原始日志 → 标准 SQL 语句                              │
│  功能：去除 XE 前缀符号、提取 SQL 文本、格式化             │
└─────────────────────────────────────────────────────────────┘
                            ↓ 标准 SQL CSV
┌─────────────────────────────────────────────────────────────┐
│  ③ 解析 (parse)                                            │
│  CSV → Python 解析 → JSON 中间格式                         │
│  功能：去重、过滤无效SQL、生成可回放JSON                    │
└─────────────────────────────────────────────────────────────┘
                            ↓ JSON 文件
┌─────────────────────────────────────────────────────────────┐
│  ④ 回放 (replay)                                           │
│  JSON → Python 回放脚本 → TiDB 并行执行                    │
│  功能：连接池、并发执行、按 conn_id 串行                   │
│  输出：results_{task_name}.json                            │
└─────────────────────────────────────────────────────────────┘
                            ↓ 结果 JSON
┌─────────────────────────────────────────────────────────────┐
│  ⑤ 分析 (analyze)                                          │
│  结果 JSON → 分析脚本                                       │
│  功能：                                                      │
│  - 识别语法不兼容问题                                       │
│  - 性能对比分析（TiDB vs SQL Server）                       │
│  - 自动生成语法转换建议（转换前/后/点）                     │
│  - HTML 报告（含语法转换对照表）                            │
└─────────────────────────────────────────────────────────────┘

前置准备

环境要求

Python 3.8+
pymysql（连接 TiDB）
pandas（解析 CSV）
PowerShell 5.1+（采集用，Windows 环境）

TiDB 连接信息

bash

# 方式一：配置环境变量
export TIDB_HOST="your-tidb-host"
export TIDB_PORT="4000"
export TIDB_USER="root"
export TIDB_PASSWORD="your-password"
export TIDB_DATABASE="test_db"

# 方式二：命令行参数传入（优先级更高）

核心功能说明

CSV 转标准 SQL（关键步骤）

SQL Server 慢查询日志导出的 CSV 不是标准的 XE 格式，包含大量 XE 前缀符号和混合格式，需要先转换为标准 SQL 语句。

原始 CSV 常见问题：

SQL 文本被截断或换行
包含 XE 事件前缀（如 sql_statement_completed、sp_statement_completed）
变量参数化符号（@1, @2, N'' 等 Unicode 前缀）
多行合并问题

转换脚本：csv_to_sql.py
自动处理：

去除 XE 事件前缀
合并被截断的 SQL（检测分号断句）
替换 SQL Server 特有参数格式
去除不可见字符

使用步骤

① 采集 SQL Server 慢日志

在 Windows 服务器上运行 PowerShell 脚本：

powershell

# 方式一：Extended Events（推荐，结构清晰）
.\collect_xe.ps1 -SessionName "slow_query_capture" -ThresholdMs 1000 -OutputPath "C:\slow_logs\slow_20260412.csv"

# 方式二：从 SQL Server Management Studio 导出慢查询日志
# 右键 → 导出 → CSV（含 statement、duration、cpu 等字段）

采集的字段：

字段	说明
statement	SQL 文本
duration_us	执行时间，微秒
cpu_us	CPU 时间，微秒
physical_reads	物理读次数
logical_reads	逻辑读次数
row_count	返回行数
start_time	开始执行时间
database_name	所属数据库
session_id	连接 ID

注意：采集需要 VIEW SERVER STATE 权限。建议在测试环境运行。

② CSV 转标准 SQL 格式

bash

python3 scripts/csv_to_sql.py \
  --input /path/to/raw_slow_query.csv \
  --output /path/to/standard_sql.csv \
  --normalize \
  --remove-prefix

参数说明：

参数	说明
`--input`	原始 CSV 路径
`--output`	标准 SQL CSV 输出路径
`--normalize`	规范化 SQL 格式（去除多余空白）
`--remove-prefix`	去除 XE 事件前缀符号

转换后字段：

字段	说明
sql_text	标准 SQL 文本
duration_ms	执行时间（毫秒，标准化）
database_name	数据库名
session_id	连接 ID

③ 解析 CSV 为回放格式

bash

python3 scripts/parse_csv.py \
  --input /path/to/standard_sql.csv \
  --output /path/to/slow_20260412.format.json \
  --filter-type select,insert,update,delete \
  --filter-duration-ms 1000 \
  --remove-admin \
  --lang cn

解析输出 JSON 格式：

json

[
  {
    "conn_id": "52",
    "start_time": "2026-04-12T10:00:01.123",
    "sql": "SELECT c FROM sbtest1 WHERE id=250438",
    "sql_type": "select",
    "duration_us": 380,
    "database": "test_db"
  }
]

④ 回放至 TiDB

bash

python3 scripts/replay_tidb.py \
  --input /path/to/slow_20260412.format.json \
  --host $TIDB_HOST \
  --port $TIDB_PORT \
  --user $TIDB_USER \
  --password $TIDB_PASSWORD \
  --database $TIDB_DATABASE \
  --speed 1.0 \
  --workers 4 \
  --output-dir ./replay_results \
  --task-name "test_migration"

回放输出：

text

replay_results/
├── test_migration_conn_52.json   # 每个 conn_id 一个文件
├── test_migration_conn_88.json
└── test_migration_summary.json   # 汇总信息

汇总文件格式：

json

{
  "task_name": "test_migration",
  "total_sqls": 1523,
  "total_errors": 12,
  "avg_duration_us": 4523,
  "max_duration_us": 128500,
  "compatibility_rate": "99.21%"
}

⑤ 生成分析报告（含语法转换）

bash

python3 scripts/analyze_results.py \
  --input-dir ./replay_results \
  --task-name "test_migration" \
  --output ./replay_report.html \
  --source-db "SQL Server 2022" \
  --target-db "TiDB v8.0"

报告内容：

✅ SQL 兼容性统计（错误类型分布）
✅ 性能对比分析（TiDB vs SQL Server）
✅ 慢 SQL Top 10
✅ 语法转换对照表（转换前 / 转换后 / 转换点）
✅ 迁移风险评估

语法转换功能

自动识别的不兼容模式

类别	SQL Server 写法	TiDB 改写	转换说明
OUTPUT clause	`INSERT INTO t OUTPUT inserted.id VALUES(...)`	`INSERT INTO t VALUES(...); SELECT LAST_INSERT_ID();`	TiDB 不支持 OUTPUT clause，用 LAST_INSERT_ID() 替代
NVARCHAR	`N'Unicode字符串'`	`CAST('字符串' AS CHAR)`	TiDB 字符集差异，需显式 CAST
OPENJSON	`SELECT * FROM OPENJSON(@json)`	`JSON_EXTRACT(@json, '$')`	TiDB 不支持 OPENJSON，用 JSON 函数替代
Sequence	`NEXT VALUE FOR seq_name`	`NEXTVAL('seq_name')`	TiDB 序列语法不同
OFFSET	`OFFSET 10 ROWS FETCH NEXT 5 ROWS`	`LIMIT 5 OFFSET 10`	TiDB LIMIT...OFFSET 顺序相反
TOP	`SELECT TOP 10 * FROM t`	`SELECT * FROM t LIMIT 10`	TiDB 用 LIMIT 替代 TOP
INTO	`SELECT * INTO #temp FROM t`	`CREATE TEMPORARY TABLE t AS SELECT...`	TiDB 不支持 SELECT INTO 临时表
MERGE	`MERGE INTO t USING...`	`INSERT...ON DUPLICATE KEY UPDATE`	TiDB 不支持 MERGE，用 IODU 替代

报告中的语法转换表示例

text

┌──────────────────────────────────────────────────────────────────────────────┐
│  语法转换记录 #12                                                            │
├────────────────────────────────────────────────────────────────────────────┤
│  源 SQL Server：                                                             │
│  INSERT INTO orders (name, amount)                                          │
│  OUTPUT inserted.order_id                                                  │
│  VALUES ('商品A', 100)                                                      │
├────────────────────────────────────────────────────────────────────────────┤
│  转换后 TiDB：                                                               │
│  INSERT INTO orders (name, amount)                                          │
│  VALUES ('商品A', 100);                                                     │
│  SELECT LAST_INSERT_ID() AS order_id;                                       │
├────────────────────────────────────────────────────────────────────────────┤
│  转换点：                                                                   │
│  1. OUTPUT inserted.order_id → SELECT LAST_INSERT_ID()                     │
│  2. 原因：TiDB 不支持 OUTPUT clause                                        │
│  3. 影响：需应用层调整获取自增 ID 的方式                                     │
└────────────────────────────────────────────────────────────────────────────┘

完整使用案例

场景：某银行核心系统 SQL Server → TiDB 迁移验证

背景：银行信贷系统从 SQL Server 2019 迁移至 TiDB，需要验证 2000+ 条核心 SQL 的兼容性。

Step 1：生产库慢日志采集

在 SQL Server 生产库上运行（阈值设为 500ms）：

powershell

.\collect_xe.ps1 -SessionName "credit_slow" -ThresholdMs 500 -OutputPath "C:\logs\credit_slow_20260412.csv"

采集结果：约 3800 条慢查询，覆盖 3 天的业务高峰期。

Step 2：CSV 转标准 SQL

bash

python3 scripts/csv_to_sql.py \
  --input credit_slow_20260412.csv \
  --output credit_slow_standard.csv \
  --normalize \
  --remove-prefix

Step 3：解析并过滤

bash

python3 scripts/parse_csv.py \
  --input credit_slow_standard.csv \
  --output credit_slow.format.json \
  --filter-type select,insert,update,delete \
  --filter-duration-ms 500 \
  --remove-admin

解析后：2156 条有效 SQL。

Step 4：回放至 TiDB 测试环境

bash

python3 scripts/replay_tidb.py \
  --input credit_slow.format.json \
  --host 192.168.1.100 \
  --port 4000 \
  --user root \
  --password "Xszyh@315315" \
  --database credit_db \
  --speed 2.0 \
  --workers 8 \
  --output-dir ./replay_results \
  --task-name "credit_migration"

Step 5：生成报告

bash

python3 scripts/analyze_results.py \
  --input-dir ./replay_results \
  --task-name "credit_migration" \
  --output credit_migration_report.html \
  --source-db "SQL Server 2019" \
  --target-db "TiDB v8.0"

报告结果示例：

text

迁移兼容性评估报告
===============================
源库：SQL Server 2019
目标库：TiDB v8.0
采集时间：2026-04-12
总SQL数：2156
兼容性：98.6%（错误SQL 30条）

错误分布：
  - 语法不兼容：8条（主要是 OUTPUT clause）
  - 函数不存在：12条（DB2兼容函数）
  - 字符集问题：5条（NCHAR/NVARCHAR vs CHAR/VARCHAR）
  - 杂项错误：5条

语法转换记录：
  - #1: OUTPUT clause → SELECT LAST_INSERT_ID()（12条）
  - #2: N'' Unicode前缀 → CAST() 转换（8条）
  - #3: OFFSET...FETCH → LIMIT...OFFSET（15条）
  - #4: OPENJSON → JSON_EXTRACT（5条）

高风险SQL（需手动改写）：
  1. proc_audit_insert (行12) - OUTPUT clause
  2. proc_statement_get (行89) - OPENJSON 函数
  ...

性能对比（成功SQL）：
  - TiDB 平均响应：12.3ms
  - SQL Server 平均响应：45.2ms
  - TiDB 加速比：3.7x

常见问题

Q: CSV 是慢查询日志，不是标准 XE 格式怎么办？

A：这是正常情况。SQL Server 慢查询日志导出时格式不统一，需用 csv_to_sql.py 进行标准化转换。该脚本会自动处理换行符、XE 前缀、变量参数等问题。

Q: Extended Events 会话对生产库性能影响大吗？

A：XE 设计为低开销，建议阈值设高一些（≥500ms）避免量太大。如果 CPU 紧张，可使用 histogram 目标先看分布。

Q: 回放时出现大量连接错误？

A：检查 TiDB 连接数限制（max_connections），同时调整 --workers 参数。SQL Server 和 TiDB 的连接池模型不同，建议从 4 开始逐步加压。

Q: 语法转换是自动的吗？

A：分析报告会自动识别常见的语法不兼容模式，并给出转换建议。但最终改写需人工确认，特别是涉及业务逻辑的部分。

Q: 性能对比怎么做的？

A：回放时会记录 TiDB 执行时间，汇总文件中会与原 SQL Server 的 duration_us 进行对比。注意：相同数据量下对比才有意义。

Q: 能回放存储过程吗？

A：可以，但采集的是 sp_statement_completed 事件。需要确保 TiDB 端有对应的存储过程（存储过程不会被自动翻译，需手动迁移）。

输出文件说明

文件	说明
`*_raw.csv`	原始采集数据
`*_standard.csv`	标准 SQL CSV（已转换）
`*.format.json`	解析后的回放中间格式
`replay_results/*.json`	回放执行结果
`replay_report.html`	最终兼容性报告（含语法转换对照表）

与 MySQL→TiDB 回放工具的区别

维度	Bowen-Tang/sql-replay	本工具
源数据库	MySQL slow log	SQL Server 慢查询日志
日志格式	MySQL slow log text	Extended Events CSV（非标准）
CSV 标准化	不需要	需要（csv_to_sql.py）
语法转换	无	自动识别并生成转换对照表
性能对比	基础	完整对比分析
回放目标	TiDB	TiDB

Skill 版本：1.1.0 | 参考：sql-replay v0.3.4 | 适用：SQL Server 2008+ → TiDB 5.0+

sqlserver-tidb-replay

Install

SQL Server → TiDB SQL 回放工具

工具简介

工作流程

前置准备

环境要求

TiDB 连接信息

核心功能说明

CSV 转标准 SQL（关键步骤）

使用步骤

① 采集 SQL Server 慢日志

② CSV 转标准 SQL 格式

③ 解析 CSV 为回放格式

④ 回放至 TiDB

⑤ 生成分析报告（含语法转换）

语法转换功能

自动识别的不兼容模式

报告中的语法转换表示例

完整使用案例

场景：某银行核心系统 SQL Server → TiDB 迁移验证

常见问题

Q: CSV 是慢查询日志，不是标准 XE 格式怎么办？

Q: Extended Events 会话对生产库性能影响大吗？

Q: 回放时出现大量连接错误？

Q: 语法转换是自动的吗？

Q: 性能对比怎么做的？

Q: 能回放存储过程吗？

输出文件说明

与 MySQL→TiDB 回放工具的区别

Related skills