Persistentブランチを利用する場合のSupabase Branching 設定と運用自動化

こんにちは、株式会社Berryの浅沼です。
Supabaseの機能の中で、最近はBranchingが格段に便利だと感じています。SupabaseのBranchingはGitHubと連携することで、プルリクエストのGitブランチに合わせてSupabaseのプロジェクトも手軽にブランチングされる機能です。他の開発に影響を与えずに変更を反映したDBができるため、動作確認の環境用意が格段に捗ります。

Supabase Branchingの公式ドキュメントはこちらになります。
https://supabase.com/docs/guides/deployment/branching

このSupabase Branchingは、VercelのマーケットプレイスにあるSupabase用のIntegrationと連携することで本領を発揮すると思います。この記事では、GitHub + Vercel + Supabase Branchingの環境設定方法、プルリクエストにおける動作・運用について、また、Branchingでできないことの補い方を紹介したいと思います。

Berryでは、よくあるStagingやDevelopmentなど、結合環境に使うGitブランチを利用するパターンでGitを運用しています。その場合、何度か設定に躓いたので、Supabase BranchingのPersistentブランチを利用するケースでの設定について、この記事で扱います。

この記事の執筆時において利用している supabase cli は、

❯ supabase -v
2.19.7

です。

Supabase BranchingにPersistentなブランチを作る

前提として、Gitのブランチ運用は以下のようになっています。

main: プロダクション用
development: 開発用（結合環境）
feature or chore or epic/xxxx: 開発タスク用
release/xxx: リリース作業用

1. GitHubのIntegrationを有効化、設定する

Supabaseの管理画面、Organizations->IntegrationsにあるGitHub Connectionsの設定を行います。

連携するSupabaseのプロジェクトとGitHubのリポジトリを選択して連携を開始します。

連携できたら設定を見てみましょう。Manage -> Configure connectionで設定を確認できます。
Supabase changes onlyはデフォルトのONのままにして、migrationの追加などがあった場合のみ、SupabaseのBranchができるようにしています。

2. Supabase Branchingを有効化する

次に、Supabase Branchingを有効化します。

Choose your production branchの欄に、プロダクション用のGitブランチを入力します。
※この記事を書いている時点では、設定完了後に変更することができない項目です。変更する場合は、Supabase BranchingをDisableにしてから、再度、設定する必要があります。

3. developmentブランチのPersistentなSupabase Branchを作成する

無事にSupabase Branchingを有効化できたら、Manage branchesの画面からCreate branchで、Gitのdevelopmentブランチ用のSupabase Branchを作成します。

Supabase Branchの作成が完了したら、一覧からSwitch to persistentを実行して、Persistentなブランチに切り替えます。

後述のVercelとの連携で、Persistentへの変更を忘れていて、VercelのPreview用環境変数に反映できないことがありました。

4. config.tomlのremotesを設定する

supabase/config.tomlに[remotes.xxxx]の設定を加えることで、GitHubのdevelopmentブランチに向けたプルリクエストがマージされたときに、supabaseのmigrationなどをremotesに設定したSupabase Branchに自動反映させることができます。

supabase/config.toml

[remotes.development]
project_id = $PROJECT_ID

[remotes.development.db.seed]
sql_paths = ["./seed.sql"]

上記の例のように、remotes用のseed.sqlを個別に設定することもできます。

5. supabase cliのlinkを設定する

プロダクション用のSupabase Branchに向けて誤操作しないように、development用のSupabase Branchにローカル開発環境のsupabase cliのlinkを切り替えておきましょう。

> supabase link --project-ref $PROJECT_ID

VercelのSupabase Integrationを設定する

1. SupabaseのIntegrationを有効化

まずは、VercelにSupabaseのIntegrationをインストールします。
VercelのIntegrationメニューからSupabaseを選択して設定していきます。
以下では、既存のSupabaseプロジェクトと接続する流れで設定しています。

2. Supabase側でVercel Integrationを設定する

Vercelにインストールできたら、Supabase側のIntegrationメニューにVercel Integrationが追加されます。

初期状態では、連携するEnvironmentはProductionのみになっています。

これをPreview用のEnvironmentを連携するように設定します。私の場合は、動的に連携するEnvironmentはPreviewのみにしています。Production用は必要最低限の管理にしたいため、Vercel側のみで管理しています。利用しているBuild環境に合わせて、Prefixの項目も設定します。

変更後、Resync environment variablesを実行して、VercelにPreview用の環境変数設定を反映します。

3. Preview用のEnvironmentを設定する

Resync environment variablesを実行後、VercelのEnvironment variablesを確認すると、PreviewにSupabaseと連携して作られた環境変数ができていると思います。
※Productionにも初回の設定で環境変数ができているので、不要なものは削除しています。

ここで環境変数のSUPABASE_URL、VITE_SUPABASE_URLの設定値を確認すると、Supabase BranchingのProduction branchに設定しているブランチのProject IDやURLになっています。
これをPersistentに設定したdevelopmentブランチの内容に更新します。

• SUPABASE_URL
• VITE_SUPABASE_URL
• SUPABASE_ANON_KEY
• VITE_SUPABASE_ANON_KEY

は、内容を確認して、確実に更新してください。

4. プルリクエストを作成して、ブランチに連動した環境変数ができること確認する

では、試しにGitHubへプルリクエストを作成して動作確認しましょう。新しいmigrationを作るか、seed.sqlの内容を変更しているブランチを作成します。

