PT-ONLINE-SCHEMA-CHANGE

• pt-online-schema-change模仿MySQL内部更改表的方式，但是它在您希望更改的表的副本上工作。这意味着原始表没有被锁定，客户端可以继续读取和更改其中的数据。
• pt-online-schema-change的工作方式是创建要修改的表的空副本，根据需要对其进行修改，然后将原始表中的行复制到新表中。当复制完成时，它将移走原始表并用新表替换它。默认情况下，它还会删除原始表。
• 数据复制过程是在小数据块中执行的，数据拷贝过程是在小的数据块中执行的，这些数据块被改变以试图使它们在特定的时间内执行(参见 --chunk-time)。这个过程与其他工具(如pt-table-checksum)的工作方式非常相似。在复制期间对原始表中的数据的任何修改将反映在新表中,因为该工具在原始表上创建触发器，以更新新表中的相应行。触发器的使用意味着如果表上已经定义了任何触发器，那么该工具将无法工作。
• 当工具完成将数据复制到新表中时，它使用一个自动 RENAME TABLE 操作来同时重命名原始表和新表。完成此操作后，该工具将删除原始表。
• 外键使工具的操作复杂化，并带来额外的风险。当外键引用表时，自动重命名原始表和新表的技术不起作用，在change schema完成后，该工具必须更新外键以引用新表。该工具支持两种实现此目的的方法。有关这一点，您可以在“–alter-foreign-keys-method.”方法的文档中了解更多。
• 外键也会产生一些副作用。最终的表将具有与原始表相同的外键和索引(除非在ALTER语句中指定了不同的外键和索引)，但是对象的名称可能会稍微更改，以避免MySQL和InnoDB中的对象名称冲突。
• 为了安全起见，该工具不会修改表，除非您指定—execute选项，该选项在默认情况下不启用。该工具支持各种其他措施来防止不必要的负载或其他问题，包括自动检测从库、连接从库以及使用以下安全检查：
• 1.在大多数情况下，除非表中有主键或惟一索引，否则该工具将拒绝操作 详见–alter
• 2 如果该工具检测到复制，则拒绝操作。有关详细信息，请参见 --[no]check-replication-filters
• 3 如果工具观察到复制过程中有任何从库延迟，它将暂停数据复制操作。详情请参阅max-lag。
• 4 如果检测到服务器上的负载过多，该工具将暂停或中止其操作。有关详细信息，请参见–max-load和–critical-load。
• 5.工具设置innodb_lock_wait_timeout=1和(对于MySQL 5.5和更新版本)lock_wait_timeout=60，这样它更有可能成为任何锁争用的受害者，并且不太可能中断其他事务。可以通过指定- -set-vars来更改这些值
• 6 如果外键约束引用该表，则该工具拒绝更改该表，除非您指- -alter-foreigkeys -method
• 7 该工具不能更改“Percona XtraDB集群”节点上的MyISAM表
   pt-online schema-change适用于Percona XtraDB集群(PXC) 5.5.28-23.7和更新版本，但是有两个限制:只能修改InnoDB表,必须将wsrep_OSU_method设置为TOI(完全顺序隔离) 如果主机是一个集群节点，而表是MyISAM，或者表正在被转换为MyISAM (ENGINE=MyISAM)，或wsrep_OSU_method不是TOI，则该工具将出现错误退出。没有办法禁用这些检查。这些工具忽略MySQL 5.7+生成的列，因为这些列的值是根据用于计算列值的表达式的值生成的。
   该工具将关于其活动的信息打印到STDOUT，以便您可以看到它在做什么。在数据复制阶段，它向STDERR打印进度报告。您可以通过指定—print获得更多信息。
   如果指定了–statistics ，则在最后打印各种内部事件计数的报告，如:
  

选项

–dry-run 和 --execute是互斥的。
 这个工具接受额外的命令行参数。有关详细信息，请参阅“大纲”和使用信息。

- - alter

 没有ALTER TABLE关键字的sql语法。您可以通过使用逗号指定表来执行多个修改。关于ALTER TABLE的语法，请参考MySQL手册
 以下限制适用，如果尝试，将导致工具以不可预知的方式失败:

• 在几乎所有情况下，表中都需要有一个主键或惟一索引。这是必要的，因为该工具创建了一个DELETE触发器，以便在流程运行时更新新表
   一个值得注意的例外是，当主键或惟一索引作为ALTER子句的一部分从现有列创建时;在这种情况下，它将使用这些列作为删除触发器。
• 不能使用RENAME子句重命名表。
• 不能通过使用删除和重新添加来重命名列。该工具不会将原始列的数据复制到新列。
• 如果您添加了一个没有默认值的列，并将其设置为NOT NULL，那么该工具将失败，因为它不会尝试为您猜测默认值;您必须指定默认值。
• 删除外键constraint_name需要指定_constraint_name而不是真正的constraint_name。由于MySQL的限制，pt-online schema-change在创建新表时向外键约束名添加了一个前导下划线。例如：删除这个外键
  你必须指定 --alter “DROP FOREIGN KEY _fk_foo”
• mysql5.0 可能会有bug 如果使用MySQL 5.0并将MyISAM转换为InnoDB，请确保验证新表!

- - alter-foreign-keys-method

 如何修改外键以便它们引用新表。引用要修改的表的外键必须得到特殊处理，以确保它们继续引用正确的表。当该工具重命名原始表以让新表取代其位置时，外键“跟随”重命名的表，必须更改外键以引用新表。
 该工具支持两种技术来实现这一点。它会自动找到引用要修改的表的“子表”。

• 自动确定哪种方法最好。如果可能，该工具将使用rebuild_constraints(有关详细信息，请参阅该方法的描述)，如果不使用rebuild_constraints，则使用drop_swap。

  rebuild_constraints

  • 此方法使用ALTER TABLE删除并重新添加引用新表的外键约束。这是首选的技术，除非有一个或多个“子”表非常大，以至于修改太长时间。该工具通过比较子表中的行数和该工具能够将行从旧表复制到新表的速度来确定这一点。如果工具估计子表的修改时间少于 --chunk-time，那么它将使用这种技术。为了估计修改子表所需的时间，该工具将行复制率乘以 --chunk-size-limit，因为MySQL的alter表通常比复制行的外部进程快得多。
     由于MySQL的限制，外键在它之前所做的修改之后将不会有相同的名称。该工具在重新定义外键时必须对其进行重命名，这将在名称中添加一个前导下划线。在某些情况下，MySQL还会自动重命名外键所需的索引

  drop_swap

 禁用外键检查(foreign_key_check =0)，然后在重命名新表之前删除原始表。这与交换旧表和新表的常规方法不同。
 这种方法速度更快，不会阻塞，但风险更大，原因有二。首先，在删除原始表和重命名临时表之间的短时间内，要更改的表根本不存在，对其进行查询将导致错误。其次，如果出现错误，并且不能将新表重命名为旧表的位置，那么就无法中止，因为旧表已经永久地消失了。这个方法强制-no-swap-tables和-no-drop-old-table。

- -[no]analyze-before-swap

默认 yes
在与旧表交换之前，在新表上执行ANALYZE表

- -ask-pass

连接的时候会要求提供密码

- -charset

默认字符集

- -[no]check-alter

默认 yes
解析指定的–alter，对于危险的操作会产生告警，如删除主键或者重命名列

- -check-interval

默认1s
当主从延时为–max-lag 秒的时候，检查check-interval；例如设置为10的时候，主从延时产生，则暂停10秒，再检查延时，如果依然有有延时，停止10s再检查；

- -[no]check-plan

默认yes
是否在执行前用EXPLAIN检查语句

- -[no]check-replication-filters

默认yes
如果在任何服务器上设置了任何复制筛选器，则中止。该工具寻找筛选复制的服务器选项，如binlog_ignore_db和replicate_do_db。如果它发现任何这样的过滤器，它会以一个错误中止。

- -check-slave-lag

如果复制延迟大于–max-lag就停止数据拷贝，设置该参数后会监控所有的复制进程，一旦发现任何大于–max-lag时间的就停止数据拷贝，如果不想监控所有的复制进程，可以通过–recursion-method来指定想要监控的对象

