2016-07-16

GitBucketは標準では内蔵のH2という組み込みデータベースで動作しますが、4.0からはH2の代わりに外部データベースとしてPostgreSQLやMySQLを使うことができるようになっています。H2はデータの保全性に問題がありますので業務等の重要な用途にGitBucketを使われるのであればなるべくPostgreSQLもしくはMySQLを利用することが望ましいです（パフォーマンス面でもメリットがあります）。

外部データベースの設定方法は以下のドキュメントに記載されていますが、このエントリでは日本語でもう少し丁寧に解説しようと思います。

github.com

クリーンインストールの場合

まず、一度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でエクスポートしておきます。

f:id:takezoe:20160716021017p:plain

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でご相談いただければと思います。

gitter.im

たけぞう瀕死ブログ

GitBucketをPostgreSQLやMySQLで動かす