Backlog プロフェッショナル : PostgreSQL から MySQL への移行ガイド

このドキュメントでは PostgreSQL から MySQL へデータを移行する手順を説明いたします。PostgreSQL はバージョン 9.6 をもってサポートを終了とさせていただきますので、お早めの移行をお願いいたします。MySQL をご利用の場合はこのガイドは必要ありません。

1 システム要件
2 MySQLのインストールと設定
3 PostgreSQL の設定確認
1. 3.1 bytea_output
4 作業ディレクトリ構成
5 データ移行ツールの実行（時間計測）
6 Backlog の停止
7 データ移行ツールの実行
8 データベース切替ツールの実行
9 Backlog の起動
10 データ移行ツールが正常に動作しなかった場合
改訂履歴

1 システム要件

本ドキュメントは Backlog プロフェッショナル最新版がインストールされており、その環境は Backlog プロフェッショナルインストールガイドシステム要件を満たしている事を前提とします。

移行元の PostgreSQL はバージョン 9.5 と 9.6 をサポートしています。

大量のデータを移行する場合、移行ツールの実行に時間がかかる場合があります。所要時間については以下目安にご利用ください。

データサイズ	所要時間	計測環境
11GB	28分	SSD(MacBook Pro内蔵)上で実行した仮想マシン / メモリ 8GB / プロセッサー数 4

このページのいちばん上へ

2 MySQL のインストールと設定

2.1 MySQL のインストール

Backlog プロフェッショナルインストールガイドのデータベースに記載されているバージョンの MySQL をインストールしてください。

2.2 MySQL の設定

MySQL のインストールが完了しましたら、インストールガイドの以下の３つの設定を行ってください。

2.3 MySQL の設定を一時的に変更

課題や Wiki に添付された大きなサイズのファイルを移行させるため、my.cnf を以下のように修正・追加して、MySQL サーバーを再起動してください。

修正箇所

[mysqld]
max_allowed_packet = 48M

追加箇所

[mysqld]
innodb_buffer_pool_size = 1024M
innodb_log_file_size = 512M

このページのいちばん上へ

3 PostgreSQL の設定確認

3.1 bytea_output

PostgreSQL の設定値 bytea_output を確認し、データ移行ツールの実行の前に hex に変更してください。
データ移行が完了しましたら元に戻されて構いません。

backlog=> show bytea_output;
 bytea_output
--------------
 hex

このページのいちばん上へ

4 作業ディレクトリ構成

次の jar ファイルが存在するディレクトリを「作業ディレクトリ」と呼んで説明を続けます。

mysql-connector-java-5.1.X-bin.jar
※「2.2 MySQL の設定」で「データベースドライバーのダウンロード・インストール」でダウンロードした jar ファイルを指します。

このページのいちばん上へ

5 データ移行ツールの実行（時間計測）

データ移行ツールは PostgreSQL からダンプファイルを生成し、そのファイルを元にMySQL へデータを移行します。データ量が多いほど時間がかかります。

完全なデータ移行には Backlog を停止する必要があるため、一度ツールを実行しておおよその時間を計測し、どのくらいのダウンタイムが必要であるかを把握しておくことをお勧めします。

時間計測の目的でデータ移行を実行する場合は Backlog を停止する必要はございません。データ移行ツールは MySQL へデータを移行するだけで、Backlog は PostgreSQL を利用した状態のままです。

作業ディレクトリに移動してデータ移行ツールを root 権限で起動してください。コマンドの先頭に time をつけると、最後に実行時間が表示され、時間の計測がしやすくなります。

# time /opt/backlog/bin/db-migrate.sh

データ移行ツールを開始します。　　　　　　　　　　　　　　　　　　　　　　　　　　

起動中の Backlog を確認しました。
データ移行ツールを本番実行する前には Backlog を必ず停止してください。処理を続けますか？
( y<処理を続ける> / q<中断し終了する> )

