YugabyteDB Voyagerは、YugabyteDBへの移行を支援するツールです。移行可否のアセスメントから、スキーマ移行、データ移行まで、データベース移行に必要な操作全般を管理することができます。
本稿では、まずYugabyteDB Voyagerの概要について解説し、さらに移行方式の一つであるオフラインマイグレーションについて、具体的な操作方法を解説します。

概要

YugabyteDB Voyagerは、無料かつオープンソースのYugabyteDB移行ツールです。PostgreSQL、Oracle、MySQLといった主要なデータベースを移行元としてサポートしており、オンプレミス環境・クラウド環境のどちらでも使用可能なため、さまざまなシステム構成からの移行に対応できます。また、すべてのYugabyteDB製品を移行対象としてサポートしています。

YugabyteDB Voyagerは、YugabyteDBに移行するにあたりどの程度修正が必要な箇所があるかをリストアップし、移行可能かどうかのアセスメントを支援します。また、実際に移行すると決定した際には、テーブル定義やインデックス定義については自動で変換を行い、移行に必要な労力を最小限に抑えます。データ移行の際にはチューニングを行い、インポートパフォーマンスの向上を自動で行います。

さらに、ソースデータベースとしてPostgreSQLを使用する場合、データベース停止が必要なオフラインマイグレーションの他に、ダウンタイムを最小限に抑えるライブマイグレーションが利用可能です。ビジネスクリティカルなアプリケーションにおいて、YugabyteDBへの移行を強力に支援します。

移行方式

YugabyteDB Voyagerで利用可能な移行方式は以下の通りです。

オフラインマイグレーション

今回は、PostgreSQLからYugabyteDBへのオフラインマイグレーションを実行してみます。
環境は以下の通りです。

今回は移行元データベースとしてPostgreSQLサーバ1台、移行先データベースとしてYugabyteDB3台のクラスタ構成を構築しています。
各サーバの情報は以下の通りです。

今回はPostgreSQLサーバ、YugabyteDBクラスタの構築手順については記載を省略します。YugabyteDBクラスタの構築についてはYugabyteDB OSS版の使い方、YugabyteDB Aeon Self-Managed (旧 YugabyteDB Anywhere) の使い方も参考にしてください。

YugabyteDB Voyagerのインストール

まず、YugabyteDB Voyagerをインストールします。
公式ドキュメントの手順に従って、インストールしてください。
本稿ではPostgreSQLサーバにYugabyteDB Voyagerをインストールしています。

ソースデータベースに対する事前準備

まず、ソースデータベース(PostgreSQL)にマイグレーション用のユーザを作成します。マイグレーション用ユーザは移行対象のすべてのリソースに対してREAD権限を持っている必要があります。

今回はybvoyagerユーザを作成します。
ソースデータベースに接続し、以下のSQLを実行しました。

CREATE USER ybvoyager PASSWORD 'password';

次に、必要な権限を与えます。移行対象のデータベースに接続し、/opt/yb-voyager/guardrails-scripts/以下にある yb-voyager-pg-grant-migration-permissions.sql を実行します。

psql -h 172.20.0.15 \
     -d db1 \
     -U postgres \
     -v voyager_user='ybvoyager' \
     -v schema_list='public' \
     -v is_live_migration=0 \
     -v is_live_migration_fall_back=0 \
     -f /opt/yb-voyager/guardrails-scripts/yb-voyager-pg-grant-migration-permissions.sql

これで、ソースデータベースに対する準備は完了しました。

ターゲットデータベースに対する事前準備

ターゲットデータベース(YugabyteDB)に移行先のデータベースを用意します。
移行先のデータベース名はソースデータベースと同じ名前でも異なる名前でも問題ありません。(以降のyb-voyagerコマンド実行時に、データベース名を指定しない場合、yb-voyagerは移行先データベースを yugabyte データベースとみなします。)
移行先データベース名をyugabyteから変更したい場合は、YugabyteDB クラスタにデータベースを作成してください。

CREATE DATABASE db1 WITH COLOCATION = true;

次に、ターゲットデータベースについてもマイグレーション用ユーザを作成します。スーパーユーザとして作成する必要があります。
今回はybvoyagerユーザを作成しました。

CREATE USER ybvoyager SUPERUSER PASSWORD 'password';

エクスポートディレクトリの設定

