MENU
データベース＆クラウド技術情報
  1. ホーム
  2. 技術情報
  3. MySQL
  4. MySQL HeatWave
  5. MySQL HeatWave Migration Assistant を使ってMySQLをOCIにリフトアップ！ツールの紹介と注意点について

MySQL HeatWave Migration Assistant を使ってMySQLをOCIにリフトアップ！ツールの紹介と注意点について

技術情報 MySQL MySQL HeatWave
目次

はじめに

皆さん、2025/11/25 に公開された MySQL HeatWave Migration Assistant(以降、Migration Assistant) をご存知でしょうか。

MySQL HeatWave Migration Assistant

https://dev.mysql.com/doc/workbench/en/heatwave-migration-assistant.html

本ツールを使用すると、オンプレミス環境の MySQL を Oracle Cloud Infrastructure (以降、OCI) の MySQL HeatWave DB システム（以降、MDS）に簡単に移行することができます。

今回は実際に本ツールを検証し、前半は使い方、後半は筆者がハマってしまった注意点やエラーを対処方法とともに記載しておきますので、ぜひ皆様の参考になれば幸いです。

MySQL HeatWave Migration Assistantとは

MySQL Workbench 8.0.45 で追加された新機能で、無料でオンプレ環境のMySQLをOCI上のMDSへ移行するツールです。ただし、サポートOSはMicrosoft Windows および macOS のみです。

また、移行元DBとして MySQL 5.6, 5.7, 8.0, 8.4 LTS, 9.x (Perconaを含む)をサポートしています。

本ツールは、ボタンをクリックしていくだけでOCIへリフトアップできるというもので、以下のGOODなポイントがあります。

  • 無料で使える
  • 移行で必要となるOCI上のオブジェクト（VCN/コンピュートインスタンス/MDS/オブジェクトストレージ）を自動生成してくれる
  • マイグレーション完了後、生成した不要なOCIオブジェクトの自動削除もできる
  • GUI画面で操作が完結し、マイグレーションの進行状況が確認できる

検証環境

前提条件

検証の前提条件は以下の通りです。

  • Windows OSにMySQL Workbench 8.0.45がインストール済みである
  • オンプレミス環境の MySQL Server があり、MySQL Workbenchからアクセスできること
  • OCI CLI がWinodws OS上で使用できること

検証環境

今回検証に使用した環境は以下の通りです

  • OS：Windows 11
  • MySQL Workbench：8.0.45
  • 移行元DB：MySQL8.0.33

Migration Assistantを使用してマイグレーションを行うと、構成図は以下のようになります。
右側のOCIのオブジェクト（コンピュートインスタンス/ MDS /オブジェクトストレージ）についてはツール内で自動作成されます。

Migration Assistantでのマイグレーションに必要な要件

Migration Assistant を使用してマイグレーションする際に必要な要件は以下の通りです。

  • 移行元のMySQLバージョンは MySQL 5.6 以降（5.6/5.7/8.0/8.4/9.x） であること

    • ドキュメントに記載はありませんが、MySQL 5.6/5.7では以下のパッチバージョンでないとマイグレーション処理の途中でエラーが発生し動作しません。
      • MySQL 5.6 ： MySQL 5.6.42以降
      • MySQL 5.7 ： EE版であれば5.7.10以降、CE版だと5.7.28以降

  • 使用するOCIアカウントが管理者アカウントでない場合、以下の権限を設定しておく必要があります。
    詳細は公式ドキュメントをご確認ください。

マイグレーションの流れ

Migration Assistant による大まかな移行の流れです。

  1. マイグレーションの事前設定
  2. OCI上に 踏み台サーバ（コンピュートインスタンス）、移行先MDSを自動生成
  3. 踏み台サーバからソース元DBのスナップショットを取得し、OCI 上のオブジェクトストレージへアップロード
  4. 移行先 MDS へスナップショットをインポート
  5. （ホットマイグレーションを選択した場合）インバウンドレプリケーションによるスナップショット取得以降の更新データの同期

最初の手順である「マイグレーションの事前設定」を行うだけで、以降の処理は自動で行われます。ここからは実際の画面を使った移行手順をご紹介します。

1. Migration Assistantの起動

MySQL Workbenchのホーム画面の MySQL Connections セクションより、移行したいDBの connection の緑ボタンをクリックします。（画像の赤枠部分をクリック）

そもそも connection がない場合、MySQL Connectionsセクション横の＋ボタンをクリックして、 DB接続 を作成してください。

