SupabaseをGitHub Actions×GCSで無料自動バックアップする手順

Supabase の Free プランを使って個人開発や小規模な Web アプリを運用していると、データベースの自動バックアップ機能が付いていないことに気づきます。意図しないデータ削除やマイグレーションの失敗に備えるには、自前で定期バックアップの仕組みを用意しておく必要があります。

とはいえ、バックアップのためだけに常設サーバーを立てたり、サービスアカウントの JSON 秘密鍵を GitHub に長期保管したりするのは、コスト面でもセキュリティ面でも避けたいところです。

この記事では、GitHub Actions と Google Cloud Storage(GCS)の Always Free 枠を組み合わせ、JSON 秘密鍵を使わない Workload Identity Federation(WIF)認証で Supabase のデータを毎日無料バックアップする手順を解説します。筆者の環境で実際に構築・運用する中で踏んだ IPv6 接続エラーや CLI フラグ変更の対処法もあわせて紹介します。

この記事で行うこと

この記事では、以下の流れで日次自動バックアップ環境を構築します。

  • Google Cloud Storage(us-west1)に無料枠向けのバケットを作成し、パス別の自動削除ルールを設定する
  • Workload Identity Federation(WIF)を設定し、JSON 秘密鍵なしで GitHub Actions から GCS へアップロードできるようにする
  • Supabase の Session pooler 接続 URL を取得し、GitHub Secrets に登録する
  • GitHub Actions のワークフロー(backup.yml)を作成し、手動テストと日次実行を確認する

前提条件・構成の全体像

本記事の手順を進めるにあたり、以下の環境・アカウントを前提としています。

項目内容
SupabaseFree プラン以上のプロジェクト(接続パスワードがわかる状態)
GitHubバックアップ用 Private リポジトリ(GitHub Actions が利用可能)
Google Cloud請求先アカウントが有効なプロジェクト(Always Free 枠利用)
作業端末gcloud CLI が実行できる環境(Cloud Shell でも可)

今回の構成では、各アプリのリポジトリにデータベースの接続情報を分散させないため、バックアップ専用の Private リポジトリを1つ用意し、複数アプリ・複数スキーマのバックアップを集約する設計としています。

注意点

構築を始める前に、以下の3点をあらかじめ把握しておいてください。

  • supabase db dump でバックアップできるのは PostgreSQL データベース(スキーマ定義やテーブルデータ)のみであり、Supabase Storage に保存した画像やファイルは含まれません
  • データベースパスワードは Supabase ダッシュボード上で後から再表示できないため、不明な場合は事前にリセット・再発行が必要です
  • 本記事のコマンド例や YAML に含まれる <PROJECT_ID> や <BUCKET_NAME> などのプレースホルダーは、ご自身の環境の値に置き換えて実行してください

手順1:GCS バケット作成とパス別ライフサイクル設定

まずはバックアップファイルの保存先となる GCS バケットを作成します。Google Cloud の Always Free 枠(月間 5 GB-months の Standard ストレージ)を適用するため、対象リージョンである us-west1(オレゴン)、us-central1(アイオワ)、us-east1(サウスカロライナ)のいずれかを指定します。

以下のコマンドをターミナル(または Cloud Shell)で実行し、公開アクセスを完全にブロックしたバケットを作成します。

gcloud storage buckets create gs://<BUCKET_NAME> \
  --project=<PROJECT_ID> \
  --location=us-west1 \
  --default-storage-class=STANDARD \
  --uniform-bucket-level-access \
  --public-access-prevention

次に、古いバックアップが溜まって 5 GB の無料枠を超えないよう、ライフサイクルルール(自動削除)を設定します。複数のアプリを1つのバケットにまとめつつ、第1階層のプレフィックス(フォルダ相当)ごとに保持日数を分けたい場合は、matchesPrefix 条件を使います。

lifecycle.json というファイルを作成し、以下の内容を記述します。たとえば app-a/ 配下は 30 日、app-b/ 配下は 90 日で自動削除する設定例です。

{
  "rule": [
    {
      "action": {
        "type": "Delete"
      },
      "condition": {
        "age": 30,
        "matchesPrefix": ["app-a/"]
      }
    },
    {
      "action": {
        "type": "Delete"
      },
      "condition": {
        "age": 90,
        "matchesPrefix": ["app-b/"]
      }
    }
  ]
}

matchesPrefix には gs://<BUCKET_NAME>/ や先頭の / を含めない点に注意してください(なお、ルート要素を {"lifecycle": {"rule": [...]}} で囲む形式でも同様に適用できます)。作成したら、以下のコマンドでバケットに適用します。

gcloud storage buckets update gs://<BUCKET_NAME> --lifecycle-file=lifecycle.json