プルリクエストを作成、SupabaseとVercelのIntegrationが成功したら、プルリクエスト分のブランチされたSupabaseプロジェクトとVercelの環境変数が追加されているのが確認できます。

ブランチの環境変数の設定が、Supabase Branchingのプロジェクトと内容が一致していること、Persistent用に設定した環境変数が変更されていないことを確認できたら成功です。
うまく行かないときは、前述のSupabase Branchingの設定でPersistentブランチの設定漏れ、config.tomlへのremotes設定漏れなどを疑ってみてください。

プルリクエストの運用におけるメリット

Supabase BranchingとGitHub、Vercelの連携を活用することで、プルリクエストごとの開発環境が大幅に改善されます。

自動化されるメリット

この連携により、以下の作業が自動化されます：

• DBスキーマの変更反映: supabase db pushが自動的に実行され、スキーマの変更が各ブランチに適用されます
• Edge Functionのデプロイ: config.tomlに設定したEdge Functionはsupabase functions deployが自動実行されます
• 独立した検証環境: 各プルリクエストごとに独自のSupabase環境が構築されるため、他の開発に影響を与えず変更の検証が可能です

実際のプルリクエストワークフロー

1. 開発者がブランチを作成し、Supabaseに関連する変更を実装
2. プルリクエストを作成すると、自動的にSupabase Branchが生成される
3. Vercelのプレビュー環境が、そのプルリクエスト専用のSupabase Branchと連携
4. コードレビューと並行して、実際のSupabase環境での動作確認が可能
5. 必要に応じて、手動でSecrets設定やテストデータ投入
6. マージ後は、メインブランチのSupabase環境に変更が反映される
7. プロダクション用ブランチへのマージ後も、プロダクション用Supabase環境に変更が反映される

注意点

運用時には以下の点に注意が必要です：

• Secretsの手動設定: supabase secrets setは自動化されないため、Secrets依存の機能は手動設定が必要です
• テストデータの初期化: ブランチ環境のデータはseed.sqlの状態から始まるため、テストに必要なデータは事前に用意する必要があります

Edge FunctionをSupabase Branchにデプロイするための設定

supabase/config.tomlにデプロイしたいEdge Functionの設定を記入することで、プルリクエストに連動してEdge Functionも自動デプロイすることができます。
内容については、デフォルトのconfig.tomlにある記載例を参考にしてください。

# Use these configurations to customize your Edge Function.
[functions.MY_FUNCTION_NAME]
enabled = true
verify_jwt = true

Edge Function用のSecretsをSupabase Branchに反映したいとき

この記事を書いている時点において、Edge Function用のSecretsはBranchに自動反映されません。そのため、Secretsが必要になるEdge Functionの動作確認を行う場合は、別途の対応が必要です。

Secretsの反映は、Edge Function用の.envとsupabase cliを使って、一括登録することができます。

supabase cliのコマンドは、

> supabase secrets set --env-file supabase/functions/.env --project-ref $PROJECT_ID

になります。

※supabase/functions/.env は、適宜、利用している環境でのパスに置き換えてください。

上記の supabase cli コマンドを使って、適宜、必要なときにSecretsをデプロイしています。

Supabase Branchのデータは、seed.sqlの状態に初期化される

現在のところ、作成したSupabase Branch内のDBレコードは、seed.sqlの状態に初期化されます。

動作確認で入力したデータは、別のブランチに反映することができませんし、ブランチを再作成したときも初期化されるため残りません。必要な場合は、都度、seed.sqlに追加する必要があります。

ただ、用途によっては、別のブランチからデータをクローンして検証したいときがあるかもしれません。

公式のドキュメントには、
https://supabase.com/docs/guides/deployment/branching?queryGroups=making-updates&making-updates=remote-dev#branching-workflow

Branching workflow

Preview Branch instances contain no data by default.
You must include a seed file to seed your preview instance with sample
data when the Preview Branch is created.
Future versions of Branching may allow for automated data seeding and
cloning after we are confident that we can provide safe data masking.

とあるので、将来的に可能になるかもしれません。

まとめ

この記事では、Supabase BranchingのPersistentブランチを活用した環境構築と運用方法について解説しました。ポイントをまとめると：

• Supabase BranchingはGitHubとの連携により、プルリクエストごとに独立したDBブランチを作成できる機能
• Persistentブランチを使うことで、development環境などの結合環境向けに安定したブランチを維持できる
• VercelのIntegrationと連携することで、フロントエンドとバックエンドの環境を一貫して管理可能
• DBスキーマの変更やEdge Functionのデプロイが自動化され、運用効率が向上
• 現時点では、Edge Function用のSecretsの設定は手動対応が必要

特に、Persistentブランチの設定では、以下の点に注意が必要です：

1. 連携時にPersistentへ変更することを忘れない
2. config.tomlへのremotes設定を忘れない
3. Vercel環境変数の初期設定を適切なブランチのものに更新する

Supabase Branchingの利用により、「他の開発に影響を与えずに検証できる」という大きなメリットを得られます。特に開発している内容のデモや確認を行うさいに、安全かつ効率的な開発フローを実現できると思います。

今後、Secretsやデータのクローンなどにおいても発展し、さらに使いやすくなることを期待しています。

応募待っています

WEBエンジニア募集中です！医療業界での経験や３Dの知見は問いません。Berryの考え方や製品に少しでも興味が持てた方はお気軽に応募下さい。
https://www.wantedly.com/projects/2023878