2.Target Selection の設定

移行先のMDSや踏み台サーバを作成するコンパートメントやVCNを選択します。

このタイミングで新規にコンパートメントやVCNを作成することもできますが、ここでは既存のVCNを選択します。

続いて、移行先MDSの設定として以下の項目を入力します。

  • Configuration Template

    • 踏み台サーバのコンピュートインスタンス、MDSの構成テンプレート（ECPU / メモリー/NW）を選択します。踏み台サーバとMDSは同じスペックになります。
    • Always Freeも選択できますが、移行元DBのバージョンによっては後述するエラーに注意が必要です。

  • Data Size

    • MDSのストレージサイズ

  • Setup Type

    • スタンドアロン もしくは 高可用性構成（HA）を選択

  • HeatWave Shape / HeatWave Nodes

    • Heatwaveクラスターの構成やクラスターノード数

  • Display Name

    • MDSのインスタンス名

  • MySQL Admin Username / Password / Confirm Password

    • MDSの管理者ユーザー名、パスワード（デフォルトはMySQL WorkbenchのDB接続で設定したユーザ名とパスワード）

  • Contact Emails (任意)

    • 作成するMDSに関する管理メールを受信するメールアドレス（空欄でよいと思います）

Nextボタンをクリックし次に進みます。

3.Migration Type の設定

マイグレーション方式を以下の2つから選択します。

  • コールドマイグレーション
    • 移行元DBのスナップショットを取得し、MDSへインポートする方法です。
    • 移行中に移行元DBに加えられたデータ更新はMDSには反映されないため、移行中はアプリケーションの書き込みを停止する必要があります。
    • MySQL 5.6/5.7はこちらのみ選択可能です。
  • ホットマイグレーション
    • 移行元DBのスナップショットを取得しMDSへインポート、その後移行中に更新されたデータをインバウンドレプリケーションによりデータ同期を行う方法です。
    • レプリケーションチャネルを自動作成しインバウンドレプリケーションを設定するため、VCNから移行元DBホストのポート3306に接続できるようにしておく必要があります。

移行元DBのスナップショットのエクスポート / MDSへのインポート は、内部的にMySQL Shellのダンプユーティリティを使用しますが並列度(threads)などのパラメータ調整はできません。

ここではコールドマイグレーションを選択し、Nextボタンをクリックし次に進みます。

4. Schema Compability Checks の設定

MDSにはいくつかの制限があり、移行データの互換性をチェックします。

互換性がない移行データについてはMySQL Shellのダンプユーティリティのオプションを指定してデータ移行を行います。

下記画像では、MDSではユーザに設定できる権限に制限があり、root権限をもつユーザを「strip_restricted_grantsオプションで移行する（特定の権限を除外して移行）」　か 「Exclude Object（移行対象から除外）とする」か選択します。

設定ができたら、Nextボタンをクリックし次に進みます。

5. Preview Migration Plan の確認

これまで選択したマイグレーションの設定が表示されるので、Start Migration Processボタンをクリックすると自動でマイグレーションが開始されます。

以降はマイグレーションが完了するまで、表示されるプログレスバーで進捗状況を見守ることになります。

6. マイグレーション完了

無事マイグレーションが完了すると、Congratulations!と表示されます。

OCI上の踏み台サーバやMDSに接続するためのコマンドが表示されるので、Windows OS / macOS 上から踏み台サーバ経由でMDSに接続したい場合などはコピーして控えておくと良いです。

また、ページ下部にマイグレーションで自動作成された踏み台サーバやオブジェクトストレージを削除するかどうか、チェックボックスで選択することができます。
不要なオブジェクトがある場合は、チェックを入れて「Delete Selected OCI Resources」ボックスをクリックしてください。

Migration Assistantを使ったマイグレーション手順は以上です。

事前設定するだけで、非常に簡単にOCIのMDSへ移行することができました。

ツール使用時の注意点

ここからは筆者がツール検証時に実際に遭遇したエラーや注意点を記載します。

1. 似たような機能である Migration Wizardと勘違いしない

左側のメニューバーの Migration Wizard機能（ODBC 準拠の他ベンダデータベースを MySQL に移行する機能）のボタンがありますが、まったく別機能なので注意しましょう。

この機能を使ったことがないと、Migration ~ と書いてあるので勘違いしそうになります。

2. 移行先MDSのバージョンは選択できない

