pt-fingerprint

把查询转换为指纹（fingerprint），使相似查询可以归为一组。

语法

pt-fingerprint [OPTIONS] [FILES]

• 用 --query 选项时，把该选项的值转换为指纹。
• 不带选项时，把命令行参数当作 FILE，读取并转换其中以分号分隔的查询；FILE 为 - 时读标准输入。

转换单条查询：

pt-fingerprint --query "select a, b, c from users where id = 500"

转换整个文件：

pt-fingerprint /path/to/file.txt

用法示例

pt-fingerprint 不连库、不涉及密码，命令可直接复制运行。它把一条或多条查询抽象成规范化指纹，便于把同类查询归组。

场景：从管道喂入单条查询

已经在剪贴板或脚本里拿到一条 SQL，用管道直接喂给它（- 表示读标准输入），免去写文件：

echo "SELECT * FROM orders WHERE user_id = 123 AND status = 'paid'" | pt-fingerprint -

场景：列名/表名带序号也归为一类

分表（shard_1、shard_2）或列名带序号（col1、col2）时，加 --match-embedded-numbers 把整段带数字的标识符当成单个占位符，让不同分片/列的相似查询更彻底地归到一起：

pt-fingerprint --match-embedded-numbers --query "UPDATE shard_2 SET col1 = 1 WHERE id = 99"

场景：查询里嵌了 MD5 哈希

当查询条件里出现 32 位 MD5 串（如按文件哈希查表）时，用 --match-md5-checksums 把它整体当成一个占位符，而不是被默认的数字匹配规则拆坏：

pt-fingerprint --match-md5-checksums --query "SELECT * FROM files WHERE md5 = 'fbc5e685a5d3d45aa1d0347fdb7c4d35'"

场景：多值 INSERT 折叠成单个模板

批量写入的多值 INSERT 会被缩减成单个 VALUES() 模板，方便把"同一形状的插入"归为一类来统计：

pt-fingerprint --query "INSERT INTO t (a,b) VALUES (1,2),(3,4),(5,6)"

功能说明

查询指纹是查询的抽象形式，使相似查询可以归组。抽象化会移除字面值、规范空白等。 例如下面两条查询：

SELECT name, password FROM user WHERE id='12823';
select name,   password from user
  where id=5;

都会被指纹化为：

select name, password from user where id=?

指纹化处理了大量实际场景中的特殊情况，例如：5 个字面值的 IN 列表与 4 个字面值的等价， 因此字面值列表会折叠为一个。主要转换规则包括：

• 把来自 mysqldump 的所有 SELECT 查询归为一组（pt-table-checksum 的校验查询同理）。
• 多值 INSERT 缩减为单个 VALUES() 列表。
• 去除注释。
• 抽象 USE 语句中的数据库名，所有 USE 语句归为一组。
• 替换所有字面值（如带引号的字符串）；十六进制字面值同样被替换；NULL 视为字面值； 标识符中内嵌的数字也会被替换（users_2009 与 users_2010 指纹相同）。
• 所有空白折叠为单个空格。
• 整条查询转小写。
• IN() 与 VALUES() 列表中的字面值无论数量多少都替换为单个占位符。
• 多个相同的 UNION 查询折叠为一个。

选项

选项	说明
--[no]buffer-stdout	默认开启 STDOUT 缓冲；使用 tee、kubectl logs 等后处理工具想看到实时进度时可关闭
--config	类型：Array。读取逗号分隔的配置文件列表；如指定必须放在命令行第一个选项的位置
--help	显示帮助并退出
--match-embedded-numbers	匹配嵌入在单词中的数字并作为单个值替换：catch22 整体替换为 ?（默认会把 catch22 替换成 catch?）。当库/表名含数字时有用
--match-md5-checksums	匹配 MD5 校验值并作为单个值替换：如 fbc5e685... 整体替换为 ?（默认替换为 fbc?）
--query	类型：string。要转换为指纹的查询
--version	显示版本并退出

其他信息

• 通用说明：已知问题的反馈方式、PTDEBUG 调试安全提示、系统要求基线，见 通用说明。

更多细节请阅读 官方文档。