Supabase CLIの使い方完全ガイド｜無料枠で始める環境構築とマイグレーション

データベースのスキーマ不整合や本番環境への予期せぬ影響を防ぐには、ローカル環境の構築が不可欠です。Supabase CLIを活用すれば、クラウド上の本番データに触れることなく、手元に安全な開発環境を立ち上げ、マイグレーションをコードベースで管理できます。

本記事では、CLIのインストール手順からマイグレーション機能の使い方、CI/CDとの連携方法を具体的に解説します。さらに、開発初期の検証をローカルで完結させ、Supabaseの無料枠を最大限に活用するコスト最適化のノウハウも紹介します。

Supabase CLIによるローカル環境構築のメリット

Supabase CLIは、手元のPCに本番環境と同等のデータベースを素早く立ち上げられる強力なツールです。クラウド上のGUI操作に頼らず、コードベースでデータベースのスキーマ変更を管理できます。

CLIを導入すべき最大の理由は、チーム開発における「再現性」と「バージョン管理」の確保です。複数人のエンジニアが関わる開発でも競合を防ぎ、CI/CDパイプラインへの組み込みも容易になります。CI/CDの基本については CI/CDとは？導入メリットと主要ツール比較、3ステップでわかる実践ガイド も参考にしてください。

運用時の注意点として、Supabase CLIを動かすためにはDockerの事前インストールが必須です。チームメンバー全員のローカル環境を整え、プロジェクト内で使用するCLIのバージョンを統一するルールを設けましょう。Docker環境の構築については Docker Desktopとは？Windows環境での開発効率を劇的に上げる導入ガイド を参照してください。

クラウド連携とチーム開発の最適化

ローカル環境で開発を進める最大のメリットは、本番データに影響を与えずに安全かつ高速にテストを行える点です。特にスピードが求められるプロダクト開発初期では、ローカルでの試行錯誤を前提としたフロー構築が推奨されます。

複数人で開発を進める場合、データベースのスキーマ変更がコンフリクトするリスクが伴います。コマンドラインから生成されたマイグレーションファイルは、必ずGitなどのバージョン管理システムにコミットしてください。

マイグレーションファイルをGitで管理することで、スキーマ不整合による手戻りを大幅に削減できます。初期設定の段階でデータベースの運用方針を明確にし、本番環境への移行を見据えた設計を行うことが重要です。

Supabase CLIのインストールと環境構築手順

開発をスムーズに始めるためには、適切な方法でツールをインストールする必要があります。Mac環境であればHomebrew、WindowsやLinuxであればnpmやScoopを利用するのが一般的です。

プロジェクト単位でのインストールを推奨

個人の検証目的であればグローバルインストールでも問題ありません。しかし、チーム開発においてはプロジェクトの package.json に依存関係として追加することを推奨します。これにより、開発メンバー間でバージョンの差異による予期せぬエラーを防ぐことができます。

npmを使用する場合の具体的なインストールコマンドは以下の通りです。

npm install supabase --save-dev

インストール後、以下のコマンドを実行してプロジェクトを初期化し、ローカル環境を立ち上げます。

# プロジェクトの初期化
npx supabase init

# ローカル環境のコンテナ起動（Dockerが立ち上がっている必要があります）
npx supabase start

環境変数の分離とセキュアな運用

ローカル環境と本番環境でシークレットキーなどの環境変数が混ざらないよう、設定ファイルの取り扱いには細心の注意を払ってください。ローカルと本番の認証情報を厳格に切り分けることで、セキュアな運用が可能になります。

ローカル版Supabase Studioの効果的な活用

コマンドラインツールを使用してローカル環境を立ち上げると、クラウド版と同等の機能を持つSupabase Studioがローカルのブラウザ上で利用できます。データベースのテーブル構造や格納されているレコードを直感的なUIで確認することが可能です。

エンジニアリングチームの生産性を高めるためには、CUIとGUIの役割分担を明確にすることが重要です。スキーマの変更履歴はコードとして残し、データの状態確認にはGUIを利用するといった使い分けが求められます。

注意点として、GUI上から直接テーブルの追加やカラムの変更を行うと、マイグレーションファイルに変更が記録されません。テーブル定義の変更は必ずCLIを通じて実行し、Supabase Studioはデータ確認やモックデータ投入に限定する運用ルールを徹底してください。

Supabase CLIを用いたマイグレーション管理

ローカル環境で構築したデータベース構造を本番環境へ正確に反映させるために、マイグレーション機能は欠かせません。手動でSQLを実行する運用から脱却し、インフラのコード化を実現することが安定した開発基盤を築く第一歩です。

具体的には、Supabase CLIの migration コマンドを活用して、変更内容をSQLファイルとして生成・適用します。1つの機能追加やバグ修正ごとにファイルを分けることで、後から変更履歴を追いやすくなります。

マイグレーションファイルの生成と適用手順

テーブルを追加する際など、新しいマイグレーションファイルを作成するには以下のコマンドを実行します。

npx supabase migration new create_users_table

コマンドを実行すると、supabase/migrations/ ディレクトリ内にタイムスタンプ付きのSQLファイル（例: 20260416120000_create_users_table.sql）が生成されます。このファイルに具体的なスキーマ変更を記述します。