yb-voyagerはすべてのマイグレーションの状態をエクスポートディレクトリに書き出します。これは、Voyagerが使用するメタデータに加えて、スキーマやデータのダンプも含まれます。そのため、ソースデータベース全体を格納できる、十分な空き容量のあるファイルシステム上にエクスポートディレクトリを作成してください。

mkdir -p $HOME/yb-migrate/export-dir

マイグレーションを実行すると、yb-voyagerによって、以下のディレクトリが作成されます。

assessment: アセスメント時のメタデータと、アセスメント結果を格納します。
schema: ソースデータベースのスキーマがCSV形式で格納されます。
data: ソースデータベースのデータがCSV形式で格納されます。
metainfo/temp yb-voyagerが内部予約しているディレクトリです。
logs: コマンド実行時のログファイルが格納されます。

設定ファイルの用意

yb-voyagerコマンドには、設定値を一括で記載する設定ファイルが用意されています。設定ファイルを使用すると、コマンド実行時に逐一パラメータを指定する必要がないため便利です。(v2025.6.2以降に導入された機能です。)

/opt/yb-voyager/config-templates以下にテンプレートファイルが提供されているので、このテンプレートファイルをコピーして使用します。今回はオフラインマイグレーション用のファイル(offline-migration.yaml)を使用します。

cp /opt/yb-voyager/config-templates/offline-migration.yaml ~

ファイル内の、エクスポートディレクトリに関する項目、ソースデータベースの接続情報、ターゲットデータベースへの接続情報を編集する必要があります。以下は設定例です。

export-dir: /voyager/export-dir
yugabyted-control-plane:
  db-conn-string: postgresql://yugabyte:yugabyte@172.20.0.11:5433  
source:
  db-type: postgresql
  db-host: 172.20.0.15
  db-port: 5432
  db-name: db1
  db-schema: public
  db-user: ybvoyager
  db-password: password
target:
  db-host: 172.20.0.11
  db-port: 5433
  db-name: db1
  db-user: ybvoyager
  db-password: password

マイグレーションのアセスメント

以下のコマンドを実行して、マイグレーションのアセスメントを実施します。
このとき、先ほど作成したYAMLファイルのパスを–config-fileに指定します。
今回は、~/offline-migration.yamlを指定しています。

yb-voyager assess-migration --config-file ~/offline-migration.yaml

実行すると、評価レポートのパスがコンソールに出力されます。
評価レポートはJSON形式とHTML形式で出力されます。以下はhtml形式の評価レポートです。

移行の難易度や、非互換のオブジェクトが存在しているかを確認することができます。

スキーマのエクスポート

アセスメントが完了したら、次はソースデータベースからスキーマをエクスポートします。
以下のコマンドを実行してください。

yb-voyager export schema --config-file ~/offline-migration.yaml

実行すると、エクスポートディレクトリのschemaディレクトリに、結果が保存されます。

スキーマのエクスポートの際に、yb-voyagerはスキーマ定義の調整を自動で行います。

スキーマの分析

スキーマのエクスポート時に、yb-voyagerはスキーマ定義の調整を自動で行います。しかし、自動調整だけではYugabyteDBへのインポートが失敗する可能性があります。YugabyteDBはPostgreSQLと互換性がありますが、分散システムであるため、スキーマに若干の手動変更が必要になります。

以下コマンドを実行し、スキーマを分析してください。

yb-voyager analyze-schema --config-file ~/offline-migration.yaml

手動変更が必要なDDLステートメント一覧を表示するレポートを出力します。

スキーマの手動修正

生成されたレポートに記載のあるすべての問題について、EXPORT_DIR/schema/以下にある、対象のDDLを修正してください。手動で修正を加えたら、yb-voyager analyze-schema コマンドを再実行してください。変更内容を反映した新しいレポートが生成されます。生成されたレポートに問題がなくなるまで、この手順を繰り返す必要があります。

スキーマのインポート

スキーマの修正が完了したら、ターゲットデータベースにスキーマをインポートします。

yb-voyager import schema --config-file ~/offline-migration.yaml

yb-voyagerコマンドは、エクスポートディレクトリのschemaサブディレクトリにあるDDL を、ターゲットのYugabyteDBデータベースに適用します。もし、スキーマのインポートが途中で異常終了してしまった場合は、設定ファイルのignore-existパラメータをtrueに変更してから再実行してください。すでに作成に成功したオブジェクトは無視するようになります。