Migration Assistantを使ったマイグレーションでは、移行先MDSのバージョンは自動的に「移行元DBのメジャーバージョンの最新版」となるため、バージョン指定はできないので注意です。

それぞれの移行先バージョンは以下の通りとなります。(2026/1/26現時点)

移行元 DB バージョン 移行先 MDS バージョン
MySQL 5.6/5.7/8.0 MySQL 8.0.45
MySQL 8.4 LTS MySQL 8.4.8
MySQL 9.x MySQL 9.6

※OCIではMySQL 5.6/5.7はサポート外のため、最もバージョンが近い8.0系の最新版が移行先バージョンとなるようです。

ちなみに、オンプレミス環境がMySQL8.0以下の方で「8.0がEOL間近なので、移行先MDSには8.4を選択したい！」という方もいらっしゃるかと思います。

そのような場合、Migration Assistantを使ったマイグレーション後のアップグレードパスは以下のようになるかと思います。（MySQL 5.7.28 からのマイグレーションで試してみましたが問題なく実行できました。ご参考までに）

  1. MigrationAssistant で MySQL 8.0.45 にマイグレーションする
  2. OCIのコンソール画面からMySQL 8.4.x へ手動アップグレード（もしくは自動アップグレード）

MDSのアップグレードの詳細については、公式ドキュメントをご参照ください。

3. エラーメッセージから原因が分かりづらい

エラーが発生した場合、ツール画面上に出てくるメッセージだけでは正直何が原因でエラーが発生したのかがわからないことが多いです。

Migration Assistantでは内部的にMySQL Shellが使用されており、エラー発生時は以下のログを確認し、エラーメッセージから原因を確認することを推奨します。

Windows の場合、ログファイルは以下のパスにあります。

  • フォルダ
    • C:\Users\ユーザ\AppData\Roaming\MySQL\mysqlsh-wb\
  • ログ
    • mysqlsh.log

ちなみにですが、本ログには移行元DBへのバックアップ取得中のログも出力されるため、ログ時刻からバックアップ実行時間を確認することができます。

4. OCI CLIに設定ミスがあると、起動しても真っ白な画面になる

OCI CLIの設定や構成ファイルに設定ミスがあると、Migration Assistant を起動しても真っ白な画面のウィンドウが立ち上がります。

待てど暮らせど画面にエラーメッセージが出るわけでないので困惑します。

そこで、ログ(mysqlsh.log)を確認すると以下のようなエラーメッセージ(Error: Loaded OCI profile didn’t work:)が発生しています。

このような場合は、OCI CLIの設定や構成ファイルに何らかの設定ミスがあるので、ドキュメントを参照し設定を見直してください。

ちなみに、私の場合は「作成したAPIキーの公開鍵をOCIにアップロードし忘れていた」という超凡ミスが原因でした。

How to Upload the Public Key

5. MySQL 8.4以下は、移行先にAlways Freeを選ぶとエラーが発生

OCIのAlways Freeでは、MySQLバージョンは常に最新版のバージョン(2026年1月26日時点ではMySQL 9.6)のみが使用可能です。公式ドキュメントにも以下の記載があります。

Always Free DBシステムには、次の構成および制限があります。

  • DBシステムは常に最新バージョンで作成されます。

https://docs.oracle.com/ja-jp/iaas/mysql-database/doc/features-mysql-heatwave-service.html#MYAAS-GUID-772BD870-57C1-4B21-9205-FFC5B4290044

前述しましたが Migration Assistant では、移行先MDSバージョンは自動的に「移行元のメジャーバージョンの最新版」となるため、MySQL 5.6/5.7./8.0では 最新版の8.0.45となり、MySQL8.4では 8.4.8 となります。

そのため、Always Freeが要求するMySQLバージョンと Migration Assistantが使用するMySQLバージョンで食い違いが発生します。

よって「移行元DBがMySQL 8.4以下」かつ「移行先のテンプレートにAlways Free 」を選択してしまうと、内部的にMySQLバージョン差異によりエラーとなります。
（以下の画面は、移行元DBとしてMySQL 8.0.33、移行先にAlways Freeを選択した場合のエラー）

このような場合、以下の手順でマイグレーションをやり直す必要があります。

  1. ×ボタンでMigration Assistantのウィンドウを閉じる

  2. 手作業でそれまで作成されたOCIオブジェクト（踏み台サーバ/オブジェクトストレージ）を削除する

  3. Always Free以外のテンプレートを選択して再度マイグレーションする

ちなみにですが、踏み台サーバは「mysql-jump-host」というインスタンス名で自動作成されます。