設定後、gcloud storage buckets describe gs://<BUCKET_NAME> --format="default(lifecycle_config)" を実行してルールが反映されていれば完了です。

手順2:Workload Identity Federation で鍵レス認証を設定

GitHub Actions から GCS へファイルをアップロードする際、サービスアカウントの JSON 秘密鍵を発行して Secrets に保存する方法は漏洩時のリスクが高くなります。今回は Google Cloud 推奨の Workload Identity Federation(WIF)を使い、秘密鍵レスかつ対象バケット・対象リポジトリのみに権限を絞って連携します。

まず、バックアップ専用のサービスアカウントを作成し、手順1で作成したバケットに対してのみオブジェクトの作成・管理権限(roles/storage.objectUser)を付与します。

gcloud iam service-accounts create supabase-backup-sa \
  --project=<PROJECT_ID> \
  --display-name="Supabase Backup Service Account"

gcloud storage buckets add-iam-policy-binding gs://<BUCKET_NAME> \
  --member="serviceAccount:supabase-backup-sa@<PROJECT_ID>.iam.gserviceaccount.com" \
  --role="roles/storage.objectUser"

続いて、Workload Identity Pool と GitHub 用の OIDC プロバイダを作成し、指定した GitHub リポジトリからの実行のみを許可します。<GITHUB_ORG>/<REPO_NAME> には作成したバックアップ用リポジトリを指定してください。

gcloud iam workload-identity-pools create github-actions-pool \
  --project=<PROJECT_ID> \
  --location="global" \
  --display-name="GitHub Actions Pool"

gcloud iam workload-identity-pools providers create-oidc github-provider \
  --project=<PROJECT_ID> \
  --location="global" \
  --workload-identity-pool="github-actions-pool" \
  --display-name="GitHub Provider" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
  --attribute-condition="assertion.repository=='<GITHUB_ORG>/<REPO_NAME>'"

最後に、作成した Pool 経由のアクセスに対してサービスアカウントの借用権限(roles/iam.workloadIdentityUser)を紐づけます。<PROJECT_NUMBER> は gcloud projects describe <PROJECT_ID> --format="value(projectNumber)" で確認できます。

gcloud iam service-accounts add-iam-policy-binding \
  "supabase-backup-sa@<PROJECT_ID>.iam.gserviceaccount.com" \
  --project=<PROJECT_ID> \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/github-actions-pool/attribute.repository/<GITHUB_ORG>/<REPO_NAME>"

これで Google Cloud 側の認証設定は完了です。

手順3:Supabase Session pooler の接続 URL を登録

次に、GitHub Actions から Supabase へ接続するための URL を取得します。ここが実運用で最もつまずきやすいポイントです。

Supabase のダッシュボードで「Connect」画面を開くと複数の接続方式が表示されますが、GitHub Actions から実行する場合は必ず「Session pooler」(ポート 5432)の接続文字列を選んでください。

接続方式ポートIP バージョンGitHub Actions での利用
Direct connection5432IPv6(IPv4 は有料)非推奨(接続不可になりやすい)
Transaction pooler6543IPv4非推奨(pg_dump に不向き)
Session pooler5432IPv4推奨(そのまま接続可能)

Direct connection(db.<project-ref>.supabase.co)はデフォルトで IPv6 専用となっているため、IPv4 ベースの一般的な GitHub Actions ランナーから接続するとエラーになります。一方、Session pooler(*.pooler.supabase.com:5432)は全プランで IPv4 に対応しており、セッションを維持する仕組みのため pg_dump ベースのバックアップも安定して動作します。

取得した接続文字列の [YOUR-PASSWORD] 部分を実際のデータベースパスワードに置き換え、GitHub リポジトリの「Settings」→「Secrets and variables」→「Actions」から、SUPABASE_DB_URL という名前で Repository secrets に登録しておきます。なお、パスワードに @ や #、/ などの特殊文字が含まれている場合は URL エンコード(%40 など)が必要になるため、英数字のみのパスワードを発行しておくとトラブルを防げます。

GitHub Actions の Secrets と Variables の詳しい設定手順や使い分けについては、以下の記事も参考にしてください。

手順4:GitHub Actions ワークフローの作成とテスト実行

バックアップ用リポジトリに .github/workflows/backup.yml を作成します。以下の例では、毎日 JST 03:00(UTC 18:00)に自動実行し、strategy.matrix で複数のスキーマ(アプリ)を並列バックアップできるようにしています。

name: Supabase Daily Backup to GCS

on:
  schedule:
    - cron: '0 18 * * *'
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

