😑

Supabase CLI の--password オプションバグを回避する

に公開
GitHub
GitHub Actions
Supabase
tech

はじめに

Supabaseは、PostgreSQLをベースにしたバックエンドサービスを手軽に構築できるプラットフォームです。私はGitHub Actionsを利用して、Supabase CLIを使った自動マイグレーションやデプロイメントを行っていました。しかし、CLI実行時にfailed SASL auth (invalid SCRAM server-final-message received from server)という認証エラーが発生し、原因を追求した結果、どうやら--passwordオプションに起因するバグであることが判明しました。この記事では、その問題の発生状況、原因調査、回避策の実装過程について共有します。

発生した問題

GitHub Actions上でSupabase CLIを実行する際、以下のように--passwordオプションを用いてパスワードを渡していました。

supabase link --project-ref $SUPABASE_PROJECT_ID --password "$SUPABASE_DB_PASSWORD"

しかし、実行すると次のエラーメッセージが表示されました。

failed to connect to postgres: failed to connect to ...: failed SASL auth (invalid SCRAM server-final-message received from server)

この認証エラーにより、マイグレーションやその他のデータベース操作が一切実行できない状態となりました。

原因調査

調査を進めると、GitHub上のSupabase CLIのIssue（例: #2347や#2360）に同様の報告があったことが分かりました。Issueの内容では、CLI内部でのフラグのバインディング処理に問題があり、--passwordオプションで指定されたパスワードが正しく認識されないことが原因とされています。

また、実際にCLI開発者からは「環境変数を利用する方法が推奨される」というアドバイスも寄せられていました。

回避策の実装

環境変数によるパスワード指定

上記Issueを踏まえ、CLI実行時にパスワードを直接コマンドラインオプションで渡すのではなく、環境変数 SUPABASE_DB_PASSWORD を利用する方法に変更しました。具体的には、GitHub Actionsのジョブ内で以下のように環境変数を設定しました。

env:
  SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}
  SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
  # 他の必要な環境変数もここで設定

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

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

  - name: Link Supabase project
    run: supabase link --project-ref $SUPABASE_PROJECT_ID

  - name: Run database migrations
    run: supabase db push

これにより、supabase link実行時に環境変数からパスワードが正しく読み込まれるようになり、認証エラーが解消されました。

結果

環境変数による指定に変更した後、GitHub Actions上での実行結果は以下のようになりました。

認証エラーの解消:
failed SASL auth のエラーがなくなり、正常にSupabase CLIがプロジェクトにリンクされ、データベースへの接続が成功しました。

その他の警告:
キーリング関連の警告（org.freedesktop.secrets のエラー）はヘッドレス環境での仕様であり、動作には影響がないため無視可能でした。

まとめ

今回の問題は、Supabase CLIの--passwordオプションに起因する既知のバグでした。原因調査の過程で、GitHub上のIssueを参照することで、環境変数SUPABASE_DB_PASSWORDを利用する回避策が推奨されていることを確認できました。GitHub Actionsのワークフローを環境変数対応に変更することで、認証エラーを解消し、マイグレーションも正常に実行できるようになりました。

Supabase CLIの今後のアップデートで本問題が正式に修正されることを期待しつつ、現状ではこの回避策が有効な方法となります。皆さんも同様の問題に直面した際は、環境変数の利用を検討してみてください。

Discussion