Supabase CLI で Supabase ローカル環境をセットアップする（Docker Desktop + macOS）

macOS で Supabase CLI を使ってローカル開発環境をセットアップする方法をご紹介します。

Supabase CLI とは

Supabase CLI は、ローカル環境での Supabase 開発を可能にするコマンドラインツールです。ローカルデータベースの起動、マイグレーション管理、型生成などに使用します。

ローカル環境で開発することで、本番環境に影響を与えずに安全に開発・テストができます。

前提条件

Supabase CLI を使用するには、以下が必要です。

macOS
Homebrew: パッケージマネージャー
Docker Desktop: Supabase のローカル環境は Docker コンテナで動作します

Docker Desktop のセットアップ

Supabase CLI はローカル環境を Docker コンテナで起動するため、事前に Docker Desktop のインストールと設定が必要です。

インストール

Docker Desktop 公式サイトから macOS 版をダウンロードしてインストールします。

または Homebrew でインストールすることもできます。

brew install --cask docker

動作確認

インストール後、Docker Desktop を起動し、ターミナルで動作を確認します。

docker --version
# Docker version 27.x.x, build xxxxxxx
 
docker ps
# CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES

docker ps でエラーが出なければ、Docker は正常に動作しています。

Supabase CLI のインストール

macOS では Homebrew を使用してインストールします。

Note: npm でのグローバルインストール（npm install -g supabase）はサポートされていません。Homebrew を使用してください。

# Supabase CLI をインストール
brew install supabase/tap/supabase
 
# バージョン確認
supabase --version

アップデート

Supabase CLI を最新版にアップデートするには以下のコマンドを実行します。

brew upgrade supabase

ローカル環境のセットアップ

1. プロジェクトの初期化

プロジェクトディレクトリで Supabase を初期化します。

# プロジェクトディレクトリに移動
cd your-project
 
# Supabase プロジェクトを初期化
supabase init

supabase init を実行すると、supabase/ フォルダが生成されます。このフォルダはバージョン管理に含めることができます。

2. ローカル環境の起動

以下のコマンドでローカル Supabase を起動します。

supabase start

初回起動時は Docker イメージのダウンロードがあるため、数分かかることがあります。

起動が完了すると、以下のような情報が表示されます。

Started supabase local development setup.
 
         API URL: http://127.0.0.1:54321
     GraphQL URL: http://127.0.0.1:54321/graphql/v1
  S3 Storage URL: http://127.0.0.1:54321/storage/v1/s3
          DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
      Studio URL: http://127.0.0.1:54323
    Inbucket URL: http://127.0.0.1:54324

3. Supabase Studio へのアクセス

ブラウザで http://127.0.0.1:54323 にアクセスすると、Supabase Studio が表示されます。これは Supabase のグラフィカルインターフェースで、テーブルの作成やデータの確認、SQL の実行などが行えます。

4. ローカル環境の停止

開発が終わったら、以下のコマンドでローカル環境を停止します。

supabase stop

データを保持したまま停止する場合は、そのまま supabase stop を実行します。データをリセットして停止したい場合は --no-backup オプションを使用します。

# データをリセットして停止
supabase stop --no-backup

よく使うコマンド

コマンド	説明
`supabase init`	プロジェクトの初期化
`supabase start`	ローカル環境の起動
`supabase stop`	ローカル環境の停止
`supabase status`	ローカル環境の状態確認
`supabase db reset`	データベースのリセット
`supabase migration new <name>`	新しいマイグレーションファイルの作成
`supabase gen types typescript`	TypeScript の型定義を生成

トラブルシューティング

supabase: command not found

原因: Supabase CLI がインストールされていない、または PATH が通っていない

解決策:

# Homebrew で再インストール
brew install supabase/tap/supabase
 
# PATH を確認
which supabase

Docker daemon is not running

原因: Docker が起動していない

解決策:

# Docker Desktop を起動
open /Applications/Docker.app
 
# Docker の起動確認
docker ps

Error: Cannot connect to the Docker daemon

原因: Docker が正常に動作していない

解決策:

# Docker Desktop を再起動
# メニューバーの Docker アイコンから「Restart」を選択
 
# 再度確認
docker ps
supabase start

ポートが既に使用されている

原因: 他のプロセスが同じポートを使用している

解決策:

# 使用中のポートを確認（例: 54321）
lsof -i :54321
 
# 該当プロセスを終了するか、Supabase の設定でポートを変更

supabase/config.toml でポート番号をカスタマイズできます。

まとめ

Supabase CLI を使えば、ローカル環境で完全な Supabase スタックを動かすことができます。本番環境と同等の機能をローカルで試せるため、開発効率が大幅に向上します。

Docker Desktop と Homebrew さえあれば、数分でセットアップが完了するので、ぜひ試してみてください。

詳細は Supabase CLI 公式ドキュメントを参照してください。

以上、Supabase CLI でローカル環境をセットアップした、現場からお送りしました。