gh-ost 参数解析，看着一篇就够了！

gh-ost --help
Usage of gh-ost:
  -aliyun-rds
        set to 'true' when you execute on Aliyun RDS.
        ##在阿里云  RDS 上使用该工具时，需要执行该参数
  -allow-master-master
        explicitly allow running in a master-master setup
        ##明确允许在双主架构下运行该工具
  -allow-nullable-unique-key
        allow gh-ost to migrate based on a unique key with nullable columns. As long as no NULL values exist, this should be OK. If NULL values exist in chosen key, data may be corrupted. Use at your own risk!
        ##对于依赖唯一索引来划分chunk(表中没有主键情况下)，如果唯一索引中有null值，默认会报错，如果指定该参数强制变更新表会为空，这是由gh-ost划分chunk的逻辑决定的
        ##如果表中只有唯一键(没有主键)，并且唯一键没有 not null 限制(即使唯一健中没有null值)，那么会报如下错误
        ##FATAL Chosen key (id: [id]; has nullable: true) has nullable columns. Bailing out. To force this operation to continue, supply --allow-nullable-unique-key flag. Only do so if you are certain there are no actual NULL values in this key. As long as there aren't, migration should be fine. NULL values in columns of this key will corrupt migration's data
        ##指定 -allow-nullable-unique-key 参数后会执行变更，但是要注意，你要确认唯一健中确实不存在null 值，否则变更后你的新表为空。因为gh-ost 通过 如下语句确定唯一键的最大值，最小值(如果唯一键中有null值，那么通过如下方法获取到唯一键最小值就是null)
        select /* gh-ost `test_change`.`test_nullable_unique` */ `id`
                                from
                                        `test_change`.`test_nullable_unique`
                                order by
                                        `id` asc
                                limit 1   
                                
      select /* gh-ost `test_change`.`test_nullable_unique` */ `id`
                                from
                                        `test_change`.`test_nullable_unique`
                                order by
                                        `id` desc
                                limit 1
      ##获得唯一键的最大值和最小值后，通过如下语句划分第一个chunk(因为唯一键中有null值，所以起点用的就是null值)，下面的sql可想而知，结果为空。最终导致变更后新表为空
      select  /* gh-ost `test_change`.`test_nullable_unique` iteration:0 */
                                                `id`
                                        from
                                                `test_change`.`test_nullable_unique`
                                        where ((`id` > NULL) or ((`id` = NULL))) and ((`id` < _binary'2000') or ((`id` = _binary'2000')))
                                        order by
                                                `id` asc
                                        limit 1
                                        offset 999;

  -allow-on-master
        allow this migration to run directly on master. Preferably it would run on a replica
        ##允许此迁移直接在master上运行。最好在从库上运行
  -alter string
        alter statement (mandatory)
        ##表结构变更的 alter 语句
  -approve-renamed-columns ALTER
        in case your ALTER statement renames columns, gh-ost will note that and offer its interpretation of the rename. By default gh-ost does not proceed to execute. This flag approves that gh-ost's interpretation is correct
        ##如果工具认为你执行的是列重命名操作，gh-ost将注意这一点并提供其对重命名的解释。默认情况下不会执行重命名操作，直接退出(会自动清理相关表和文件)，除非你指定了该参数(目前已知使用了 change column 并且两个列名不一致就会被工具认为是改名操作)
        FATAL gh-ost believes the ALTER statement renames columns, as follows: map[name_3:name_new]; as precaution, you are asked to confirm gh-ost is correct, and provide with `--approve-renamed-columns`, and we're all happy. Or you can skip renamed columns via `--skip-renamed-columns`, in which case column data may be lost

  -ask-pass
        prompt for MySQL password
  -assume-master-host string
        (optional) explicitly tell gh-ost the identity of the master. Format: some.host.com[:port] This is useful in master-master setups where you wish to pick an explicit master, or in a tungsten-replicator where gh-ost is unable to determine the master
        ##指定主库信息
  -assume-rbr
        set to 'true' when you know for certain your server uses 'ROW' binlog_format. gh-ost is unable to tell, event after reading binlog_format, whether the replication process does indeed use 'ROW', and restarts replication to be certain RBR setting is applied. Such operation requires SUPER privileges which you might not have. Setting this flag avoids restarting replication and you can proceed to use gh-ost without SUPER privileges
        ##只有在主库是RR隔离级别且binlog_format=statement时(因为RC及以上隔离级别binlog_format只能是row格式)，从库binlog_format才可能是 statement，那么这时把从库的binlog_format改成row，然后使用这些row格式的binlog是否安全呢？
  -check-flag
        Check if another flag exists/supported. This allows for cross-version scripting. Exits with 0 when all additional provided flags exist, nonzero otherwise. You must provide (dummy) values for flags that require a value. Example: gh-ost --check-flag --cut-over-lock-timeout-seconds --nice-ratio 0
  -chunk-size int
        amount of rows to handle in each iteration (allowed range: 100-100,000) (default 1000)
      ##每次copy 多少条记录
  -concurrent-rowcount
        (with --exact-rowcount), when true (default): count rows after row-copy begins, concurrently, and adjust row estimate later on; when false: first count rows, then start row copy (default true)
        ##指定该参数为true，则在开始copy数据后，统计源表数据量。为 false的话先统计表的数据量，然后执行copy操作
  -conf string
        Config file
        ##指定配置文件
  -critical-load string
        Comma delimited status-name=threshold, same format as --max-load. When status exceeds threshold, app panics and quits
        ##监控多个状态量用逗号分隔，如果指定多个状态量，只要其中一个达到阈值，工具自动退出(-critical-load="Threads_running=5,Threads_connected=6"),如果工具因为遇到阈值退出，则跟-panic-flag-file参数导致退出一样，会有遗留表 xxx_ghc，xxx_gho还有 socket 文件，管理 cut-over 的文件(可能)，如果你需要执行两次请务必检查指定目录是否存在这些文件，并且清理掉文件和表。
  -critical-load-hibernate-seconds int
        When nonzero, critical-load does not panic and bail out; instead, gh-ost goes into hibernate for the specified duration. It will not read/write anything to from/to any server
        ##当该参数指定为非0值时，达到 critical-load 阈值时不是直接退出，而是进入休眠状态(休眠时间由该参数决定)，休眠期间不读写任何数据(休眠期间会持续读binlog吗？？？)，如果被监控的状态量一直大于阈值，则循环休眠下去(可以通过ctrl+c退出，退出后会遗留表和文件，再次执行前需要先清理相关表及文件)
  -critical-load-interval-millis int
        When 0, migration immediately bails out upon meeting critical-load. When non-zero, a second check is done after given interval, and migration only bails out if 2nd check still meets critical load
        ##当该参数为非0时，达到 critical-load 阈值时不是直接退出，而是等待该参数指定时间后再次检查 critical-load，当第二次检查依然超过阈值时工具退出(如果该参数同-critical-load-hibernate-seconds参数一起使用，则该参数不生效，即第二次检查不满足也不会退出)
  -cut-over string
        choose cut-over type (default|atomic, two-step) (default "atomic")。atomic(默认)类型的cut-over是github的算法，two-step采用的是facebook-OSC的算法
        ##指定表切换的类型，默认为atomic(这时一个线程会建一个临时表这个临时表同xx_del表其实同名，然后同时锁住原表和临时表，另一个线程执行 rename操作，这时rename操作被阻塞，然后前面锁住表的线程发现rename操作在等待metadata lock，然后该线程删除 xxx_del表，并执行 unlock tables; 因为rename操作获得锁的优先级最高，所以rename操作立即被执行，表变更成功)
  -cut-over-exponential-backoff
        Wait exponentially longer intervals between failed cut-over attempts. Wait intervals obey a maximum configurable with 'exponential-backoff-max-interval').
        ##两次失败的切换尝试之间的等待时间间隔成倍增加。等待间隔服从“ exponential-backoff-max-interval”可配置的最大值。
  -cut-over-lock-timeout-seconds int
        Max number of seconds to hold locks on tables while attempting to cut-over (retry attempted when lock exceeds timeout) (default 3)
        ##在 rename 表之前设置会话级别 set session lock_wait_timeout:=10。(在lock 源表和xxx_del表之前会设置会话级别lock_wait_timeout为cut-over-lock-timeout-seconds参数值的两倍)
  -database string
        database name (mandatory)
  -debug
        debug mode (very verbose)
  -default-retries int
        Default number of retries for various operations before panicking (default 60)
        ##各种操作失败后的重试次数
  -discard-foreign-keys
        DANGER! This flag will migrate a table that has foreign keys and will NOT create foreign keys on the ghost table, thus your altered table will have NO foreign keys. This is useful for intentional dropping of foreign keys
        ##危险！此标志将迁移具有外键的表，并且不会在幻影表上创建外键，因此，更改后的表将没有外键。这对于故意删除外键很有用
  -dml-batch-size int
        batch size for DML events to apply in a single transaction (range 1-100) (default 10)
  -exact-rowcount
        actually count table rows as opposed to estimate them (results in more accurate progress estimation)
        ##实际统计表的行数(通过 select count(*) 语句)，而不是估算表的行数，这样能更准确的估算变更进度。不指定的话通过如下方式估计行数(explain select /* gh-ost */ * from `test_change`.`test_1` where 1=1)
  -execute
        actually execute the alter & migrate the table. Default is noop: do some tests and exit
        ##实际执行更改并迁移表。默认为noop：进行一些测试并退出
  -exponential-backoff-max-interval int
        Maximum number of seconds to wait between attempts when performing various operations with exponential backoff. (default 64)
        ##在执行具有指数补偿的各种操作时，两次尝试之间等待的最大秒数
  -force-named-cut-over
        When true, the 'unpostpone|cut-over' interactive command must name the migrated table
  -force-table-names string
        table name prefix to be used on the temporary tables
        ##指定临时表的表名前缀
  -gcp
        set to 'true' when you execute on a 1st generation Google Cloud Platform (GCP).
  -heartbeat-interval-millis int
        how frequently would gh-ost inject a heartbeat value (default 100)
        ##gh-ost多久往心跳表中注入一次心跳值，默认值为100毫秒(insert /* gh-ost */ into `test_change`.`_test_2_ghc` (id, hint, value)
                        values (NULLIF(1, 0), 'heartbeat', '2020-07-30T15:58:02.262896446+08:00')
                        on duplicate key update
                                last_update=NOW(),
                                value=VALUES(value))
  -help
        Display usage
  -hooks-hint string
        arbitrary message to be injected to hooks via GH_OST_HOOKS_HINT, for your convenience
  -hooks-hint-owner string
        arbitrary name of owner to be injected to hooks via GH_OST_HOOKS_HINT_OWNER, for your convenience
  -hooks-hint-token string
        arbitrary token to be injected to hooks via GH_OST_HOOKS_HINT_TOKEN, for your convenience
  -hooks-path string
        directory where hook files are found (default: empty, ie. hooks disabled). Hook files found on this path, and conforming to hook naming conventions will be executed
  -host string
        MySQL hostname (preferably a replica, not the master) (default "127.0.0.1")
        ##MySQL主机名（最好指定从库，而不是主库）（默认为“ 127.0.0.1”）
  -initially-drop-ghost-table
        Drop a possibly existing Ghost table (remains from a previous run?) before beginning operation. Default is to panic and abort if such table exists
        ##在开始之前先删除已经存在的ghost 表(可能是上次 gh-ost 操作遗留的)，如果不指定该参数，发现ghost表已存在，则终止变更操作
        FATAL Table `_test_big_gho` already exists. Panicking. Use --initially-drop-ghost-table to force dropping it, though I really prefer that you drop it or rename it away
  -initially-drop-old-table
        Drop a possibly existing OLD table (remains from a previous run?) before beginning operation. Default is to panic and abort if such table exists
        ##同上在开始变更之前先删除 OLD 表(可能是上次 gh-ost 操作遗留的)，否则发现该表存在，则终止变更操作
  -initially-drop-socket-file
        Should gh-ost forcibly delete an existing socket file. Be careful: this might drop the socket file of a running migration!
        ##gh-ost是否应强制删除现有的套接字文件。注意：这可能会删除正在运行的迁移的套接字文件！
  -master-password string
        MySQL password on master, if different from that on replica. Requires --assume-master-host
        ##连接主库的MySQL密码（如果主库与从库上的密码不同，或者使用不同用户连接）。需要--assume-master-host
  -master-user string
        MySQL user on master, if different from that on replica. Requires --assume-master-host
        ##连接主库的用户（如果通过不同用户连接主从）。需要--assume-master-host
  -max-lag-millis int
        replication lag at which to throttle operation (default 1500)
        ##指定复制延迟达到多少毫秒后，暂停变更操作(默认值为1500毫秒)
  -max-load string
        Comma delimited status-name=threshold. e.g: 'Threads_running=100,Threads_connected=500'. When status exceeds threshold, app throttles writes
        ##指定 max-load 状态变量阈值，如果指定多个状态变量，用逗号分隔。如:(Threads_running=100,Threads_connected=500)，当状态变量超过该阈值，暂停变更操作
  -migrate-on-replica
        Have the migration run on a replica, not on the master. This will do the full migration on the replica including cut-over (as opposed to --test-on-replica)
        ##在从库上进行完整变更操作，包括切换，而不在主数据库上运行。
        FATAL --allow-on-master and --migrate-on-replica are mutually exclusive
        FATAL Instructed to --test-on-replica or --migrate-on-replica, but the server we connect to doesn't seem to be a replica
        ##指定该参数和test-on-replica参数时，--user="root" --password="rootxxx" --host=10.1.30.53 必须指定从库
  -nice-ratio float
        force being 'nice', imply sleep time per chunk time; range: [0.0..100.0]. Example values: 0 is aggressive. 1: for every 1ms spent copying rows, sleep additional 1ms (effectively doubling runtime); 0.7: for every 10ms spend in a rowcopy chunk, spend 7ms sleeping immediately after
        ##指定每copy一个chunk后休眠时间，指定0的话，不休眠。如果指定1，copy row每花费一秒则需要额外的休眠一秒(简单的说就是copy row花费多长时间就休眠多长时间)。如果指定0.7，表示copy row 每花费一秒则需要额外的休眠0.7s(比如说copy row花费了10s，那么copy完成后需要休眠7s)
  -ok-to-drop-table
        Shall the tool drop the old table at end of operation. DROPping tables can be a long locking operation, which is why I'm not doing it by default. I'm an online tool, yes?
        ##指定在变更完成后是否删除旧表，不建议指定该参数(变更完成立即删除有可能导致 opening tables等待)
  -panic-flag-file string
        when this file is created, gh-ost will immediately terminate, without cleanup
        ##发现此文件被创建，gh-ost将立即终止，且不做任何清理工作。注意终止 gh-ost 操作会有遗留表 xxx_ghc，xxx_gho还有 socket 文件，管理 cut-over 的文件(可能)，如果你需要执行两次请务必检查指定目录是否存在这些文件，并且清理掉文件和表。
        FATAL Found panic-file /root/shao/panic.gh. Aborting without cleanup
  -password string
        MySQL password
        ##连接mysql实例的密码
  -port int
        MySQL port (preferably a replica, not the master) (default 3306)
        ##连接mysql 的端口
  -postpone-cut-over-flag-file string
        while this file exists, migration will postpone the final stage of swapping tables, and will keep on syncing the ghost table. Cut-over/swapping would be ready to perform the moment the file is deleted.
        ##当该参数指定的文件存在时，cut-over 操作会被推迟(正常同步ghost 表的数据)，直到该文件被删除。我们可以通过指定该参数来控制 cut-over操作在一个合适的时间点进行
        Copy: 4999999/4999999 100.0%; Applied: 0; Backlog: 0/1000; Time: 59s(total), 49s(copy); streamer: 3306-bin.000024:447090122; State: postponing cut-over; ETA: due
  -quiet
        quiet
  -replica-server-id uint
        server id used by gh-ost process. Default: 99999 (default 99999)
  -replication-lag-query string
        Deprecated. gh-ost uses an internal, subsecond resolution query
  -serve-socket-file string
        Unix socket file to serve on. Default: auto-determined and advertised upon startup
        ##指定gh-ost 使用的 socket 文件
  -serve-tcp-port int
        TCP port to serve on. Default: disabled
        ##指定 gh-ost 监听的端口
  -skip-foreign-key-checks
        set to 'true' when you know for certain there are no foreign keys on your table, and wish to skip the time it takes for gh-ost to verify that
        ##当您确定您的表上没有外键并且希望跳过gh-ost验证所花费的时间时，将其设置为“ true”
  -skip-renamed-columns ALTER
        in case your ALTER statement renames columns, gh-ost will note that and offer its interpretation of the rename. By default gh-ost does not proceed to execute. This flag tells gh-ost to skip the renamed columns, i.e. to treat what gh-ost thinks are renamed columns as unrelated columns. NOTE: you may lose column data
        ##gh-ost对于认为是重命名列的操作，默认不会执行。如果指定该参数，则会继续执行。但是注意指定该参数可能会导致重命名后列中数据丢失或者错误(因为插入数据的时候不会插入改名的那一列)，居然是这样那为什么说可能会导致数据丢失或者错误呢？有这样一种情况。如果建表时该列就指定了某默认值(xxx)，之后该列中数据都是默认值，我们给列改名时也给列指定了之前相同的默认值(xxx)，那这时新列中数据就是没有问题的
  -ssl
        Enable SSL encrypted connections to MySQL hosts
  -ssl-allow-insecure
        Skips verification of MySQL hosts' certificate chain and host name. Requires --ssl
  -ssl-ca string
        CA certificate in PEM format for TLS connections to MySQL hosts. Requires --ssl
  -stack
        add stack trace upon error
  -switch-to-rbr
        let this tool automatically switch binary log format to 'ROW' on the replica, if needed. The format will NOT be switched back. I'm too scared to do that, and wish to protect you if you happen to execute another migration while this one is running
        ##如果指定该参数，在需要时该工具会自动把从库的binlog格式改为row模式，并且改完后不会改回来。
  -table string
        table name (mandatory)
        ##指定需要进行变更的表名
  -test-on-replica
        Have the migration run on a replica, not on the master. At the end of migration replication is stopped, and tables are swapped and immediately swap-revert. Replication remains stopped and you can compare the two tables for building trust
        ##在从库上进行变更操作，而不是在主库上进行变更操作。变更结束时，停止复制线程，表被cut-over并立即还原(最后从库上会保留有xxx_gho表，在进行主库变更前，要先删除从库的xxx_gho表，否则变更过程中复制线程会出现问题)。复制仍然停止，你可以比较两个表确认变更效果
        ##FATAL Replication on 10.1.30.50:3306 is broken: Slave_IO_Running: No, Slave_SQL_Running: No. Please make sure replication runs before using gh-ost
        ##在变更前，如果从库复制线程已经停止，则工具报错
  -test-on-replica-skip-replica-stop
        When --test-on-replica is enabled, do not issue commands stop replication (requires --test-on-replica)
        ##指定 -test-on-replica 参数时，如果同时指定该参数，则在表切换的时候不会先停止复制线程
  -throttle-additional-flag-file string
        operation pauses when this file exists; hint: keep default, use for throttling multiple gh-ost operations (default "/tmp/gh-ost.throttle")
        ##该文件存在时，操作会暂停；提示：保留默认值，用于限制多个gh-ost操作
  -throttle-control-replicas string
        List of replicas on which to check for lag; comma delimited. Example: myhost1.com:3306,myhost2.com,myhost3.com:3307
        ##列出需要监控延迟的从库，每秒(目前该频率无法调整)查询从库的xxx_ghc表心跳值(select value from `test_change`.`_test_2_ghc` where hint = 'heartbeat' and id <= 255)(不同于pt工具无法自动发现从库，所有从库都需要手动指定，逗号分隔)
  -throttle-flag-file string
        operation pauses when this file exists; hint: use a file that is specific to the table being altered
        ##该文件存在时，操作会暂停;(用于暂停某个单独的表变更操作，throttle-additional-flag-file用户控制当前服务器上所有的gh-ost变更)
        Copy: 1412000/4999999 28.2%; Applied: 0; Backlog: 0/1000; Time: 21s(total), 21s(copy); streamer: 3306-bin.000024:538746298; State: throttled, flag-file; ETA: 53s
  -throttle-http string
        when given, gh-ost checks given URL via HEAD request; any response code other than 200 (OK) causes throttling; make sure it has low latency response
  -throttle-query string
        when given, issued (every second) to check if operation should throttle. Expecting to return zero for no-throttle, >0 for throttle. Query is issued on the migrated server. Make sure this query is lightweight
        ##在进行变更的服务器上执行该查询，如果返回值大于0则进行 throttle，否则继续变更。注意该查询要是轻量级的不要对实例性能产生影响
  -timestamp-old-table
        Use a timestamp in old table name. This makes old table names unique and non conflicting cross migrations
        ##在旧表名称中使用时间戳。这使得旧表名在多次变更中是唯一的没有冲突
  -tungsten
        explicitly let gh-ost know that you are running on a tungsten-replication based topology (you are likely to also provide --assume-master-host)
  -user string
        MySQL user
        ##连接mysql实例的用户名
  -verbose
        verbose
  -version
        Print version & exit
        ##版本信息