Backlog が起動している場合は処理を続けるか聞かれますので、y を選択して処理を続行します。本番実行の場合にこのメッセージが出た場合は q を選択し、 Backlog を停止してからやり直してください。


======================================================================
Backlog の設定ファイルからデータベース情報を取得します。

Backlog 設定ファイルを読み込んで現状のデータベース接続情報を取得します。

Backlog が利用しているデータベースの種類を確認しました。PostgreSQL

Backlog が利用しているデータベースの種類が表示されます。MySQLをご利用の場合はここでツールが終了します。

Backlog のバージョンを確認しました。1.12.0

ご利用のBacklog のバージョンが表示されます。バージョンが最新ではない場合はここでツールが終了します。

このデータ移行ツールを初めて実行された場合は、エンターキーを押して、次に進んでください。

２回以上実行された場合は PostgreSQL のダンプファイルが実行ディレクトリの配下に backlog.dmp という名前で存在します。処理を省略できますので backlog.dmp を相対パスもしくは絶対パスで指定してください。
( <Enter> / <backlog.dmpのパス> )

初めてツールを実行された場合は、エンターキーを押してください。

再実行した場合で、PostgreSQL のダンプファイルがある場合は処理を省略できます。作業ディレクトリの下に存在するダンプファイル（backlog.dmp）のパスを指定してください。

※ Backlog を停止せずに実行したときのダンプファイルはデータの漏れがあるので本番では使用しないでください。

次の内容を利用して PostgreSQL のデータをダンプします。
サーバーホスト        [localhost]
ポート番号        [5432]
ユーザー        [backlog]
パスワード        [*****]

Backlog が利用しているデータベースの情報が表示されます。

PostgreSQL のデータダンプ用のコマンドが実行可能であることを確認しました。

ダンプに必要な pg_dump コマンドがあると上のメッセージが表示されます。

PostgreSQL のバージョンチェックを開始します。

PostgreSQL のバージョンが Backlog プロフェッショナルインストールガイドのデータベースに記載されているものであるか確認します。

PostgreSQL のダンプを開始しました。
PostgreSQL のダンプファイル dump_work_20200912230031/backlog.dmp を保存しました。

データベースのダンプに成功すると、上のメッセージが表示されます。

======================================================================
PostgreSQL のデータを MySQL へ移行します。

使用するJDBCドライバーを選択してください。
 1:mysql-connector-java-5.1.49-bin.jar
1

 1:mysql-connector-java-5.1.49-bin.jar が選択されました。

作業ディレクトリに存在する MySQL の JDBC ドライバー名が表示されます。JDBC ドライバー名の前に表示されている番号を指定してください。上では 1 を選択した状態を記載しています。

MySQL サーバーのホスト名を指定してください [localhost]

MySQL サーバーのホスト名を指定してください。メッセージ中に表示される[]の値は、未入力時に既定値として設定されます。

MySQL サーバーのポート番号を指定してください [3306]

MySQL サーバーのポート番号を指定してください。メッセージ中に表示される[]の値は、未入力時に既定値として設定されます。

MySQL のユーザーを指定してください [backlog]

MySQL のユーザーを指定してください。メッセージ中に表示される[]の値は、未入力時に既定値として設定されます。

MySQL のユーザーのパスワードを入力してください [Backlog@1]

MySQL のユーザーのパスワードを指定してください。メッセージ中に表示される[]の値は、未入力時に既定値として設定されます。

次の設定内容でデータ移行を行います。

サーバーホスト        [localhost]
ポート番号        [3306]
ユーザー        [backlog]
パスワード        [Backlog@1]

よろしいですか？
( y<続ける> / r<やり直し> )

MySQL の設定が表示されます。 y を選択すると MySQL への移行処理を続行します。r を選択すると、MySQL サーバーのホスト名の指定からやり直せます。

MySQL のバージョンチェックを開始します。

