binlogctl

Binlog Control (binlogctl for short) is a command line tool for TiDB Binlog. You can use binlogctl to manage TiDB Binlog clusters.

You can use binlogctl to:

  • Check the state of Pump or Drainer
  • Pause or close Pump or Drainer
  • Handle the abnormal state of Pump or Drainer

The following are its usage scenarios:

  • An error occurs during data replication or you need to check the running state of Pump or Drainer.
  • You need to pause or close Pump or Drainer when maintaining the cluster.
  • A Pump or Drainer process exits abnormally, while the node state is not updated or is unexpected. This affects the data replication task.

Download binlogctl

binlogctl is included in the TiDB Toolkit. To download the TiDB Toolkit, see Download TiDB Tools.

Descriptions

Command line parameters:

  1. Usage of binlogctl:
  2.   -V    prints version and exit
  3.   -cmd string
  4.         operator: "generate_meta", "pumps", "drainers", "update-pump", "update-drainer", "pause-pump", "pause-drainer", "offline-pump", "offline-drainer", "encrypt" (default "pumps")
  5.   -data-dir string
  6.         meta directory path (default "binlog_position")
  7.   -node-id string
  8.         id of node, used to update some nodes with operations update-pump, update-drainer, pause-pump, pause-drainer, offline-pump and offline-drainer
  9.   -pd-urls string
  10.         a comma separated list of PD endpoints (default "http://127.0.0.1:2379")
  11.   -show-offline-nodes
  12.         include offline nodes when querying pumps/drainers
  13.   -ssl-ca string
  14.         Path of file that contains list of trusted SSL CAs for connection with cluster components.
  15.   -ssl-cert string
  16.         Path of file that contains X509 certificate in PEM format for connection with cluster components.
  17.   -ssl-key string
  18.         Path of file that contains X509 key in PEM format for connection with cluster components.
  19.   -state string
  20.         set node's state, can be set to online, pausing, paused, closing or offline.
  21.   -text string
  22.         text to be encrypted when using encrypt command
  23.   -time-zone Asia/Shanghai
  24.         set time zone if you want to save time info in savepoint file; for example, Asia/Shanghai for CST time, `Local` for local time

Command examples:

  • Check the state of all the Pump or Drainer nodes.

    Set cmd to pumps or drainers. For example:

    1. bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pumps
    1. [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=pump] [node="{NodeID: 1.1.1.1:8250, Addr: pump:8250, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"]
    1. bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd drainers
    1. [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=drainer] [node="{NodeID: 1.1.1.1:8249, Addr: 1.1.1.1:8249, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"]

  • Pause or close Pump or Drainer.

    You can use the following commands to pause or close services:

    CommandDescriptionExample
    pause-pumpPause Pumpbin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-pump -node-id ip-127-0-0-1:8250
    pause-drainerPause Drainerbin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-drainer -node-id ip-127-0-0-1:8249
    offline-pumpClose Pumpbin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-pump -node-id ip-127-0-0-1:8250
    offline-drainerClose Drainerbin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-drainer -node-id ip-127-0-0-1:8249

    binlogctl sends the HTTP request to the Pump or Drainer node. After receiving the request, the node executes the exiting procedures accordingly.

  • Modify the state of a Pump or Drainer node in abnormal states.

    When a Pump or Drainer node runs normally or when it is paused or closed in the normal process, it is in the normal state. In abnormal states, the Pump or Drainer node cannot correctly maintain its state. This affects data replication tasks. In this case, use binlogctl to repair the state information.

    To update the state of a Pump or Drainer node, set cmd to update-pump or update-drainer. The state can be paused or offline. For example:

    1. bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd update-pump -node-id ip-127-0-0-1:8250 -state paused

    binlogctl - 图1

    Note

    When a Pump or Drainer node runs normally, it regularly updates its state to PD. The above command directly modifies the Pump or Drainer state saved in PD; therefore, do not use the command when the Pump or Drainer node runs normally. For more information, refer to TiDB Binlog FAQ.