第252回　MySQL Shellのバイナリログダンプ・ロード機能

MySQLのバイナリログ（binlog）はデータの変更履歴を記録したログファイルで、主にレプリケーションやデータリカバリに用いられます。

バイナリログを扱うために古くからあるのがmysqlbinlogコマンドです。mysqlbinlogを使うことで、バイナリログをテキスト化して確認したり、指定範囲のイベントを抽出して再適用することができます。

そしてMySQL Shell 9.2では、mysqlbinlogに代わる新しい機能であるBinary Log Dumping and Loading Utilitiesが追加されました。

本稿ではBinary Log Dumping and Loading Utilitiesを構成する要素と、その使い方について紹介します。バージョンはMySQL Shell 9.4を使用します。

Binary Log Dumping and Loading Utilities

Binary Log Dumping and Loading Utilitiesは、util.dumpBinlogsとutil.loadBinlogsの2つから構成され、バイナリログをダンプ（エクスポート）し、後からまとめて適用（インポート）するための新しい機能です。

既存のmysqlbinlogと目的は近いものの、

バイナリログの並列ダンプ
ダンプの圧縮
クラウドストレージ対応

といった特徴を持っています。

`util.dumpBinlogs`

util.dumpBinlogsは、オプションで指定した時点以降のバイナリログをダンプします。

開始点は、以前のダンプのスナップショットから自動決定するか、startFromオプションで明示できます。ダンプはマルチスレッドで実行でき、圧縮とクラウドストレージに対応します。

ダンプには以下の条件が必要です。

対象サーバのバイナリログが有効である
対象サーバのgtid_modeがOFF/OFF_PERMISSIVE以外である
MySQL Shellの実行アカウントがSUPERまたはREPLICATION CLIENT権限を持っている

主なオプション

util.dumpBinlogsの主なオプションを紹介します。sinceとstartFromはどちらかが必須です。

since
- util.dumpInstanceまたはutil.dumpBinlogsの出力パスまたはURLを指定します
- 指定した出力を起点に続きからダンプが行われます
- startFromと併用不可
startFrom
- binary-log-file:binary-log-file-positionの形式で、ダンプ開始ファイル／位置を指定します
- sinceと併用不可
threads
- ダンプの並列数
- default: 4
compression
- ダンプの圧縮形式及びその圧縮レベル
- none（非圧縮⁠）⁠、gzip,zstdを指定できます
- default: zstd;level=1
dryRun
- 実際にダンプはせず、どのように行われるかのみを表示します
- default: false
showProgress
- ダンプの進捗を表示します
- default: true

util.dumpBinlogsはOracle Cloud Infrastructure（OCI）Object Storage、S3、Azure Blobといったオブジェクトストレージへのダンプもサポートしています。各クラウドサービス用オプションにアップロード先の情報をわたすことで利用が可能です。

コマンドサンプル

CLIでの実行形式は以下になります。

mysqlsh <user>@<dump-source-hostname>:<port> -- util dump-binlogs [<dump-dir-path> or <dump-url>]

たとえば、binlog.000014の先頭を開始点としてresultディレクトリに出力する場合は、以下のように実行します。

$ mysqlsh takusaek@127.0.0.1:3306 -- util dump-binlogs ./results --startFrom="binlog.000014"

Starting from binary log file: binlog.000014:0
Will finish at binary log file: binlog.000015:11518
Dumping 2 binlogs (25.88 KB of data) using 4 threads
100% (25.88 KB / 25.88 KB), 0.00 B/s, 0.00 B/s compressed, 2 / 2 binlogs done
Dump was written to: /home/ubuntu/results/2025-08-12-05-34-10
Total duration: 00:00:00s
Binlogs dumped: 2
GTID set dumped: aa92c42e-770f-11f0-940f-525400fc48e5:1-13
Uncompressed data size: 25.88 KB
Compressed data size: 3.76 KB
Compression ratio: 6.9
Events written: 62
Bytes written: 3.76 KB
Average uncompressed throughput: 25.88 KB/s
Average compressed throughput: 3.76 KB/s