MySQL のバージョンが Backlog プロフェッショナルインストールガイドのデータベースに記載されているものであるか確認します。さらに、MySQL の backlog データベースにデータがあるかどうか確認し、もしデータがある場合はエラーメッセージが表示されツールが中断します。

テーブルの新規作成を開始します。
:
:
テーブルの新規作成が終了しました。

Backlog のテーブルの作成が成功すると、上のメッセージが表示されます。すでにテーブルが作成済みの場合は、作成処理をスキップすることができます。

PostgreSQL の設定値を調べています。

PostgreSQL の設定値の確認が始まると、上のメッセージが表示されます。

ダンプファイルの変換を開始しました。
ダンプファイルの変換に成功しました。

MySQL 用へダンプファイルの変換に成功すると、上のメッセージが表示されます。

MySQL へデータ移行しています。
MySQL へデータを移行しました。

MySQL へデータの移行が成功すると、上のメッセージが表示されます。データ量が多いほど時間がかかります。移行したあとも PostgreSQL 側にデータは残ります。

データベースの型変換をしています。
データベースの型変換が終了しました。

MySQL にデータを移行したあと、一部のデータの型変換が成功すると、上のメッセージが表示されます。データ量が多いほど時間がかかります。

終了
設定が完了しました。

データの移行が完了しました。
※ 実際にデータベースを切り替える場合にのみ、以下のコマンドを実行し Backlog が使用するデータベースをPostgreSQLからMySQLへ変更してください。
/opt/backlog/bin/db-switch.sh

完了メッセージが表示され、データ移行ツールが終了します。

計測した時間はメンテナンスの計画にご利用ください。

このページのいちばん上へ

6 Backlog の停止

データ移行ツールを本番実行する前に Backlog を停止してください。Backlog が利用されると、正しくデータが移行されない可能性があります。

以下のコマンドで Backlog を停止させてください。

# systemctl stop backlog.target

ps コマンドなどで Backlog のプロセスが停止していることを確認してください。

ps aux | grep backlog

Backlog のプロセスが停止しない場合がありますので、一つずつ kill コマンド等で停止させて下さい。

kill BacklogのプロセスID

このページのいちばん上へ

7 データ移行ツールの実行

「4. データ移行ツールの実行（時間計測）」と手順は同じです。詳細は「4. データ移行ツールの実行（時間計測）」をご参照ください。

計測時の MySQL のデータは消してから実行してください。

このページのいちばん上へ

8 データベース切替ツールの実行

データ移行ツールが完了しましたら、次にデータベース切替ツールを実行します。このツールは Backlog がアクセスするデータベースを MySQL へ切り替えるためのものです。

作業ディレクトリに移動してデータベース切替ツールを root 権限で起動してください。

# /opt/backlog/bin/db-switch.sh

データベース切替を開始します。

Backlog が停止していることを確認しました。
Backlog の設定ファイルからデータベース情報を取得します。

Backlog 設定ファイルを読み込んで現状のデータベース接続情報を取得します。

Backlog のバージョンを確認しました。1.12.0

ご利用の Backlog のバージョンを確認します。バージョンが最新ではない場合はここでツールが終了します。

現在のデータベースの設定は以下の通りです。

データベース        [PostgreSQL]
サーバーホスト        [localhost]
ポート番号        [5432]
ユーザー        [backlog]
パスワード        [*****]

現在 Backlog が利用中のデータベースの設定が表示されます。

切替先のデータベースを選択してください
( m<MySQL> / p<PostgreSQL> )

切り替えるデータベースを選択します。MySQL を選択したとして手順の説明を続けます。

MySQL サーバーのホスト名を指定してください [localhost]

MySQL サーバーのホスト名を指定してください。メッセージ中に表示される[]の値は、未入力時に既定値として設定されます。

MySQL サーバーのポート番号を指定してください [3306]