jobs:
  backup:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        schema:
          - app-a
          - app-b

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Supabase CLI
        uses: supabase/setup-cli@v3
        with:
          version: latest

      - name: Set JST timestamp
        id: date
        run: echo "jst_date=$(TZ='Asia/Tokyo' date +'%Y%m%d_%H%M%S')" >> $GITHUB_OUTPUT

      - name: Dump Supabase schema and data (${{ matrix.schema }})
        id: dump
        env:
          SUPABASE_DB_URL: ${{ secrets.SUPABASE_DB_URL }}
        run: |
          SCHEMA_NAME="${{ matrix.schema }}"
          TS="${{ steps.date.outputs.jst_date }}"
          SCHEMA_FILE="${SCHEMA_NAME}_${TS}_schema.sql"
          DATA_FILE="${SCHEMA_NAME}_${TS}_data.sql"
          ARCHIVE_FILE="${SCHEMA_NAME}_${TS}.tar.gz"

          supabase db dump --remote="$SUPABASE_DB_URL" --schema "$SCHEMA_NAME" -f "$SCHEMA_FILE"
          supabase db dump --remote="$SUPABASE_DB_URL" --schema "$SCHEMA_NAME" --data-only --use-copy -f "$DATA_FILE"
          tar -czf "$ARCHIVE_FILE" "$SCHEMA_FILE" "$DATA_FILE"
          echo "archive=${ARCHIVE_FILE}" >> $GITHUB_OUTPUT

      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/github-actions-pool/providers/github-provider
          service_account: supabase-backup-sa@<PROJECT_ID>.iam.gserviceaccount.com

      - name: Upload backup to GCS
        uses: google-github-actions/upload-cloud-storage@v3
        with:
          path: ${{ steps.dump.outputs.archive }}
          destination: <BUCKET_NAME>/${{ matrix.schema }}
          parent: false

supabase db dump でスキーマ定義と実データ(--data-only --use-copy)を分けて出力し、tar -czf で圧縮することで GCS の 5 GB 無料枠を節約しています。また、upload-cloud-storage に parent: false を指定しているため、余計なディレクトリ階層を作らずバケット内の <SCHEMA_NAME>/ 直下に .tar.gz ファイルが保存されます。

ファイルをプッシュしたら、GitHub リポジトリの「Actions」タブから「Supabase Daily Backup to GCS」を開き、「Run workflow」ボタンで手動実行します。すべてのステップが緑色の成功表示になり、GCS バケットの該当フォルダ配下にアーカイブファイルが生成されていれば構築完了です。

うまくいかない場合の確認ポイント

筆者の環境で初回テスト時に実際に遭遇したエラーを中心に、代表的な対処法をまとめます。

Network is unreachable で supabase db dump が失敗する

GitHub Secrets の SUPABASE_DB_URL に Direct connection(db.<project-ref>.supabase.co:5432)を登録している場合、IPv6 接続に対応していない GitHub Actions ランナーでは以下のようなエラーが出力されて失敗します。

pg_dump: error: connection to server at "db.<project-ref>.supabase.co" (<IPv6_ADDRESS>), port 5432 failed: Network is unreachable
	Is the server running on that host and accepting TCP/IP connections?
error running container: exit 1
Your network does not support IPv6, which is required for direct connections to the database.
Retry with your project's IPv4 transaction pooler connection string via --remote=<db-url>.
You can copy it from the dashboard under Connect > Transaction pooler.
##[error]Process completed with exit code 1.

このエラーが出た場合は、手順3のとおり IPv4 で接続できる Session pooler(*.pooler.supabase.com:5432)の接続文字列へ差し替えて再実行してください(ログの案内には Transaction pooler と表示されますが、pg_dump のような単一セッション処理にはポート 5432 の Session pooler を使用するのが確実です)。

--db-url が非推奨(deprecated)という警告やエラーが出る

古い記事のサンプルを参考にして --db-url オプションを指定すると、実行ログに以下のような警告が出力されます。

Warning: --db-url is deprecated and will be removed in v4. Use --remote=<db-url> instead, or --remote=<project-ref> with an access token set

Supabase CLI v3 以降では --db-url や --linked フラグが非推奨となり、接続先を指定するオプションが --remote に統一されています(v4 で削除予定)。ワークフローのように --remote="$SUPABASE_DB_URL" と記述することで警告を解消できます。

google-github-actions/auth で権限エラーになる

WIF 連携が失敗する場合は、まずワークフロー内の permissions に id-token: write が記載されているか確認してください。あわせて、attribute-condition や add-iam-policy-binding で指定した <GITHUB_ORG>/<REPO_NAME> の大文字・小文字が実際のリポジトリ名と完全一致しているかも見直すと解決しやすいです。