`util.loadBinlogs`

util.loadBinlogsはutil.dumpBinlogsによって生成済みのダンプをインポートします。ローカルまたはクラウドからダンプを読み込み、ダンプ内のスナップショット情報を起点にインポートを進めます。オプションによって、特定GTIDまでインポートするといった制御も可能です。

インポートには以下の条件が必要です。

入力ディレクトリ（またはURL）はutil.dumpBinlogsが作ったダンプである
ダンプが完了している
スナップショットが連続である（GTIDが途中で欠けていない）
ターゲットのgtid_executedが、インポート対象ダンプの先頭バイナリログのgtid_executedを完全に含む（余分なトランザクションが含まれていてもOK。不一致でもignoreGtidGapで強行実行することは可能）
MySQL Shellの実行アカウントが以下権限を持っている
- SUPERまたはREPLICATION CLIENT権限
- SUPER、SYSTEM_VARIABLES_ADMIN、SESSION_VARIABLES_ADMIN、REPLICATION_APPLIERのいずれかの権限

主なオプション

ignoreVersion
- ダンプのソースとターゲットのバージョン非互換を無視してインポートします
- default: false
ignoreGtidGap
- ターゲットのgtid_executedがインポート対象ダンプの先頭バイナリログの先頭GTIDを含まなくても、インポートを実行します
- default: false
stopBefore
- 指定したGTIDの手前でインポートを停止します
- 書式はUUID[:tag]:transaction-id
stopAfter
- 指定したGTIDの直後でインポートを停止します
- 書式はUUID[:tag]:transaction-id
dryRun
- 実際にインポートはせずどのように行われるかのみを表示します
- default: false
showProgress
- インポートの進捗を表示します
- default: true

クラウドからインポートする場合、オプションにアップロード先の情報を指定する必要があります。

コマンドサンプル

CLIでの実行形式は以下になります。

mysqlsh <user>@<import-target-hostname>:<port> -- util load-binlogs [<dump-dir-path> or <dump-url>]

たとえば、resultディレクトリからインポートする場合は以下のように実行します。

$ mysqlsh takusaek@127.0.0.1:3307 -- util load-binlogs ./results

Opening dump '/home/ubuntu/results'
Loading 2 binlogs, 25.88 KB of data
  Loading dump '2025-08-12-05-34-10' created at 2025-08-12 05:34:10 UTC
    Loading binary log file 'binlog.000014', GTID set: aa92c42e-770f-11f0-940f-525400fc48e5:1-12 (14.36 KB)
      Found starting GTID: aa92c42e-770f-11f0-940f-525400fc48e5:1
    Loading binary log file 'binlog.000015', GTID set: aa92c42e-770f-11f0-940f-525400fc48e5:13 (11.52 KB)
100% (25.88 KB / 25.88 KB), 0.00 B/s, 0.00 B/s compressed, 0.00 stmts/s, 2 / 2 binlogs done
Total duration: 00:00:00s
Binlogs loaded: 2
Uncompressed data size: 25.88 KB
Compressed data size: 3.76 KB
Statements executed: 128
Average uncompressed throughput: 25.88 KB/s
Average compressed throughput: 3.76 KB/s
Average statement throughput: 128.00 B/s

まとめ

本稿では、バイナリログを扱うための新機能Binary Log Dumping and Loading Utilitiesを構成するutil.dumpBinlogs、util.loadBinlogsについて紹介しました。これまで使われてきたmysqlbinlogと比較して、各種クラウドサービスのサポートや並列・圧縮ダンプといった運用上の強みがあります。

一方で、適切な権限を持ったMySQLアカウントの用意が必須であったり、ダンプ対象のフィルタリングがバイナリログ名とポジションによる開始地点しか指定できなかったりと、完全に代替できるものではなさそうです。現時点では要件に応じた使い分けが必要となるでしょう。

Binary Log Dumping and Loading Utilitiesの詳細については公式ドキュメントをご覧ください。