MySQL サーバーのポート番号を指定してください。メッセージ中に表示される[]の値は、未入力時に既定値として設定されます。

MySQL のユーザーを指定してください [backlog]

MySQL のユーザーを指定してください。メッセージ中に表示される[]の値は、未入力時に既定値として設定されます。

MySQL のユーザーのパスワードを入力してください [Backlog@1]

MySQL のユーザーのパスワードを指定してください。メッセージ中に表示される[]の値は、未入力時に既定値として設定されます。

次の設定内容でデータベース切換を行います。

データベース        [MySQL]
サーバーホスト        [localhost]
ポート番号        [3306]
ユーザー        [backlog]
パスワード        [Backlog@1]

よろしいですか？
( y<続ける> / r<やり直し> )

切替先のデータベースの設定が表示されます。 y を選択すると Backlog の設定ファイルの書き換えが始まります（MySQLを選択した場合は、JDBCドライバーの設定も行います）。

r を選択すると、切り替え先のデータベースの選択からやり直せます。

使用するJDBCドライバーを選択してください。
 1:mysql-connector-java-5.1.49-bin.jar
1

 1:mysql-connector-java-5.1.49-bin.jar が選択されました。

終了
設定が完了しました。

上記のメッセージが表示され、データベース切替ツールが終了します。

このページのいちばん上へ

9 Backlog の起動

Backlog を起動して、ログインできるか確認をしてください。

# systemctl start backlog.target

MySQLに切り替わったかどうかを確認する方法は以下があります。

PostgreSQL を停止する
Backlog を操作して backlog データベースレコードに変更があるかを確認する

正常に動作していることを確認したら my.cnf の設定値を以下のように元に戻して、MySQL サーバーを再起動してください。

修正箇所

[mysqld]
max_allowed_packet = 16M

削除箇所

[mysqld]
innodb_buffer_pool_size = 1024M
innodb_log_file_size = 512M

このページのいちばん上へ

10 データ移行ツールが正常に動作しなかった場合

データ移行ツールが正常に動作しなかった場合は以下の方法をお試しください。

「PostgreSQL のダンプに失敗しました。」もしくは「ダンプファイルの変換に失敗しました。」というメッセージが表示されました。

ストレージの空き容量が不足したためダンプファイルの作成もしくはダンプファイルの変換に失敗した可能性があります。以下を目安に空き容量を確保してください。

PostgreSQL のデータサイズ	データ移行ツールが出力するダンプファイルの合計サイズ	MySQL のデータサイズ
11 GB	47 GB	12 GB

空き容量の確保のため、データ移行ツールを再実行する前に以下のファイルを削除してください。また、データ移行が正常に終了した後も削除できます。

作業ディレクトリに存在する、名前が dump_work_ で始まるディレクトリとその中にあるファイル
/tmp に存在する、名前が backlog-for-mysql.dmp で始まるファイル

「 MySQL へのデータ移行に失敗しました。」というメッセージが表示されました。

作業ディレクトリに出力された実行ログ db-migration-tool.log に「MySQL server has gone away」というメッセージが出ている場合、 2.3 MySQL の設定を一時的に変更を参考に MySQL の設定値が変更されているかご確認ください。

「2.3 MySQL の設定を一時的に変更」に沿って設定しましたが、「 MySQL へのデータ移行に失敗しました。」というメッセージが表示されます。

MySQL は以下のように大文字小文字や全角半角、カタカナひらがなを区別しないため、Wiki などでデータ移行に失敗することがあります。
Backlog を起動し Wiki のページ名を変更してから､データ移行ツールを実行してください。

Wikiのページ名の例	同一ページ名と判定される例
test	TEST、ＴＥＳＴ
あいうえお	ぁぃぅぇぉ、アイウエオ、ァィゥェォ、ｱｲｳｴｵ、ｧｨｩｪｫ

「MySQL へデータ移行しています。」とメッセージが出たまま処理が止まったように見えます。