6. MySQL 5.6/5.7 はパッチバージョンに注意しないとエラーが発生する

ドキュメントに記載はありませんが、MySQL 5.6/5.7では以下のパッチバージョンでないと動作しません。

  • MySQL 5.6 ： MySQL 5.6.42以降
  • MySQL 5.7 ： EE版であれば5.7.10以降、CE版だと5.7.28以降

これは、Migration Assistantでは内部的にMySQL Shellからの接続時にTLS接続が必須であることが原因です。
Migration Assistantでは内部的に移行元DBに対して以下のようなTLS接続が行われます。

MySQL8.0.28ではTLS1.0および1.1のサポートが削除されているため、以降のバージョンではこれらを使ったTLS接続ができず、MySQL Shellも同様です。以下、公式ドキュメントの引用です。

Support for the TLSv1 and TLSv1.1 connection protocols is removed from MySQL Server as of release 8.0.28.

(機械翻訳：TLSv1およびTLSv1.1接続プロトコルのサポートは、MySQL Server 8.0.28リリース以降で削除されました。）

そのため、移行元DBではTLS1.2をサポートしている必要があります。
MySQL 5.6/5.7 の前述したバージョンはTLS1.2をサポートしているため、これらのバージョンだとMigration Assistant機能が利用できるということです。
こちらに関してはドキュメントに以下のように記載があります。

MySQL supports encrypted connections using the TLSv1 protocol and (as of MySQL 5.6.46) TLSv1.1 and TLSv1.2, listed in order from less secure to more secure.
(機械翻訳：MySQLはTLSv1プロトコルを使用した暗号化接続をサポートしており、（MySQL 5.6.46以降）TLSv1.1およびTLSv1.2もサポートしています。)

TLS1.2をサポートしていないバージョンの場合（MySQL 5.6.41以下など）、マイグレーションを実行するとTLS接続に失敗し、下記画像のようにスナップショットのエクスポート / インポート処理でエラーが発生します。

ログ上では以下の「SSL routines::unsupported protocol」エラーが発生することが確認できます。
（以下、MySQL 5.6.10 でのエラーケース）

このような場合、移行元DBをTLS1.2が使用できるバージョンにアップグレードしてからでないと Migration Assistant が使用できないので注意が必要です。

マイグレーション実行中にエラーが発生したときの対応

マイグレーション実行中にエラーが発生した場合、画面上のエラーメッセージやC:\Users\ユーザ\AppData\Roaming\MySQL\mysqlsh-wb配下のログを確認し、エラー原因を事前に取り除いてください。

その後、自動作成されたOCIオブジェクト（踏み台サーバ/MDS/オブジェクトストレージ）を削除し、最初からやり直すだけでマイグレーションを再実行できます。

ちなみにですが、踏み台サーバは前回自動作成されたものを使いまわすことが可能なので、削除しなくともよいです。
ただし、Migration Assistant は踏み台サーバの再起動は行わないので、踏み台サーバが起動していないと再実行時に「踏み台サーバが起動していないことによるエラー」が発生します。
(下記画面のようなエラーメッセージが出力されます)

マイグレーションを再実行する場合、踏み台サーバは削除するか、もしくは起動していることをきちんと確認しましょう。

まとめ

MySQL HeatWave Migration Assistantを使用してみた所感ですが、
移行元バージョンの確認、OCI CLI構成ファイル設定など事前の設定がきちんと行えていれば、ボタンをクリックするだけで非常に簡単にMySQL HeatWave へリフトアップできるツールだと感じました！
また、Always Freeを使用しなければ、MySQL 8.0以上のバージョンは特段のエラーもなく簡単に移行できました。

ただし、エラーが発生した場合、ツール画面上に出てくるメッセージだけでは何が原因でエラーが発生したのかがわからないことが多いので、エラー発生時はMySQL Workbenchのログを確認することを推奨します。

今回のブログが皆様のお役に立てば幸いです。
皆様も是非とも使ってみてください！

スマートスタイルTECHブログについて

スマートスタイルTECHブログでは、日頃MySQLのサポート業務に従事している有資格者で構成された技術サポートチームがMySQLに関する技術情報を発信しています。データベースのお困りごとはお気軽にご相談下さい。

パソナデータ&デザインのオープンソースDBサポートについて
MySQLに関するお問合せはこちら
技術情報 MySQL MySQL HeatWave
よかったらシェアしてね！
  • URLをコピーしました！

関連記事

目次