- -chunk-index

指定chunk的索引，工具默认会选择最合适的索引

- -chunk-index-columns

int类型
只使用chunk-index-columns的这么多最左列。这只适用于复合索引

- -chunk-size

默认 1000
要为复制的每个块选择的行数。允许的后缀是k, M, G
此选项可以覆盖默认行为，即动态调整块大小，以使块在确切的块时间秒内运行。当没有显式设置此选项时，将使用其默认值作为起点，但在此之后，工具将忽略此选项的值。但是，如果您显式地设置此选项，则它将禁用动态调整行为，并试图使所有块准确地指定行数。

- -chunk-size-limit

默认 4.0
不要复制比所需块大小大这么多倍的块
当表没有惟一索引时，块大小可能不准确。此选项指定对不准确性的最大可容忍限制。该工具使用来估计数据块中有多少行。如果该估计值超过了所需的块大小乘以限制，那么该工具将跳过该块。
这个选项的最小值是1，这意味着没有块可以大于 --chunk-size。您可能不想指定1，因为EXPLAIN报告的行是估计值，它可能与块中的实际行数不同。您可以通过指定0的值来禁用超大块检查。
该工具还使用此选项来确定如何处理引用要更改的表的外键。有关详细信息，请参见- alter-foreign -keys-method

- -chunk-time

默认0.5
工具会根据每次复制数据花费的时间自动调整chunk大小，尽可能使每次时间都相同；=0则不调节

- -config

读取配置文件，多个文件逗号分隔；如果指定则必须是第一个参数

- -critical-load

默认Threads_running=50； 每次chunk执行后会自动用SHOW GLOBAL STATUS检查负载情况，如果超过阈值则放弃

- -database

简写 -D
指定数据库

- -default-engine

该选项将导致新表使用系统默认引擎； 而不是原有表一致的引擎

- -data-dir

在不同的分区上创建新表

–remove-data-dir

默认 no
如果原表已通过–data-dir 创建，该参数会删除它并在默认datadir下创建新表

- -defaults-file

简写 -F
只从给定的文件中读取mysql选项。您必须提供一个绝对路径名

- -[no]drop-new-table

默认yes
如果复制原始表失败，则删除新表。
如果指定-no-drop-new-table和-no-swap-tables，则会在不修改原始表的情况下保留修改后的新表副本
–no-drop-new-table和 alter-foreign-keys-method drop_swap无法一起生效

- -[no]drop-old-table

默认yes
重命名原始表后删除它。在成功地重命名原始表以让新表取代其位置之后，如果没有错误，该工具默认情况下会删除原始表。如果有任何错误，该工具将保留原始表。
如果指定了-no-swap-tables，则没有要删除的旧表。

- -[no]drop-triggers

默认yes
在旧表上删除触发器
–no-drop-triggers 强制 --no-drop-old-table.

- -dry-run

创建和更改新表，但不要创建触发器、复制数据或替换原始表。与–execute互斥

- -execute

表明您已经阅读了文档，并希望更改该表。必须指定此选项才能更改表。如果不这样做，那么该工具将只执行一些安全检查并退出。这有助于确保您已经阅读了文档并了解了如何使用该工具。如果您没有阅读文档，则不要指定此选项

- -[no]check-unique-key-change

默认yes
如果–alter尝试增加唯一索引的的话，则工具不会运行； 因为增加唯一索引如果列有重复值，会发生丢失数据的情况；因为INSERT的时候默认采用"INSERT IGNORE"

- -force

强制运行，此选项在使用 alter-foreign-keys-method = none时绕过确认,可能打破外键约束

- -force-concat-enums

Percona Toolkit中的NibbleIterator可以检测具有枚举字段的索引，以及它所拥有的项是否已排序。根据MySQL文档https://dev.mysql.com/doc/refman/8.0/en/enum.html:

枚举值根据索引号排序，索引号取决于列规范中列出枚举成员的顺序。例如，枚举的“b”排序在“a”之前(“b”、“a”)。空字符串在非空字符串之前排序，空值在所有其他枚举值之前排序。
为了防止在枚举列上使用ORDER BY子句时出现意外结果，请使用以下技术之一:-按字母顺序指定枚举列表。-确保列是按词法排序的
而不是按索引编号，按转换顺序编码(col为CHAR)或按CONCAT顺序编码(col)。
Percona Toolkit中的NibbleIterator使用CONCAT(col)，但是这样做会增加开销，因为MySQL不能直接使用列，必须为每一行计算CONCAT的结果。
为了使用户能够看到此场景，如果有索引的ENUM字段中有未排序的项，则需要指定—force-concat-enums参数。

- -host

简写 -h
指定host

- -max-flow-ctl

有点类似-max-lag，但对于PXC集群。检查用于流控制的平均暂停时间集群，如果超过选项中指定的百分比，则使工具暂停。当检测到任何流控制活动时，值0将使工具暂停。默认情况下没有流控制检查。此选项适用于PXC版本5.6或更高版本。

- -max-lag

默认 1s暂停数据复制，直到所有副本的延迟都小于此值。在每个数据复制查询(每个块)之后，该工具使用Seconds_Behind_Master查看它所连接的所有副本的复制延迟。如果任何副本的延迟超过该选项的值，那么该工具将休眠 --check-interval秒，然后再次检查所有副本。如果指定–check-slave-lag，那么该工具只检查该服务器的延迟，而不是所有服务器。如果您想要确切地控制该工具所监视的服务器，请使用DSN值–recursion-method。
该工具永远等待副本停止延迟。如果任何副本被停止，该工具将永远等待，直到副本启动。当所有副本都在运行且不太滞后时，数据复制将继续。
该工具在等待时打印进度报告。如果副本被停止，它将立即打印进度报告，然后在每个进度报告间隔时再次打印。

- -max-load

默认: Threads_running=25
检查每个块之后显示的全局状态，如果任何状态变量高于其阈值，则暂停。该选项接受一个逗号分隔的MySQL状态变量列表。每个变量后面都可以有一个可选的=MAX_VALUE(或:MAX_VALUE)。如果没有给出，该工具通过检查当前值并将其增加20%来确定阈值。
 例如，如果您希望工具在Threads_connected过高时暂停，那么可以指定“Threads_connected”，工具在开始工作时检查当前值，并在该值上添加20%。如果当前值是100，那么当Threads_connected超过120时，该工具将暂停，当Threads_connected再次低于120时，该工具将恢复工作。如果要指定显式阈值，如110，可以使用“Threads_connected:110”或“Threads_connected=110”。
 此选项的目的是防止工具向服务器添加过多负载。如果数据复制查询具有侵入性，或者会导致锁等待，那么服务器上的其他查询将倾向于阻塞和排队。这通常会导致Threads_running增加，该工具可以在每个查询完成后立即运行SHOW GLOBAL STATUS来检测这一点。如果您为这个变量指定了一个阈值，那么您可以指示该工具等待，直到查询再次正常运行。然而，这并不妨碍排队;它只会让服务器有机会从排队中恢复。如果您注意到排队，最好减少块时间。

- -preserve-triggers

保留指定的旧触发器。从MySQL 5.7.2开始，可以为具有相同触发事件和动作时间的给定表定义多个触发器。这允许我们添加pt-online-schema-change所需的触发器，即使表已经有了自己的触发器。如果启用此选项，pt-online-schema-change 将尝试将所有现有触发器复制到新表中，以确保在更改表之后可以应用旧触发器

–new-table-name

默认: %T_new
交换之前的新表名。%T替换为原始表名。当使用默认值时，该工具将名称的前缀设置为10_(下划线)，以查找唯一的表名。如果指定了表名，则该工具不会在其前面加上_前缀，因此该表必须不存在。

- -null-to-not-null

允许将允许空值的列修改为不允许空值的列。包含空值的行将转换为定义的默认值。如果没有明确的默认值，MySQL会根据数据类型分配一个默认值，例如0表示数字数据类型，“表示字符串数据类型。