スケジュール時刻どおりに実行されない・定期実行が止まる

GitHub Actions の schedule(cron)トリガーは、GitHub 側の負荷状況によって指定時刻から数分〜数十分ほど遅延して実行されることがあります。また、リポジトリに 60 日間一度もコミットや手動実行などのアクティビティがない場合、スケジュール実行が自動的に無効化される仕様があるため、定期的に Actions タブの状態を確認するか、監視仕組みと併用することをおすすめします。

元に戻す方法・リストアの基本

万が一バックアップ構成が不要になった場合は、GitHub リポジトリから .github/workflows/backup.yml を削除(または無効化)し、必要に応じて GCS バケットと作成したサービスアカウントを削除することで元の状態に戻せます。

バックアップファイルからデータを復元したい場合は、GCS から対象の .tar.gz ファイルをローカル環境へダウンロードして解凍し、psql コマンド等で接続先の Supabase(Session pooler URL)へ schema.sql と data.sql を順番に適用します。

gcloud storage cp gs://<BUCKET_NAME>/app-a/app-a_20261115_030000.tar.gz .
tar -xzf app-a_20261115_030000.tar.gz

psql "<SESSION_POOLER_URL>" -f app-a_20261115_030000_schema.sql
psql "<SESSION_POOLER_URL>" -f app-a_20261115_030000_data.sql

復元作業は既存データを上書き・競合させる可能性があるため、本番環境へ適用する前にテスト用プロジェクトやローカル環境で一度検証しておくことをおすすめします。

よくある質問

バックアップ対象のスキーマを追加したいときはどうすればよいですか?

backup.yml の strategy.matrix.schema のリストに新しいスキーマ名を1行追加してプッシュするだけで対応できます。lifecycle.json 側にも新しいプレフィックスのルールを追記しておけば、アプリごとに異なる保持期間を適用できます。

GCS の無料枠(5 GB)を超えそうになった場合はどうなりますか?

テキストベースの SQL ダンプは tar.gz 圧縮すると非常に小さくなるため、個人開発規模であれば 90 日分を保持しても数 MB〜数十 MB 程度に収まるケースが大半です。ただしレコード数が急増するアプリでは容量が増えるため、保持日数(age)を短く調整するか、Google Cloud の予算アラートを設定しておくと安心です。

public スキーマをバックアップしたい場合もこの手順で使えますか?

はい、matrix.schema に public を指定すれば利用できます。ただし、Supabase 側で管理されている拡張機能や内部オブジェクトとの関係でリストア時に注意が必要な場合があるため、運用しているアプリに合わせてテスト復元を確認しておくと確実です。

まとめ

Supabase の Free プランには公式の自動バックアップがありませんが、GitHub Actions と Google Cloud Storage の Always Free 枠を組み合わせることで、コストを抑えながら安全な日次バックアップ体制を構築できます。

特に、Workload Identity Federation による秘密鍵レス認証と、matchesPrefix を使った単一バケットでのパス別ローテーション、そして IPv4 環境での Session pooler 接続の3点を押さえておけば、後からの保守も非常に楽になります。個人開発や検証環境の大切なデータを守る仕組みとして、ぜひ取り入れてみてください。

次に読むおすすめ記事

フロントエンド側(Next.js / Vercel)の障害対策や、Supabase の無料枠・セキュリティ確認についてさらに詳しく知りたい方は、以下の記事もあわせて参考にしてください。

Next.jsをVercelとCloudflare Workersで冗長化する手順
Next.js アプリケーションを個人開発や小規模な業務システムで運用する際、デプロイ先として Vercel を選んでいる方は多いのではないでしょうか。GitHub と連携してプッシュするだけで公開できる手軽さは大きな魅力ですが、ホスティン...
【2026年版】個人開発の無料DB比較|Supabase・Neon等の無料枠と選び方
個人開発を始める際、誰もが一度は頭を悩ませるのが「データベースをどれにするか」という選定問題です。できれば完全無料で使い続けたいものの、インフラ設定に時間をかけたくない、あるいは久しぶりにポートフォリオを開いたらデータベースがスリープしてい...
【解決】Supabaseで42501エラー?Data API仕様変更とGRANT設定
Supabaseを利用しているプロジェクトにおいて、クライアントライブラリ(supabase-js)やREST API、GraphQL経由でデータを取得・更新しようとした際に「42501」や「permission denied for ta...
Supabaseの不正アクセス調査方法|Auth・DB・APIログとRLSの確認
Firebaseの代替となるオープンソースBaaS(Backend as a Service)として、個人開発やスタートアップで圧倒的な人気を誇るのがSupabaseです。PostgreSQLの強力なリレーショナル機能に加え、認証(Auth...

参考情報