GitBucketは標準では内蔵のH2という組み込みデータベースで動作しますが、4.0からはH2の代わりに外部データベースとしてPostgreSQLやMySQLを使うことができるようになっています。H2はデータの保全性に問題がありますので業務等の重要な用途にGitBucketを使われるのであればなるべくPostgreSQLもしくはMySQLを利用することが望ましいです(パフォーマンス面でもメリットがあります)。
外部データベースの設定方法は以下のドキュメントに記載されていますが、このエントリでは日本語でもう少し丁寧に解説しようと思います。
クリーンインストールの場合
まず、一度GitBucketを起動すると~/.gitbucket
ディレクトリが作成されるので、いったんGitBucketを停止します。
~/.gitbucket
ディレクトリの中にdatabase.conf
というファイルがあるはずです。このファイルは以下のような内容になっています。
db { url = "jdbc:h2:${DatabaseHome};MVCC=true" user = "sa" password = "sa" }
このファイルを使用するデータベースにあわせて以下のように編集します(URLやユーザ名、パスワードは使用する環境にあわせて適宜変更してください)。データベースはあらかじめ作成しておく必要があります。なお、データベースは使用する文字コードで作成しておく必要があります。
MySQLの場合
db { url = "jdbc:mysql://localhost/gitbucket?useUnicode=true&characterEncoding=utf8" user = "test" password = "test" }
MySQLの場合は5.7以上である必要があるので注意してください。
PostgreSQL
db { url = "jdbc:postgresql://localhost/gitbucket" user = "test" password = "test" }
これでGitBucketを再起動すればMySQLまたはPostgreSQLの指定したデータベースに必要なテーブルが自動的に作成され、外部データベースでGitBucketを使い始めることができます。
アップグレードの場合
既存のGitBucketを外部データベースを使用するように設定する場合は一度データをエクスポートしておき、データベースの設定後にインポートしなおす必要があります。また、GitBucket 3系から4系にアップグレードする場合、以下の2点に注意が必要です。
- まず一度GitBucket 3系の最終バージョンである3.14までアップデートしてから4系にアップデートする必要がある
- GitBucket 4系にアップデートする際は一度プラグインをアンインストール(
~/.gitbucket/plugins
ディレクトリからjarファイルを削除)しておく必要がある
データのエクスポート
GitBucketを4系にアップグレードするとGitBucketの管理コンソールから以下のように既存のH2内のデータをエクスポートする機能が利用可能になりますので、ここでデータをXMLまたはSQLでエクスポートしておきます。
XMLだとインポート時にGitBucketの管理コンソールから作業が可能ですが、SQLだと自分でDBに直接インポートする必要があります。そのためSQLのほうが作業は面倒なのですが、データが大きい場合などXMLだとインポートに失敗することがあるので、可能であればXMLとSQL両方ともエクスポートしておくとよいでしょう。
プラグインのデータも移行する場合はプラグインのテーブル(gitbucket-gist-pluginであればGIST
テーブルとGIST_COMMENT
テーブル)も選択しておきます。プラグインのデータが不要な場合はチェックを外しておきます。いったん基本データだけ移行してプラグインのデータは後から移行したいという場合は二回に分けてエクスポートしておきます。
データのインポート
エクスポートに成功したら一度GitBucketを停止し、使用するデータベースにあわせて~/.gitbucket
ディレクトリにあるdatabase.conf
を前述の通り修正します。また、プラグインのデータも移行する場合はGitBucket4系に対応したバージョンのプラグインをインストールしておきます。
この状態でGitBucketを起動するとクリーンインストール状態で立ち上がりますのでデフォルトの管理ユーザであるroot / rootでログインし、管理コンソールからさきほどエクスポートしたXMLファイルをインポートします。インポートが成功すれば外部データベースへの移行は完了です。
ただし、PostgreSQLの場合のみ、追加で以下のSQLを実行しておく必要がありますのでpsqlコマンドなどを使って実行しておいてください。
SELECT setval('label_label_id_seq', (select max(label_id) + 1 from label)); SELECT setval('activity_activity_id_seq', (select max(activity_id) + 1 from activity)); SELECT setval('access_token_access_token_id_seq', (select max(access_token_id) + 1 from access_token)); SELECT setval('commit_comment_comment_id_seq', (select max(comment_id) + 1 from commit_comment)); SELECT setval('commit_status_commit_status_id_seq', (select max(commit_status_id) + 1 from commit_status)); SELECT setval('milestone_milestone_id_seq', (select max(milestone_id) + 1 from milestone)); SELECT setval('issue_comment_comment_id_seq', (select max(comment_id) + 1 from issue_comment)); SELECT setval('ssh_key_ssh_key_id_seq', (select max(ssh_key_id) + 1 from ssh_key));
XMLでのインポートに失敗する場合はエクスポートしたSQLファイルを直接DBにインポイートします。たとえばMySQLの場合は以下のようにします。
$ mysql -u root -p gitbucket < gitbucket-export-xxxxxxxx.sql
まとめ
GitBucketを外部データベースで動かす方法について紹介しました。デフォルトのH2はデータが破損することがあるというレポートを多くのユーザさんから頂いていますので、繰り返しになりますができるだけMySQLやPostgreSQLを利用されることをおすすめします。
既存のGitBucketのデータを外部データベースに移行する場合は多少複雑な手順が必要になりますが、もしトラブルに遭遇した場合はGitterでご相談いただければと思います。