このページのいちばん上です このページの本文へ

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

1 システム要件

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

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

データサイズ 所要時間 計測環境
2GB 30分 SSD(MacBook Pro内蔵)上で実行した仮想マシン / CentOS6 x86_64/ メモリ 1GB
11GB 90分 SSD(MacBook Pro内蔵)上で実行した仮想マシン / CentOS6 x86_64/ メモリ 2GB

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

2.1 MySQL のインストール

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

2.2 MySQL の設定

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

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

3.2 standard_conforming_strings

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

backlog=> show standard_conforming_strings;
 standard_conforming_strings
-----------------------------
 on

4 作業ディレクトリ構成

次の 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.11.0

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

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

2回以上実行された場合は 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.47-bin.jar
1

 1:mysql-connector-java-5.1.47-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 のテーブルの作成が成功すると、上のメッセージが表示されます。すでにテーブルが作成済みの場合は、作成処理をスキップすることができます。

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

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

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

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

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

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

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

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

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

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

6 Backlog の停止

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

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

ps aux | grep backlog

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

kill BacklogのプロセスID

6.1 Red Hat Enterprise Linux 6 server または CentOS 6 の場合

# service backlog-api stop
# service backlog-git stop
# service backlog-www stop
# service backlog-app stop

6.2 Red Hat Enterprise Linux 7 または CentOS 7 の場合

# systemctl stop backlog.target

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

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

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

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

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

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

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

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

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

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

Backlog のバージョンを確認しました。1.11.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.47-bin.jar
1

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

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

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

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

9 Backlog の起動

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

9.1 Red Hat Enterprise Linux 6 server または CentOS 6 の場合

# service backlog-api start
# service backlog-git start
# service backlog-www start
# service backlog-app start

9.2 Red Hat Enterprise Linux 7 または CentOS 7 の場合

# 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、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 までお問い合わせください。

改訂履歴

2020-11-16

2020-10-09

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