pt-osc 启动需同时满足三项硬性条件:目标表有主键或唯一索引、原表无任何触发器、操作用户具备 TRIGGER、REPLICATION SLAVE 和 PROCESS 权限;--dry-run 仅做静态检查,无法暴露触发器创建失败、从库延迟、主键字段类型变更等运行时风险;加唯一索引前须人工校验并清理重复值,否则静默覆盖;MySQL 8.0.12+ 的 INSTANT DDL 应优先使用,避免 pt-osc 无谓开销。

pt-osc 不是“开了就跑”的命令,不满足硬性条件会直接报错退出,不是警告;真正出问题往往在 --execute 阶段,--dry-run 根本测不出来。
必须满足的三项硬性条件
缺一不可,否则 pt-online-schema-change 启动即失败:
- 目标表必须有主键或唯一索引——普通二级索引(如
INDEX idx_name (col))不满足,工具无法分块读取和触发器精准定位行 - 原表不能已存在任何触发器——
pt-osc要自己建INSERT/UPDATE/DELETE三类触发器,已有触发器会冲突报错 - 操作用户需同时具备
TRIGGER、REPLICATION SLAVE、PROCESS权限——注意:REPLICATION SLAVE权限即使单机部署也必须有,它用于读取binlog position判断复制延迟
为什么 --dry-run 容易让人误判安全
--dry-run 只做静态检查:语法、权限、表结构兼容性。它不连接从库、不创建触发器、不测复制延迟,所有关键风险点都被绕过:
- 触发器创建失败:比如表名含特殊字符(空格、短横线)、数据库名用了反引号,
--dry-run不报,--execute卡在Creating triggers步骤 - 从库延迟超限:启用了
--check-replica-lag,但某从库积压了 120 秒,pt-osc会暂停拷贝并轮询,看起来像“卡住”,实则是主动保护 - 主键字段被修改:如
--alter "MODIFY id BIGINT UNSIGNED",虽语法合法,但触发器中OLD.id/NEW.id比较可能因隐式类型转换失效,导致UPDATE同步丢失
建议始终加 --print,看它实际生成的 CREATE TRIGGER 和 REPLACE INTO 语句是否符合预期。
安装、修复、更新或打包一个基于 Python 和 PyMySQL 实现的 Windows `mysql` 命令。适用于用户希望在 PowerShell/CMD 中输入 `mysql` 时重定向到 Python 实现、需要交互式输入 MySQL 连接信息、需要同步到当前用户本地 bin 目录,或需要将该能力封装成可公开复用的 Codex skill。
加索引时,普通索引和唯一索引行为完全不同
不能混用,否则数据可能静默丢失:
- 普通索引(
ADD INDEX idx_col (col)):全量拷贝走INSERT IGNORE,不校验重复,性能快,适合快速上线 - 唯一索引(
ADD UNIQUE INDEX uk_col (col)):pt-osc不校验全表唯一性,遇到重复值直接覆盖(后写生效),历史数据可能丢!必须提前执行:SELECT col, COUNT(*) FROM t GROUP BY col HAVING COUNT(*) > 1并清理重复行 - 如果只是想“防误插”,但允许历史重复存在,可先加普通索引,再通过应用层控制新增数据
MySQL 8.0.12+ 的 INSTANT 变更别用 pt-osc
对 ADD COLUMN、DROP COLUMN、CHANGE COLUMN(仅限长度扩展)等操作,MySQL 原生支持 ALGORITHM=INSTANT,毫秒级完成、完全无锁:
- 用
pt-osc做ADD COLUMN是杀鸡用牛刀:多出触发器开销、数据拷贝压力、临时表空间占用 - 更危险的是:
pt-osc的REPLACE INTO在遇到NOT NULL新列且无默认值时,会因缺失值写入失败;而原生INSTANT会自动补DEFAULT或NULL - 验证方式:
ALTER TABLE t ADD COLUMN c INT DEFAULT 0, ALGORITHM=INSTANT;成功即表示可用,此时应直接走原生 DDL
真正容易被忽略的是:pt-osc 完全不识别 INSTANT 能力,它一律按老流程走影子表 + 触发器——你手动指定 --alter "ADD COLUMN c INT",它照样拷全表、建触发器、占两倍磁盘空间。










