pgbranch は、ローカル開発中に PostgreSQL データベースの状態を管理するためのコマンドラインツールです。Git ブランチの切り替えに伴い、異なるデータベーススキーマ、マイグレーション、またはシードデータが必要になるという一般的な問題に対処します。データベースのインスタントスナップショットを作成することで、手動でのリセットや長時間かかるダンプ／リストア操作なしに、一貫性のある状態間を切り替えることが可能になります。
このツールは、PostgreSQL をバックエンドに使用するアプリケーションを開発するエンジニア向けに設計されており、特にマイグレーションを通じて頻繁にスキーマを進化させるチームに適しています。ローカル開発環境専用であり、本番データベースでの使用は想定されていません。
pgbranch は、PostgreSQL のネイティブなテンプレートデータベース機構を利用して、スナップショットの作成と復元を高速に行います。プロジェクト内で初期化後、現在のデータベース状態を表す名前付きブランチ（スナップショット）を作成します。ブランチをチェックアウトする際、pgbranch は現在の作業用データベースをドロップし、選択したスナップショットからクローンすることで、スキーマとデータが目的のブランチと一致することを保証します。
典型的なワークフローでは、機能ブランチ上でマイグレーションやデータ変更を実行し、その状態を保存しておき、必要に応じてクリーンなメイン状態に戻ります。オプションの Git フック統合により、データベースブランチを Git ブランチと自動で同期できます。チームでは、リモートストレージを使用してスナップショットを共有場所にプッシュ／プルできます。リモート認証情報はローカルで暗号化されるため、設定ファイルを安全にコミットできます。
サポートされているリモートストレージバックエンド：
| バックエンド | 備考 |
|---|---|
| AWS S3 | 対応済み |
| MinIO | 対応済み |
| Cloudflare R2 | 対応済み |
| ローカルファイルシステム | 対応済み |
システム要件：
| コンポーネント | 要件 |
|---|---|
| PostgreSQL | 最近の任意のバージョン |
| Go | 1.21+（go install によるインストール用） |
pgbranch は、データベーススキーマの変更が頻繁に発生し、ブランチごとに固有の状態を持つ開発ワークフローにおいて、ローカル開発の効率を向上させます。開発者は実験的なマイグレーション、シードデータ、テストレコードを他のブランチに影響を与えることなく分離できます。既知の正常な状態へ戻る操作は一貫性があり高速であるため、データベースのリセットや再シードに費やす時間を削減できます。
チームでは、リモートストレージを活用して特定の問題を再現できるスナップショットを共有したり、マージ前のスキーマ差分を確認したり、マイグレーション戦略の調整を行ったりできます。スキーマ差分およびマージ機能により、マイグレーションファイルの生成や、反復的な開発における変更の直接適用など、慎重な変更管理が可能になります。全体として、pgbranch はブランチ間で予測可能なデータベース状態を維持するのに役立ち、スキーマ中心の開発サイクルにおける摩擦を低減します。