- -only-same-schema-fks

仅在与原始表相比的相同模式上的表上检查foreigns键。这个选项很危险，因为如果在其他模式中使用FKs重新定义表，将无法检测到它们。

- -password

简写 -p
密码

- -pause-file

改参数指定的文件存在的时，操作将会暂停

- -pid

创建给定的PID文件。如果PID文件已经存在，且其中包含的PID与当前PID不同，则该工具不会启动。但是，如果PID文件存在并且它所包含的PID不再运行，该工具将用当前PID覆盖PID文件。PID文件在工具退出时自动删除

- -plugin

定义pt_online_schema_change_plugin类的Perl模块文件。插件允许您编写一个Perl模块，该模块可以连接到pt-online模式更改的许多部分。这需要对Perl和Percona工具箱约定有很好的了解，这超出了本文档的范围。如果您有任何问题或需要帮助，请联系Percona。
有关更多信息，请参见“plugin”

- -port

简写-P 连接端口

- -print

将SQL语句打印到STDOUT。指定此选项允许您查看该工具执行的大多数语句 您可以和–dry-run同时运行

- -progress

默认 time,30
在复制行时向STDERR打印进度报告。该值是一个逗号分隔的列表，包含两部分。第一部分可以是百分比、时间或迭代;第二部分指定应该以百分比、秒或迭代次数为单位打印更新的频率。

- -quiet

简写 -q
不要打印消息到STDOUT(禁用- -progress)。错误和警告仍然打印到STDERR。

- -recurse

发现从库时在层次结构中递归的级别数。默认的是无限的。

- -recursion-method

默认: processlist,hosts
查找Slave的递归方法

- -skip-check-slave-lag

检查SLAVE的时候，指定该SLAVE跳过
DSN在检查从延迟时跳过。它可以被多次使用。例如:-skip-check-slave-lag h=127.0.0.1,P=12345 -skip-check-slave-lag h=127.0.0.1,P=12346 Plase考虑到，即使对于MySQL驱动程序h=127.1 = h=127.0.0.1，这个参数也需要指定完整的IP地址。

- -slave-user

设置用于连接从服务器的用户。此参数允许您拥有对从服务器具有较少特权的不同用户，但该用户必须存在于所有从服务器上

- -slave-password

设置用于连接从服务器的密码。它可以与–slave-user一起使用，用户的密码在所有slave上必须相同。

- -set-vars

默认

命令行上指定的变量覆盖这些默认值。例如，指定- -set-vars wait_timeout=500将覆盖10000的默认值。
如果无法设置变量，该工具将打印警告并继续。
注意，设置sql_mode变量需要一些巧妙的转义来解析引号和逗号。

--set-vars sql_mode=\'STRICT_ALL_TABLES\\,ALLOW_INVALID_DATES\'

注意单反斜杠表示引号，双反斜杠表示逗号。

- -sleep

默认 0
复制每个数据块后需要多长时间(以秒为单位)睡眠。当无法通过—max- delay和—max-load进行节流时，此选项非常有用。应该使用小于秒的小值，比如0.1，否则该工具复制大型表可能会花费很长时间。

- -socket

简写-S 连接使用的Socket文件

- -statistics

打印关于内部计数器的统计信息。这有助于查看与插入数相比，有多少警告被抑制

- -[no]swap-tables

默认yes
交换原始表和修改后的新表。这一步完成了在线模式更改过程，使用新模式的表取代了原来的表。原来的表变成了“old”
除非你禁用drop-old-table，否则这个工具就会删除它。
使用-no-swap-tables会运行整个过程，它会创建新表，它会复制所有行，但最后它会删除新表。它的目的是运行一个更现实的-–dry-run.。

- -tries

尝试关键操作的次数。如果某些操作由于非致命的、可恢复的错误而失败，该工具将等待并再次尝试该操作。这些是重试的操作，它们的默认尝试次数和两次尝试之间的等待时间(以秒为单位):
必须指定这三个值

- -user

连接用户名

- -version

版本

- -[no]version-check

默认yes
检查Percona Toolkit的最新版本