データのエクスポート

スキーマ移行が完了したら、次はデータ移行を行います。まずは、ソースデータベースからデータをエクスポートします。

yb-voyager export data --config-file ~/offline-migration.yaml

このコマンドは、EXPORT_DIR/data以下にCSV形式でデータをダンプします。

注意事項

データエクスポートの際は、以下の点に注意してください。

• PostgreSQLの場合、ソースデータベース上でロックを獲得しようとしている他のプロセスが存在しないことを確認してください。並列ジョブが複数ある場合、データをダンプすることはできません。
• シーケンスの移行は、シーケンスの作成とレジューム値の設定という2つのステップで構成されています。レジューム値はデータのエクスポート時に生成されます。また、すべてのテーブルデータがインポートされた直後に、ターゲットのYugabyteDBデータベースにこれらのレジューム値は設定されます。PostgreSQLの場合、移行対象テーブルに紐づけられている、または、テーブルが所有するシーケンスのみが移行時に復元されます。
• ソースデータベース上のテーブルの行サイズが大きすぎて、デフォルトのRPCメッセージサイズを超えている場合、インポートデータは「ERROR: Sending too long RPC message…」というエラーで失敗します。そのため、行サイズが大きいテーブルは、該当箇所を削除してから個別に移行する必要があります。

データのインポート

データをエクスポートできたら、次はターゲットデータベースにデータをインポートします。

yb-voyager import data --config-file ~/offline-migration.yaml

進行状況を確認したい場合は、yb-voyager import data statusを実行してください。

デフォルトでは、yb-voyagerは複数の接続を使用して並列にデータをインポートします。並列度はクラスタのリソース使用状況に基づいて判断されます。

yb-voyagerは、データダンプファイル(EXPORT_DIR/data)をより小さなバッチに分割します。yb-voyagerは、ターゲットのYugabyteDBデータベースクラスタのすべてのノードが使用されるように、バッチを同時に取り込みます。このフェーズは、データインポート中にyb-voyagerが終了した場合でも再開できるように設計されています。再開後、データのインポートは処理が中断された地点から続行されます。

注意事項

データインポートの際は、以下の点に注意してください。

• 大規模データセットをインポートする場合は、ターミナルセッションが終了してもインポート処理が中断されないように、screenセッションでimport dataを実行してください。
• yb-voyagerのimport dataコマンドがデータ取り込み完了前に終了した場合は、同じ引数で再度実行すれば、データインポート処理が再開されます。

データインポート後のスキーマ調整

ソースデータベースにNOT VALID制約がある場合は、データインポート後に制約を作成するコマンドを実行する必要があります。

yb-voyager finalize-schema-post-data-import --config-file ~/offline-migration.yaml

マイグレーションの検証

スキーマとデータのインポートが完了したら、データが正しく移行されていることを確認します。
ソースデータベースとターゲットデータベース(YugabyteDB)の両方で検証用クエリを手動で実行して確認を行います。
例えば、各テーブルの行数を確認するクエリを実行して行数がそろっているかどうかの確認を行ってください。

マイグレーションの終了

データが正しく移行されていることを確認できたら、移行する際に作成されたディレクトリ・データをクリーンアップします。
yb-voyager end migration コマンドで、クリーンアップを実行します。

yb-voyager end migration --config-file ~/offline-migration.yaml

必要であれば、移行に使用したybvoyagerユーザの削除も行ってください。
yb-voyagerで移行を実施すると、移行されたすべてのオブジェクトはybvoyagerユーザが所有している状態となります。
オブジェクトの所有者を別のユーザに変更してから、ybvoyagerユーザを削除してください。

終わりに

本稿ではYugabyteDBへのマイグレーション支援ツール YugabyteDB Voyagerの使用方法を紹介しました。
YugabyteDBはPostgreSQL互換データベースであるとはいえ、アーキテクチャが異なりますので、移行する際はスキーマ定義の修正が必要になります。
YugabyteDB Voyagerは、スキーマ定義の互換性の評価から実施できますので、マイグレーションを行う際の強力なツールとなります。
YugabyteDBへの移行を検討している方は、ぜひYugabyteDB Voyagerをご活用ください。

参考

YugabyteDB Voyager 公式ドキュメント