PostgreSQL のデータ量が多いと、MySQL へのデータ移行に時間がかかります。
SHOW PROCESSLIST で現在実行中のクエリーを確認し、処理が進んでいるかご確認ください。

# mysql -u backlog -p
mysql> SHOW FULL PROCESSLIST;

「データベースの型変換が失敗しました。」というメッセージが表示されました。

3 PostgreSQL の設定確認を参考に PostgreSQL の設定値を確認し、必要があれば修正してください。

それでも問題が解決しない場合は

作業ディレクトリに出力された実行ログ db-migration-tool.log を添付して support-ja@backlog.com までお問い合わせください。

このページのいちばん上へ

改訂履歴

2024-02-29

バージョン 1.12.0 リリースに伴い、Backlog のバージョンを 1.12.0 に変更しました。

2023-12-01

バージョン 1.11.17 リリースに伴い、Backlog のバージョンを 1.11.17 に変更しました。

2023-11-08

バージョン 1.11.16 リリースに伴い、Backlog のバージョンを 1.11.16 に変更しました。

2023-09-07

バージョン 1.11.15 リリースに伴い、Backlog のバージョンを 1.11.15 に変更しました。

2023-06-22

バージョン 1.11.14 リリースに伴い、Backlog のバージョンを 1.11.14 に変更しました。

2023-03-16

バージョン 1.11.13 リリースに伴い、Backlog のバージョンを 1.11.13 に変更しました。

2023-02-02

バージョン 1.11.12 リリースに伴い、Backlog のバージョンを 1.11.12 に変更しました。

2022-10-13

バージョン 1.11.11 リリースに伴い、Backlog のバージョンを 1.11.11 に変更しました。

2022-07-13

バージョン 1.11.10 リリースに伴い、Backlog のバージョンを 1.11.10 に変更しました。

2022-04-15

バージョン 1.11.9 リリースに伴い、Backlog のバージョンを 1.11.9 に変更しました。

2022-02-24

バージョン 1.11.8 リリースに伴い、Backlog のバージョンを 1.11.8 に変更しました。

2021-12-21

バージョン 1.11.7 リリースに伴い、Backlog のバージョンを 1.11.7 に変更しました。

2021-12-14

バージョン 1.11.6 リリースに伴い、Backlog のバージョンを 1.11.6 に変更しました。

2021-10-12

バージョン 1.11.5 リリースに伴い、Backlog のバージョンを 1.11.5 に変更しました。

2021-09-30

バージョン 1.11.4 リリースに伴い、Backlog のバージョンを 1.11.4 に変更しました。

2021-07-29

バージョン 1.11.3 リリースに伴い、Backlog のバージョンを 1.11.3 に変更しました。

2021-03-05

バージョン 1.11.2 リリースに伴い、Backlog のバージョンを 1.11.2 に変更しました。
システム要件に移行元の PostgreSQL はバージョン 9.5 と 9.6 をサポートしていることを追記しました。

2021-01-29

サポート対象外となった Red Hat Enterprise Linux (RHEL) 6 と CentOS 6 に関する記述を削除しました。RHEL 6 もしくは CentOS 6 をご利用の場合はアーカイブされたガイドをご参照ください。
動作改善に伴いシステム要件の表を修正しました。
動作改善に伴い「3.2 standard_conforming_strings」項を削除しました。
動作改善に伴いデータ移行ツールの実行（時間計測）に PostgreSQL の設定値を確認するメッセージが表示されることを追記しました。
バージョン 1.11.1 リリースに伴い、Backlog のバージョンを 1.11.1 に変更しました。

2020-11-16

PostgreSQL の設定確認項を追加しました。
データ移行ツールが正常に動作しなかった場合項に「データベースの型変換が失敗しました。」というエラーが出たときの対処法を追加しました。

2020-10-09

本ドキュメントを作成しました。

このページのいちばん上へ

目次