マイグレーションファイルのサンプル（usersテーブル作成）

-- supabase/migrations/20260416120000_create_users_table.sql
create table public.users (
  id uuid primary key default gen_random_uuid(),
  email text not null unique,
  created_at timestamp with time zone default timezone('utc'::text, now()) not null
);

ファイルを編集後、ローカルデータベースにマイグレーションを適用して動作確認を行います。

# ローカルDBをマイグレーションファイルから再構築して適用（ローカル専用）
npx supabase db reset

注意: supabase db reset はローカル環境の DB を完全にリセットし、すべてのマイグレーションを再適用します。本番環境には使用しないでください。本番（リモート）プロジェクトへマイグレーションを適用する場合は、supabase db push を使用します。

# リモートの本番プロジェクトへマイグレーションを適用（本番用）
npx supabase db push

複数人が同時にスキーマを変更すると、マイグレーションファイルの適用順序に矛盾が生じる可能性があります。Gitのブランチごとに整合性を確認するフローを定着させ、本番適用前には必ずローカルやステージング環境で動作確認を行ってください。

Supabaseの無料枠を最大限に活用するコスト最適化

Supabase CLIを活用する大きなメリットは、ローカル環境を構築することでクラウドリソースを消費せず、Supabaseの無料枠を有効活用できる点です。クラウド上のプロジェクトに直接依存せずに開発を進められるため、コスト最適化に直結します。

Supabase Freeプランの主な制限（2026年時点）

項目	上限
プロジェクト数	2プロジェクト
データベース容量	500 MB
ストレージ容量	1 GB
月間アクティブユーザー（MAU）	50,000 MAU
エッジファンクション	500,000 回/月
帯域幅	5 GB/月

クラウド環境を直接操作して開発を行うと、意図しないAPIコールやデータベース容量の超過により、無料枠の上限に達してしまうリスクがあります。手元のPC上でデータベース設計やエッジファンクションの検証を行うことで、無駄なリソース消費を防ぐことができます。

無料枠の制限を正しく理解し、ローカルでの検証プロセスをチーム全体で定着させることが重要です。特に複数プロジェクトを同時進行している場合は、不要なクラウドプロジェクトを定期的に整理することで、無料枠の上限を効果的に管理できます。

本番環境へのデプロイとCI/CD連携

ローカルで作成したマイグレーションファイルを、リモートプロジェクトへ安全に反映させる仕組みはチーム開発において不可欠です。小規模なプロトタイプ開発であれば手動コマンドでも十分ですが、中規模以上のプロジェクトではCI/CD環境の構築が推奨されます。

GitHub Actionsなどを利用してデプロイを自動化することで、人為的なミスを防ぎ、開発効率を大幅に向上させることが可能です。ワークフローファイル内で supabase db push --linked を実行することで、PRマージのタイミングで自動的にマイグレーションを本番環境へ適用できます。

本番環境へデプロイする前には、必ずステージング環境でテストを実行し、データベースの整合性が保たれているかを確認してください。本番データベースへの直接的な変更は避け、常にバージョン管理されたファイルを経由する運用ルールを徹底しましょう。

よくある質問（FAQ）

Supabase CLIは無料で利用できますか？

はい、利用可能です。ローカル環境の構築自体は完全に無料であり、手元のPCのリソースを使用するため、Supabaseのクラウド側の無料枠（Freeプラン）を消費しません。

Supabase CLIのインストールでよくあるエラーは？

Dockerが起動していない状態で npx supabase start を実行するとエラーになります。インストール後は必ずDocker Desktop等のデーモンが起動していることを確認してください。

`supabase db reset` と `supabase db push` の違いは？

supabase db reset はローカルのDBを完全にリセットしてすべてのマイグレーションを再適用するコマンドです。ローカル開発専用です。本番（リモート）プロジェクトへマイグレーションを適用する場合は supabase db push を使用します。誤って本番環境で db reset を実行すると、データが消失するリスクがあります。

マイグレーションファイルの競合を防ぐにはどうすればいいですか？

チーム内でSupabase CLIを用いたmigration運用を行う際は、同じテーブルに対する変更を複数人が同時に行わないよう、タスクの割り当てを明確にしてください。また、生成されたマイグレーションファイルは必ずGitでバージョン管理し、レビュープロセスを挟むことで競合を未然に防ぐことができます。

まとめ

本記事では、Supabase CLIを用いた開発効率の最大化について、ローカル環境構築からマイグレーション管理、無料枠の活用まで多角的に解説しました。CLIの導入は、チーム開発における再現性とバージョン管理を強化し、クラウドコストを抑えながら安全な開発を可能にします。

ローカルでの安全な検証、GUIに頼らないコードベースでの変更管理、そしてCI/CD連携によるスムーズなデプロイメントは、プロダクトの品質向上に不可欠です。特に supabase db reset（ローカル専用）と supabase db push（本番デプロイ用）を正しく使い分けることが、安全な運用の鍵となります。

まずはプロジェクト単位でのインストールから始め、チームに合ったマイグレーションの運用フローを構築してみてください。