履歴
Supabase CLI のコマンド (v1.93.0) - Qiita
Supabase CLI のコマンド (v1.28.3) - Qiita
Supabase CLI のコマンド (v1.8.7) - Qiita
追記 2023/03/02
ドキュメントは開発者用ツールの重要な機能です。しかし、Supabaseでは2年間この機能に問題がありました。今日のリリースでそれを改善します。
感想：ドキュメントの整備が完了しました、AIによる質問もできてSupabaseのドキュメントを読み込ませたGPT-4で動いているとか、しらんけど。（未確認 3.5かも）
追記終了
追記 2023/02/23
現在 Supabase CLI v1.38.7
確認しただけでも
supabase migration repair
SQL Editorからのデータの読み込み
seed.sql
これらの挙動に変更がありました。
追記終了
Supabase CLI v1.28.3
更新日:2023年1月6日
前回の記事よりローカルとサーバーの同期がしやすくなりました。
dumpファイル化するコマンドはあるのに、このファイルを使ってRestoreするコマンドがないのはなぜなのか？
※ Supabase CLI
Breaking changes
https://github.com/supabase/cli/releases
※ Supabase CLIのupdate
scoop update supabase
重要コマンド
| コマンド | 説明 |
|---|---|
supabase start |
supabase コンテナ開始 |
supabase stop |
supabase コンテナ終了 |
supabase stop --backup |
supabase コンテナ終了＋スキーマやテーブル内のデータを保存 |
supabase db reset |
最後にマイグレーションした状態に戻す |
supabase db diff -f [ファイル名] |
ローカル側のスキーマの差分を新しいマイグレーションファイルに保存 |
supabase db diff --linked -f [ファイル名] |
サーバー側のスキーマの差分を新しいマイグレーションファイルに保存 |
supabase db remote commit -p [Database Password] |
サーバーのデータベースの変更から新しいマイグレーションファイルを作成 |
supabase db push -p [Database Password] |
新しいマイグレーションをサーバーのデータベースに送信し適用させる。 |
supabase db push -p [Database Password] --dry-run |
db push コマンドのリハーサル |
supabase migration list |
ローカルとサーバーのマイグレーションの状況がわかる |
supabase migration repair --status applied [タイムスタンプ] |
指定したマイグレーションを適用させる |
supabase migration repair --status reverted [タイムスタンプ] |
指定したマイグレーションを適用させる前の状態に戻す（＝無効化）させる。 |
重要コマンド一覧
supabase start
supabase stop
supabase stop --backup
supabase db reset
supabase db diff -f [ファイル名]
supabase db diff --linked -f [ファイル名]
supabase db remote commit -p [Database Password]
supabase db push -p [Database Password]
supabase db push -p [Database Password] --dry-run
supabase migration list
supabase migration repair --status applied [タイムスタンプ]
supabase migration repair --status reverted [タイムスタンプ]
scoop update supabase
環境
Windows 10
VScode
powershell
Docker Desktop
Supabase
Supabase CLI v1.28.3
※ ローカル（LOCAL）は自分のPC環境内にあるDocker上のSupabaseを指します。（以下ローカル）
Supabase プラットフォーム（REMOTE）はネット上にあるSupabaseダッシュボードから操作するSupabaseを指します。（以下サーバー）
※ 便利なVScode拡張機能
supabaseの設定ファイルの拡張子.toml
これはVScodeの拡張機能 Better TOML をインストールすると
supabase\config.tomlを綺麗に見ることが出来る
用語
マイグレーション
テーブルの新規作成、更新、削除などの情報を記録する行為。
通常はファイルに保存して、マイグレーションファイルを作る。
現在、複数のマイグレーションファイルをまとめるコマンドは無い。
※全部をやり直したい時は、ルート直下にあるsupabaseディレクトリを削除してsupabase initで可能。
スキーマ
SQL文のことを指す、マイグレーションファイルの中身はスキーマであり、
SQL文として実行するとテーブルなどが作成される。
もう少し詳しく書くと、スキーマはデータベースの構造を定義したもの。
テーブル、主キー、外部キー、データ型、データの大きさなどが決められている。
ダンプ
DB全体のバックアップを行うこと、そして出力したもの。
ダンプファイルを利用してDBを再現することをリストアという。
現在、supabase CLI にリストアコマンドが無い。（Supabase CLI v1.28.3 2023年1月5日）
同期
リモートとサーバーで衝突（conflict）が起きてない状態。
マイグレーションファイルなどを不用意に消したりするとこの同期が崩れ、
マイグレーション関連等のコマンドがエラーになる場合がある。
公式ドキュメント
CLI リファレンス
Supabase Documentation
https://supabase.com/docs/reference/cli/introduction
CLIの紹介
Supabase CLI | Supabase
https://supabase.com/docs/guides/resources/supabase-cli
ローカル開発
Local Development | Supabase
https://supabase.com/docs/guides/resources/supabase-cli/local-development
リリース情報 CLIの重大な変更等
Releases · supabase/cli
https://github.com/supabase/cli/releases
日本語 非公式ユーザーマニュアル | supabase
https://www.supabase.jp/docs/
※未翻訳あり。
Supabaseダッシュボード
ダッシュボードは、ローカルやWebブラウザ上からSupabaseをGUIで操作できる
サーバーのダッシュボード
https://app.supabase.com/
ローカルのダッシュボード
http://localhost:54323/
主なコマンド
supabase start
Supabase をローカルで実行。
supabase migration
データベースの移行を管理。
supabase db push
本番環境にリリースするための CI/CD。
supabase projects
Supabase プロジェクトの管理。
supabase gen types
データベース スキーマから型を直接生成。
TypeScript 型を生成する。コミュニティがサポートしている。
supabase completion
シェルのオートコンプリート機能
開発環境の構築
Docker の実行環境
Docker Desktopをインストール
Docker Desktop - Docker
https://www.docker.com/products/docker-desktop/
Docker Desktopを立ち上げておくと
ローカルでsupabase を立ち上げられるようになる。
supabase start
を実行すると、
必要なイメージをダウンロードしてsupabase が実行される。
※現在はこのコマンド1つでsupabase コンテナがノーコンフィグで立ち上がる。
supabase CLIのインストール
supabase/cli: Supabase CLI
https://github.com/supabase/cli
supabase CLIのインストール (powershell)
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
アップデート
scoop update supabase
※ 更新が早いので1-2週間に1度は実行を推奨します。
グローバルフラグ
すべてのコマンドで使えるフラグ
--debug
標準出力にエラーログを出力する
--experimental
実験的機能を有効化する。
-h, --help
そのコマンドのヘルプを表示
--workdir
supabase のプロジェクトディレクトリを指定する。
複数のsupabase プロジェクトがあっても、
どこからでも指定して実行可能になる。
（通常はRoot下のディレクトリからコマンドを実行する。）
初期接続設定
ログインをする
supabase login
開発初期の最初に1回だけ実行する
※アクセストークンを要求される、アクセストークンは
https://app.supabase.com/account/tokens
こちらで取得する。
今回はNext.jsのプロジェクトを作ってそこにsupabase を利用できるようにする。
（supabase は独立しているので、CLIコマンドはNext.jsに一切依存しない、OSやエディター、シェル等には関わっている。）
Next.jsでプロジェクトを作成
適当な場所で
yarn create next-app my-supabase -project
cd my-supabase -project
最新のNext.js
npm i next@latest react@latest react-dom@latest eslint-config-next@latest
ローカルでsupabase を使う
ローカルでのsupabase を初期化
supabase init
プロジェクトを作った最初に実行する。
実行例
たとえば、Next.js をインストール後このコマンドを実行します。
そうするとルート直下にsupabase ディレクトリが作られます。
この中に、supabase の設定ファイルや、マイグレーションファイルが作成されます。
ローカルでのsupabase を起動
supabase start
※2つ以上のプロジェクトはエラーになる。
2箇所同時にsupabase startコマンドは実行できず、エラーになる。
ローカルのsupabase への接続情報を表示
supabase status （デフォルト）
supabase status -o env
supabase status -o json
supabase status -o pretty （デフォルトと同じ）
supabase status -o toml
supabase status -o yaml
-o オプション
出力先の指定
それぞれの形式で出力される
--override-name オプション
使用例
supabase status -o env --override-name api.url=NEXT_PUBLIC_supabase _URL
結果（一部抜粋）
NEXT_PUBLIC_supabase _URL="http://localhost:54321"
と出力される。
これはシェルでプログラムを組んで
自動的に.envファイルを作成する場合などに使用する・・などが想定される。
> supabase status
supabase local development setup is running.
API URL: http://localhost:54321
DB URL: postgresql://postgres:postgres@localhost:54322/postgres
Studio URL: http://localhost:54323
Inbucket URL: http://localhost:54324
JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
anon key: eyJh*****************************************************************************
*****************************************************************************_I0
service_role key: eyJhb**********************************************************************************
**********************************************************************************n3W0YpN81IU
ローカルでのsupabase を停止
supabase stop
ローカルのsupabaseを停止する。
※テーブルや登録したデータ等は保存されない。
保存したい場合は
backupオブションを使用するか
diffコマンドでマイグレーションファイルに保存する必要がある。
supabase stop --backup
バックアップオプションをつけたコマンド
テーブルの変更などをマイグレーションファイルにしていなくても、
バックアップオプションを利用する事で保存される。
アクセス サービス
supabase内のPostgresにアクセスする方法
任意の Postgres クライアント(＝DBクライアント)を使用、または API ゲートウェイ ( Kong )を介してサービスに直接アクセスできます。
任意の Postgres クライアントとは
pgAdmin4
https://www.pgadmin.org/download/pgadmin-4-windows/
知名度の高いDBクライアント
DBeaver Community | Free Universal Database Tool
https://dbeaver.io/
モダンなDBクライアント
その他、数十種類あります。
Postgres専用や、複数のDBに対応しているもの、機能がシンプルなもの、複数あるもの多種多様なクライアントが開発されています。
Default URL:
DBクライアント等で必要
postgresql://postgres:postgres@localhost:54322/postgres
http://localhost:54321
クライアント ライブラリを使用せずにこれらのサービスにアクセスしている場合は、クライアント キーをAuthorizationヘッダーとして渡す必要がある場合があります。JWT ヘッダーの詳細をご覧ください。
curl 'http://localhost:54321/rest/v1/' \
-H "apikey: <anon key>" \
-H "Authorization: Bearer <anon key>"
http://localhost:54321/rest/v1/ # REST (PostgREST)
http://localhost:54321/realtime/v1/ # Realtime
http://localhost:54321/storage/v1/ # Storage
http://localhost:54321/auth/v1/ # Auth (GoTrue)
ローカルとリーモートの接続
サーバーと接続するためにlinkコマンドを実行します。
ローカルからサーバー内の指定したプロジェクトとの接続
supabase link --project-ref [project-id] -p [Database Password]
「サーバーのプロジェクト」をローカルから操作するための許可を得るコマンド。
[project-id]
サーバーのプロジェクト
左サイドバーにある
Project setting > General settings
Reference ID (=project-id)
から取得する。
[Database Password]
サーバー内のプロジェクトで使用されているDBのパスワード
※DB作成時にしか表示されないので注意
紛失した場合は、再生成する必要がある。
使用例
supabase link --project-ref sztibyzwqhumhpoafqmf -p x85*******LB
サーバー側でもうすでにスキーマ等を設定している場合
supabase db remote commit
このコマンドを実行するとサーバー側のスキーマをローカルにマイグレーションファイルとして保存してくれます。
マイグレーションファイルの出力形式。
このファイルは、supabase\migrations ディレクトリに出力されます。
[タイムスタンプ]_remote_commit.sql
ローカルに保存されたマイグレーションファイルを反映させるには
supabase db reset
で反映されます。
※ 注意：ローカル側にテーブルなどの設定を一切していない、テーブル等が存在しているとコンフリクトで実行出来ずエラーになります。
もしくは同期済みであること。
データベースでの CLIの基本的な利用方法
ローカルで操作してサーバーに反映させたい
テーブルを作り（＝SQLコマンドcreate tableの実行、またはGUIでテーブル作成）
テーブルを保存（＝マイグレーションファイルに保存）
マイグレーションファイルに保存するには
supabase db diffコマンドを実行する。
マイグレーションファイルがsupabase\migrations以下に保存される
pushコマンドでマイグレーションファイルサーバー側に反映させる。
サーバー側にテーブル情報が同期される。
サーバーで操作してローカルに反映させたい
※前提として、ローカルとサーバーで同期している必要がある。
たとえば、どっちもテーブル設定が空っぽとか同じテーブルが作られているとか
同期している状態から、サーバー側で操作した結果をローカル側に反映させる。
同期している状態から
supabaseダッシュボード
https://app.supabase.com/project/[project-id]
左サイドバーのTable EditorでのGUI操作
もしくは
左サイドバーのSQL Editor
create table table_name (
id bigint generated by default as identity primary key,
inserted_at timestamp with time zone default timezone('utc'::text, now()) not null,
updated_at timestamp with time zone default timezone('utc'::text, now()) not null,
data jsonb,
name text
);
等のSQL文を実行してテーブル新規作成など操作を行う。
supabase db remote commit
を実行すると、サーバー側の変更がローカルにマイグレーションファイルとして保存されます。
マイグレーションファイルをローカルのsupabaseに反映させたい場合は
supabase db reset
を実行します。
supabase db resetコマンドは
マイグレーションファイルをDBに反映させたい時や、GUIやSQL文で変更した状態をマイグレーションファイルに保存した時点に戻してくれます。
※ しかし、テーブル内などに保存したデータは消えます、seed.sqlファイルを利用しましょう。
サンプルデータの追加方法
seed.sqlファイルを利用します。
seed.sqlファイルはテーブル内のデータを初期化する時に利用します。
seed.sqlファイル例
-- in supabase/seed.sql
insert into public.employees (name)
values
('Erlich Bachman'),
('Richard Hendricks'),
('Monica Hall');
完全にリセットをするには
なにもかも全部をやり直したい時は、ルート直下にあるsupabaseディレクトリを削除して、再度 supabase initを実行します。
これでローカル側は完全にリセットされます。
しかし、サーバー側のデータはそのまま残るので、
supabase db remote commitを実行してサーバー側のスキーマをローカル側にマイグレーションファイルとして保存してから、supabase db resetを実行してローカル側のDBにマイグレーションファイルを反映させるか、
サーバー側もプロジェクトごと削除(もしくはポーズ)して、新しくプロジェクトを作ります。
※ 現在は無料プランでもプロジェクトを停止(pouse)すると3つ以上のプロジェクトを作成可能です、起動させておく上限が2個という事です。
supabase の無料アカウントならばアクティブなプロジェクトは２つまでが上限となっていましたが、プロジェクトを停止さえしておけばその他のプロジェクトをたくさん作れます。
起動／終了 関連
supabase start
このコマンドを実行するとsupabaseのコンテナが起動する、Dockerイメージやその関連ファイルが無い場合は自動的にダウンロードする。
supabase stop
このコマンドを実行するとマイグレーションファイルに保存していないテーブルやバックアップしていないテーブル内のデータは空になる
通常、supabase startとセットで使う。
supabase stop --backup
データベーススキーマやテーブルに入力したデータ等を保存したまま終了させる。
これはまだマイグレーションファイルに保存をしていないデータベーススキーマも保存される。
※ 何回か、supabase の停止に失敗することがあった、だが失敗直後すぐ2回目のコマンド実行をしたら成功した。
supabase db ローカル 関連
supabase db dump
--------- この項目は未調査
Dumps schemas from the remote database
サーバー側のデーターベーススキーマをダンプ（出力）してくれる。
サーバー側のpostgresの全体のバックアップを意味する。
supabase db dump
サーバーのテーブルスキーマをローカル側でファイルとして保存するコマンド
pg_dump の別名なのか、pg_dumpの代替ツールなのか不明
基本的な使い方はサーバーのスキーマを
ローカルの新しいプロジェクトに反映させる・・・という方法で使うのかな？
使用例
supabase\dumpディレクトリを作成
supabase db dump -f supabase\dump\dumpfile.sql -p x85*******LB
-f, --file
-p, --password
-f を
supabase\dump\dumpfile.sql
と指定すれば
root直下の supabase\dumpディレクトリ内に保存される。
※ただしsupabase linkで接続したディレクトリ以下の場所に限る。
rootやそれ以下のディレクトリ内なら実行可能
※どの場所に置くかの指定はないので
現在仮の置き場所としてsupabase\dumpを指定している。
不都合が生じたら別の場所に置く
※現在dumpファイル化されるところまでを確認
しかしこのdumpファイルをどうやって使うのか全く知識がない。
supabase db dumpコマンドがあるのだから
supabase db restoreコマンドもあるはずだと思ったが
未実装のようだ。
dumpファイルと
マイグレーションファイルは別物のようで
supabase db resetコマンドでローカルのデーターベースに
反映させようと思ったがエラーが出た。
postgresのDBクライアントからとか
postgresのリストアコマンドがあるようだが
dumpファイルからローカルへのリストア方法がわからず断念
--------- この項目は未調査
これからの予定
dumpファイルをローカルに反映させる方法を探る
マイグレーションディレクトリ内に放り込んで反映されるのか？
コンフリクトがおきた場合は？
だったらローカルのスキーマを全部削除して
ダンプファイルを読み込ませれば良いのか？
postgresの知識があったならこのへんはスムーズにいきそう
--------- この項目は未調査
supabase db push
ローカルでマイグレーションに保存したスキーマ等をサーバーに送る。
サーバーにすでにテーブルなどが作成済みだと
このコマンドは実行できない
リモートコミットを実行して確定させる必要がある。
基本的に
サーバー側で新しくプロジェクトを作り、（もしくは自分で作った全てのテーブルを削除）
ローカルでテーブルを作り
マイグレーションファイル化して
それをsupabase db pushをする。
そうするとサーバーとローカルでスキーマの同期が取れる。
サーバー側ですでに作ってあるのならば、逆にローカル側のマイグレーションファイルをすべて消してリセットコマンド(supabase db reset)を実行し、その後supabase db remote commitを実行することでサーバー側のスキーマが、ローカル側にマイグレーションファイルとして保存される、そのマイグレーションファイルをリセットコマンド（supabase db reset）でローカル側に反映させる。
そうするとサーバーとローカルでスキーマの同期が取れる。
supabase db push -p [Database Password]
※重要コマンド
新しいマイグレーションをサーバーのデータベースにプッシュする。
supabase db push -p [Database Password] --dry-run
db push コマンドのリハーサルを行う。
※ pushコマンドは追記するコマンドです
もうすでにサーバー側に他のテーブルがあるけれど衝突（コンフリクト）しない場合に追記されます。
supabase db pushでのエラー
実際の場面
> supabase db push
Error: supabase _migrations.schema_migrations table conflicts with the contents of supabase /migrations.; Found 4 versions and 2 migrations.
Try rerunning the command with --debug to troubleshoot the error.
これは
サーバー(=REMOTE)にpushしようとした所、table conflictsしていると出た場合
4つのバージョンと2つのマイグレーションファイルがあるが
サーバーとローカルが一致していないことが原因
まずは
supabase migration list
このコマンドでローカルとサーバーの状況を見る。
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────────────┼──────────────────────
│ 20230103142354 │ 2023-01-03 14:23:54
│ 20230103143552 │ 2023-01-03 14:35:52
│ 20230103163726 │ 2023-01-03 16:37:26
│ 20230103163831 │ 2023-01-03 16:38:31
20230103164733 │ │ 2023-01-03 16:47:33
20230103164834 │ │ 2023-01-03 16:48:34
今回はローカルでマイグレーション等いろいろいじって（直接マイグレーションファイルを削除したり）してサーバーとの同期が失われたことによるもの。
原因はわかっているので、サーバー側のスキーマを削除する。
実際のコマンド
supabase migration repair 20230103142354
supabase migration repair 20230103143552
supabase migration repair 20230103163726
supabase migration repair 20230103163831
この4つのコマンドを実行するとサーバー側のは消える。
ローカル側は
supabase\migrationsディレクトリ内にあるマイグレーションファイルを削除すればリストから消える。（1つ消した）
その結果
supabase migration list
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────┼──────────────────────
20230103164733 │ │ 2023-01-03 16:47:33
このようになり、
ローカル側で必要なマイグレーションファイルだけ残して
supabase db push
を実行すると
supabase migration list
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────────────┼──────────────────────
20230103164733 │ 20230103164733 │ 2023-01-03 16:47:33
と、このように 同期 が取れて
ローカルとサーバーのテーブルが同じになる。
supabase db reset
supabase db reset
※重要コマンド
「マイグレーション実行後の変更した部分」をすべてリセットしてしまう。
gitのchekcoutコマンド（直前のコミット内容まで復元）と似ている。
逆に、変更を元に戻したい時に便利なコマンド。
ファイルに保存していないデータベーススキーマを全て消して、最後にマイグレーションした状態になる。
マイグレーションをしていない場合はsupabase start立ち上げ時の状態に戻る。
※ローカル側の supabase /migrationsディレクトリ内にあるマイグレーションファイルをすべて読み込み、それらすべてのデータベーススキーマをローカルに反映させる。
supabase db diff 関連
ローカルのスキーマに関するコマンド
現在 --use-migra オプションはデフォルト値で true になっている。
※migraとは、データベーススキーマの差分を調べる外部ツール
migra(Python製) diffツール
データベーススキーマからSQLスクリプトファイルを作成する。
supabaseがmigraを使う理由
https://www.slip.so/tutorials/database-migrations-in-supabase-with-migra
supabase db diff
supabase db diff
データベーススキーマの差分を見る。
VScodeのterminalに表示される。
（ファイルとしては保存されない）
supabase db diff
GUIで操作したテーブルなどの変更や操作を、sqlファイルに保存できたりする。
マイグレーション済みとのローカルでの差分
supabase db diff -f [ファイル名]
※重要コマンド
まだマイグレーションファイルに保存されていないスキーマの差分を新たなマイグレーションファイルを作成して保存する。
タイムスタンプ＋指定したファイル名に保存される。
supabase db diff --linked
Linkしたサーバーとローカルとの差分を出力してくれる。
supabase db diff --linked
差分がVScodeのterminalに表示される。
（ファイルとしては保存されない）
サーバー側とローカル側との差分
supabase db diff --linked -f [ファイル名]
※重要コマンド
ファイルに保存される。
これはマイグレーションファイルとして保存されるので、supabase db resetを実行するとこの作成したファイルを読み込んでスキーマがDBに反映されます。
※この機能は完全ではありません、エラーが起きる場合があり、その場合は手動で修正する必要があります。
supabase db resetでエラーが出ないかを確認してください。
--use-pgadmin
pgAdminを使ってスキーマの差分を取る
（このオプションを使うよりも、デフォルトのmigraを使うほうが高性能）
supabase db lint 関連
--------- この項目は未調査
使用方法：不明
いつどのような場面で使うかがわからない
Checks local database for typing error
ローカルのタイピングエラーをチェックする？
supabase db lint
supabase db lint --level warning
Checks Local Database For Typing Error
とあるが、何のタイプエラーなのかわからない
supabase db lint [flags]
--level <[ warning | error ]>
-s, --schema
lintはチェックしてくれるという意味のようだが、
何を整形するのかがわからない、
自分で書いたSQL文を厳密にチェックをしてくれるのだろうか？
supabase db サーバー 関連
supabase db remote
supabase db remote commit -p <string>
※重要コマンド
supabase db remote commit -p x85*******LB
何もテーブルをいじっていなくても
このコマンドを実行するとコミットが実行される
その場合、空のマイグレーションファイルが作成される。
コミットするだけでマイグレーションファイルになってないスキーマはサーバーに反映されていない。
反映させるためには、
diffコマンドでマイグレーションファイルを作り、
そしてpushコマンドでサーバーと同期を取り
その後でコミットを行う。
このコマンドは、
サーバーでテーブルを作った後などに、このコマンドでコミットを行う、
そうするとローカルにサーバーのスキーマが反映されたマイグレーションファイルが
ローカルに作成される
そこで
supabase db reset を実行すると
サーバーのテーブル定義がローカルにも反映される。
コミットコマンドは
サーバー側の変更を確定させ、マイグレーションファイルを作成すること、
そして、そのサーバー側のスキーマをローカルにも反映させるには、
supabase db reset
を実行する。
そうすると
サーバーとローカルのテーブル構造などが同じになる。
supabase db remote commit
サーバーのデータベースの変更を、ローカル側の supabase /migrationsディレクトリに新しいマイグレーションファイルを作成する。
supabase db remote commit -p [Database Password]
※重要コマンド
※詳細
このコマンドの目的はサーバー側のデータベーススキーマの変更をローカル側に反映させるための使う。
まず最初にこのコマンドを実行することで、サーバー側のデータベーススキーマの変更が、ローカル側にマイグレーションファイルとして生成される。
生成される場所はローカル側のマイグレーションファイルがお体ある場所と同じsupabase /migrationsディレクトリに置かれる。
しかし、 サーバー側のマイグレーションファイルと判断するために、ファイル名に[タイムスタンプ]_remote_commit.sqlという形式でファイルが生成される。
ただし、まだこれはマイグレーションファイルを生成するだけなのでローカルには反映されていない。
マイグレーションファイルはあるのにデータベースに反映するためには、supabase db resetコマンドを使用することで、ローカル側にあるマイグレーションファイルが反映される。
では、
ローカルのマイグレーションファイルを削除した場合はどうなるか？
マイグレーションファイルの中身が空の場合、
削除しても問題無し
マイグレーションファイルが無いとしても、
差分がないと判断して、同期にずれてないとなる。
マイグレーションファイルの中身があったファイルを削除した場合
supabase db push
supabase db remote commit
このどちらのコマンドも、同期していないと判断され
エラー扱いとなる。
これの対処方法は
supabase migration list
で片側だけのタイムスタンプを探す
>supabase migration list
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────────────┼──────────────────────
│ 20230103175609 │ 2023-01-03 17:56:09
│ 20230103182319 │ 2023-01-03 18:23:19
│ 20230103182411 │ 2023-01-03 18:24:11
20230104201405 │ │ 2023-01-04 20:14:05
この状態から
--status revertedオプションを使用した場合
supabase migration repair --status reverted 20230103175609
サーバー側のを消す。
（指定したタイムスタンプはサーバー側）
サーバー側のみ
--status appliedオプションを使用した場合
supabase migration repair --status applied 20230104201405
ローカル側のをサーバー側に反映させる
（指定したタイムスタンプはローカル側）
ローカル側のみ
上記２つのコマンドを実行した結果
>supabase migration list
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────────────┼──────────────────────
│ 20230103182319 │ 2023-01-03 18:23:19
│ 20230103182411 │ 2023-01-03 18:24:11
20230104201405 │ 20230104201405 │ 2023-01-04 20:14:05
※この状態でpushしてもコンフリクトだとエラーが出る。
ローカルとサーバー（＝リモート）のどちらかが欠けておらず
タイムスタンプが両方とも埋まっていたら
同期が取れている状態になる。
supabase db remote commit
でサーバー側を確定して、ローカルにマイグレーションファイルが作成され
supabase db reset
でマイグレーションファイルがローカルにも反映される
supabase のローカルとサーバーでのマイグレーションとコミットのまとめ
※REMOTEはサーバーを指す。
supabase migration listでローカルとサーバーで両方とも揃っている時を同期しているとする。
すでにサーバー側でテーブルなどが作られている場合
※ローカルにマイグレーションファイルは無い
（supabase\migrationsディレクトリ内は空）
supabase db diff --linked -f []
このコマンドでローカル側にサーバーのテーブルを構成するマイグレーションファイルが出来る。
例
supabase db diff --linked -f linkfile01
supabase\migrationsディレクトリに
20230105081034_linkfile01.sql
サーバーのが反映されたマイグレーションファイルが出来る
ローカルに反映させるために
supabase db reset
を実行する
> supabase migration list
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────┼──────────────────────
20230105081034 │ │ 2023-01-05 08:10:34
ローカル側のダッシュボードで確認
Default Project | Supabase
http://localhost:54323/project/default/editor
サーバー側で作られていたテーブルがローカル側にも作られているのを確認。
しかし
supabase db push
をするとエラーになる。
同じテーブルになっているのだが同期は取れていない状態。
この時、
supabase db diff -f local01
diffコマンドを実行しても新しいマイグレーションファイルは作成されない。
pushもだめ、diffもだめ
そこで
supabase migration repair
を試してみる。
> supabase migration list
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────┼──────────────────────
20230105081034 │ │ 2023-01-05 08:10:34
supabase migration repair --status applied 20230105081034
> supabase migration list
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────────────┼──────────────────────
20230105081034 │ 20230105081034 │ 2023-01-05 08:10:34
このような状態になってから
supabase db pushを行うと正常に実行された。
これで同期が取れた状態となった。
その他
supabase migration listでの4パターン
ローカル側のみある
サーバー側のみある
どちらもない
ローカル側とサーバー側両方ある
の４パターン考えられる。
ローカル側のみある、サーバー側のみあるの場合同期が取れてないという。
サーバー側のみにある場合
supabase migration repair --status reverted [タイムスタンプ]
サーバー側を消す
ローカル側のみある場合
supabase migration repair --status applied [タイムスタンプ]
ローカル側のを適用させる。
ローカル側を消したい場合
supabase\migrationsにあるマイグレーションファイルを消すだけでいい。
supabase migration listにもマイグレーションファイルを消すだけですぐ反映される
supabase migration list
このコマンドはあくまでもローカル側の情報でしか無い。
Linkされたサーバー側の情報が正しいわけではない。
例えば、サーバー側にもうすでにテーブルを設定してあるのに、
supabase migration listコマンドでみても
サーバー側のマイグレーション（＝スキーマ）が正確に表示されるわけではない。
supabase migration 関連
supabase migration list で見られる情報は、
あくまでもローカル側から見た情報に過ぎず
例えば、
supabase migration list で見られる情報を削除(supabase migration repairコマンド)してもサーバー側のテーブルが削除されるわけではない。
サーバー側に適用させるにはさらに、コミットコマンド(supabase db remote commit)などを使う必要がある。
ローカル側のを消した場合リセットコマンド(supabase db reset)を実行する必要がある。
リセットコマンド(supabase db reset)はローカルに保存してあるマイグレーションファイルが適用された状態に戻る。
マイグレーションファイルに保存していなければその情報は削除される。
ローカルの変更をマイグレーションファイルに保存するには差分コマンド(supabase db diff )を実行すればよい。
supabase migration list
ローカルとサーバーのマイグレーションの状況がわかる
※ 重要
これはあくまでもローカルから見た情報であり、
サーバー側で、すでにテーブルがある状態なのに
リモートのマイグレーション？（＝タイムスタンプ）が無い場合もあります。
実行例
supabase migration list
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────┼──────────────────────
20230103164733 │ │ 2023-01-03 16:47:33
※ローカル側に作るにはsupabase db diff -f [ファイル名]コマンドで作れる
supabase migration new
supabase migration new
新しいマイグレーションファイルが出来る
自分でSQLを書いて、それを書き込むときのため用か？
supabase migration repair
マイグレーションファイルを適用したり、無効化出来る。
supabase migration repair
supabase migration repair [flags] <version>
Flags:
--status [ applied | reverted ] Version status to update.
実行例
supabase migration repair --status applied 202301031741
指定したマイグレーションをローカルからサーバーに適用させる
※重要コマンド
supabase migration repair --status reverted 20230103174
指定したマイグレーションを適用させる前の状態に戻す（＝無効化）させる。
※重要コマンド
同期が取れてない状態なのにサーバー側だけにある場合は？
LOCAL │ REMOTE │ TIME (UTC)
─────────────────┼────────────────┼──────────────────────
│ 20230126134547 │ 2023-01-26 13:45:47
20230127002828 │ 20230127002828 │ 2023-01-27 00:28:28
この例だと20230126134547をローカルに適用させたい。
同期が取れていない場合は（ローカル側のsupabase\migrationsにあるマイグレーションファイルを削除してしまった等）
現在の所は
supabase migration repair --status reverted 20230126134547
と指定して消す。
もしくは、
ゴミ箱の中から20230126134547のタイムスタンプがついたマイグレーションファイルを拾い上げてくる。
同期が取れていれば
supabase db remote commitを実行すれば
LOCALとREMOTE同時に作成される。
ローカルからサーバーに同期をとる手段は用意されているが
サーバーからローカルに同期を取る手段は現在用意されていない。
supabase projects 関連
supabase projects create
コマンドラインからのプロジェクトの新規作成
supabase projects create <project name> --db-password x85*******LB
プロジェクトを新規に作る
supabase projects create <project name> --db-password x85*******LB --interactive
インタラクティブモードでプロジェクトを新規に作る。
その他のフラグ
--org-id
組織名
--plan <[ free | pro ]>
フリープラン、プロプラン
--region
リージョン情報
supabase projects list
プロジェクトの一覧を表示
supabase projects list
supabase orgs list
supabaseの組織の一覧を表示
supabase orgs list
supabase テスト 関連
supabase test db
PgTAPでローカルのデータベースをテストします。
PgTAPとは
PostgreSQL用の単体テストツールです。
pgTAP: Unit Testing for PostgreSQL
https://pgtap.org/
使用方法
pgTAP: Unit Testing | supabase
https://supabase.com/docs/guides/database/extensions/pgtap
このコマンドを使うにはpgtapのextensionを有効にする必要があります。
有効にした後、supabase コンテナを再起動する。
supabaesディレクトリの下に適当なファイルを作成する。
begin;
select plan( 1 );
select has_table( 'profiles' );
select * from finish();
rollback;
※ 拡張子はわからないのでtxtにしておく。
※ テストファイルの書き方が不明
テストファイル作成後、
supabase test db
を実行する。
supabase gen types 型生成関連
使用例
--local オプション
supabase gen types typescript --local
ローカルのTypescriptの型をターミナルに表示する
--linkedオプション
supabase gen types typescript --linked
リンクで繋いだサーバーのTypescriptの型をターミナルに表示する
--project-idオプション
supabase gen types typescript --project-id sztibozyqhaqffqymhmf
--project-idで指定したサーバーのTypescriptの型をターミナルに表示する
--db-urlオプション
supabase gen types typescript --db-url postgresql://postgres:[YOUR-PASSWORD]@db.[project-id].supabase.co:5432/postgres
Project Settings＞Database>Connection string ＞ URI
Copyする
実際の使用例
supabase gen types typescript --db-url postgresql://postgres:x85*******LB@db.sztibyzwqhumhpoafqmf.supabase.co:5432/postgres
その他のフラグ
--------- この項目は未調査
Flags:
--schema stringArray Schemas to generate types for.
使用方法がわからない
supabase functions 関連
--------- この項目は未調査
supabase functions delete
--------- この項目は未調査
supabase functions delete
Delete a Function from the linked Supabase project. This does NOT remove the Function locally.
Usage:
supabase functions delete <Function name> [flags]
Flags:
-h, --help help for delete
--project-ref string Project ref of the Supabase project.
supabase functions deploy
--------- この項目は未調査
関数をサーバーにデプロイする
Deploy a Function to the linked Supabase project.
Usage:
supabase functions deploy <Function name> [flags]
Flags:
-h, --help help for deploy
--import-map string Path to import map file.
--legacy-bundle Use legacy bundling mechanism.
--no-verify-jwt Disable JWT verification for the Function.
--project-ref string Project ref of the Supabase project.
supabase functions new
--------- この項目は未調査
supabase functions new <Function name> [flags]
ローカルで新しい関数を作成する
supabase functions serve
--------- この項目は未調査
supabase functions serve
ローカルで機能を提供する
Usage:
supabase functions serve <Function name> [flags]
Flags:
--env-file string Path to an env file to be populated to the Function environment.
-h, --help help for serve
--import-map string Path to import map file.
--no-verify-jwt Disable JWT verification for the Function.
| コマンド | 説明 |
|---|---|
| delete | supabase から関数を削除 |
| deploy | supabase に関数をデプロイ |
| new | ローカルで新しいFunctionを作成 |
| serve | ローカルでFunctionを実行 |
supabase secrets 関連
環境変数の登録など
supabase secrets list
supabase secrets list
supabase secrets set
supabase secrets set
実際の例
--env-file
.env ファイルからシークレットを読み取ります。
supabase secrets unset
supabase secrets unset
実際の使用例
supabase secrets list
NAME │ DIGEST
───────┼─────────
まだ何も登録されていない
supabase secrets set --env-file .env.local
.env.localファイルから読み込む
supabase secrets list
NAME │ DIGEST
──────────┼─────────────
NEXT_PUBLIC_SUPABASE_ANON_KEY │ 76**************************935
NEXT_PUBLIC_SUPABASE_URL │ 3b****************************10e
このように登録される。
NEXT_PUBLIC_SUPABASE_URLを削除してみる
削除コマンド
supabase secrets unset NEXT_PUBLIC_SUPABASE_URL
supabase secrets list
NAME │ DIGEST
──────────┼─────────────
NEXT_PUBLIC_SUPABASE_ANON_KEY │ 76**************************935
supabase secrets set --env-file .env.local
もう一度登録すると削除した部分は追加され、
２重には登録されない。(=NEXT_PUBLIC_SUPABASE_ANON_KEY)
supabase secrets list
NAME │ DIGEST
──────────┼─────────────
NEXT_PUBLIC_SUPABASE_ANON_KEY │ 76**************************935
NEXT_PUBLIC_SUPABASE_URL │ 3b****************************10e
supabase domains 関連
--------- この項目は未調査
※カスタムホスト名というのがよくわかっていない
supabase domains activate
プロジェクトのカスタムホスト名設定を有効にします。
これにより、Supabaseプロジェクトがカスタムホスト名でのリクエストに応答するように再設定されます。
カスタムホスト名を有効にすると、プロジェクトの認証サービスは Supabase がプロビジョニングしたサブドメイン上では機能しなくなります。
supabase domains activate
--include-raw-output
Include raw output (useful for debugging).
--project-ref
Project ref of the supabase project.
Activate The Custom Hostname For A Project
supabase domains create
--------- この項目は未調査
※custom-hostname というのがよくわかっていない
supabase domains create --custom-hostname <string>
supabase domains create --include-raw-output
supabase domains create --project-ref <string>
Flags
--custom-hostname
The custom hostname to use for your supabase project.
--include-raw-output
Include raw output (useful for debugging).
--project-ref
Project ref of the supabase project.
supabase domains delete
--------- この項目は未調査
※custom-hostname というのがよくわかっていない
プロジェクトのカスタムホスト名設定を削除する
supabase domains delete --include-raw-output
supabase domains delete --project-ref <string>
Flags
--include-raw-output
Include raw output (useful for debugging).
--project-ref
Project ref of the supabase project.
supabase domains get
--------- この項目は未調査
※カスタムホスト名というのがよくわかっていない
supabase domains get --include-raw-output
supabase domains get --project-ref <string>
Flags
--include-raw-output
Include raw output (useful for debugging).
--project-ref
Project ref of the supabase project.
supabase domains reverify
--------- この項目は未調査
※カスタムホスト名というのがよくわかっていない
プロジェクトのカスタム ホスト名構成を再確認する
supabase domains reverify
supabase vanity-subdomains 関連
--------- この項目は未調査
supabase vanity-subdomains activate
supabase vanity-subdomains activate
サブドメインの有効化
supabase vanity-subdomains activate --desired-subdomain <string>
Flags
--desired-subdomain
The desired vanity subdomain to use for your supabase project.
vanity-subdomains subdomains get
--------- この項目は未調査
現在のバニティ サブドメインを取得する
supabase vanity-subdomains get
supabase vanity-subdomains check-availability
--------- この項目は未調査
目的のサブドメインが使用可能かどうかを確認します
supabase vanity-subdomains check-availability [flags]
supabase vanity-subdomains check-availability [flags]--desired-subdomain <string>
Flags
--desired-subdomain
The desired vanity subdomain to use for your supabase project.
supabase vanity-subdomains delete
--------- この項目は未調査
supabase vanity subdomains delete
supabase network-bans 関連
（実験的機能 Supabase CLI v1.28.3 2023年1月5日）
must set the --experimental flag
ネットワーク禁止の管理
ネットワーク禁止は、トラフィックパターンが不正に見える場合（認証に何度も失敗するなど）、一時的にブロックされるIPのことを指します。
サブコマンドを使用すると、現在の禁止を表示したり、必要に応じてIPのブロックを解除したりできます。
supabase network-bans get
（実験的機能 Supabase CLI v1.28.3 2023年1月5日）
must set the --experimental flag
supabase network-bans get
Get The Current Network Bans
Flags
--experimental
enable experimental features
--project-ref
Project ref of the supabase project.
supabase network-bans remove
（実験的機能 Supabase CLI v1.28.3 2023年1月5日）
must set the --experimental flag
supabase network-bans remove
ネットワーク禁止を解除する
Flags
--db-unban-ip
IP to allow DB connections from.
--experimental
enable experimental features
supabase network-restrictions 関連
（実験的機能 Supabase CLI v1.28.3 2023年1月5日）
must set the --experimental flag
ネットワーク制限の管理
supabase network-restrictions get
（実験的機能 Supabase CLI v1.28.3 2023年1月5日）
must set the --experimental flag
supabase network-restrictions get
現在のネットワーク制限を取得する
Flags
--experimental
enable experimental features
--project-ref
Project ref of the supabase project.
supabase network-restrictions update
（実験的機能 Supabase CLI v1.28.3 2023年1月5日）
must set the --experimental flag
supabase network-restrictions update
ネットワーク制限の更新
Flags
--bypass-cidr-checks
Bypass some of the CIDR validation checks.
--db-allow-cidr
CIDR to allow DB connections from.
--experimental
enable experimental features
--project-ref
Project ref of the supabase project.
supabase network-restrictions update [flags]
supabase completion 関連
指定されたシェルのオートコンプリート スクリプトを生成する
シェルの種類
supabase completion bash
supabase completion fish
supabase completion powershell
supabase completion zsh
powershellでの supabase コマンド補完
supabase completion powershell
これだけだと出力のみ
使うにはパイプを利用する必要がある。
Windowsで使うには
supabase completion powershell | Out-String | Invoke-Expression
これを利用できるようになると、
su
を入力後、数回tabキーで
supabase.exe
までを補完してくれる。
※VScodeのターミナル上でのsupabase.exeはsupabase と同じ。
supabase.exe s
を入力後、数回tabキーで
supabase.exe status
までを補完できる。
その他の補完が利用可能なshellは
bash、fish、zsh
よくある失敗、疑問、問題解決
supabaseが動かない場合
Docker Desktopは立ち上がっていますか？
DBのバックアップ、ダンプファイルの作成
コンテナのリストを表示する
docker ps -f name=supabase_db
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
8330fba5f44c public.ecr.aws/supabase/postgres:15.1.0.21 "docker-entrypoint.s…" 17 hours ago Up 17 hours (healthy) 0.0.0.0:54322->5432/tcp supabase_db_[プロジェクト名]
CONTAINER ID＝container_id
NAMES＝name
container_idは 8330fba5f44c だとわかる
試しにログファイルを表示してみる
docker exec -it 8330fba5f44c ls -la /var/log/postgresql
ログファイルが正常に表示されたらok
シェルの実行
docker exec -it 8330fba5f44c bin/bash
バックアップの実行
dockerコマンドからダンプファイルを出力
pg_dumpall (DBをまるごとバックアップ)
docker exec [container_id or name] pg_dumpall -U postgres > [file_name]_all.sql
実行例
docker exec 8330fba5f44c pg_dumpall -U postgres > dump_all.sql
pg_dump (DBを個別にバックアップ)
docker exec [container] pg_dump --create --clean --if-exists --schema-only -U postgres > [file_name].sql
実行例
docker exec 8330fba5f44c pg_dump --create --clean --if-exists --schema-only -U postgres > dump.sql
ファイルはroot直下に出力される
supabaseコマンドでダンプファイルを出力
実行例
supabase db dump
ファイルはroot直下に出力される
リストアする
--------- この項目は未調査
リストアの方法わからず。
supabaseのリストアコマンドは未実装です。
supabase CLI のバージョンアップ待ち
powershell からリストアする
Prismaについて
質問
Supabase は Prisma等のORM は必要ないのか？
回答
ORMではなく、Supabase CLI を使ったデータベースマイグレーションを現状公式では推奨しております。
https://youtube.com/watch?v=Kx5nHBmIxyQ
ただ、Prismaと組み合わせて使うことも可能にはなっています！
https://supabase.com/docs/guides/integrations/prisma
感想
Prismaに慣れているなら、もしくはベンダーロックイン※を恐れているなら
Prismaを選択すべき、
ただアプリがそんな大きくなければ
supabase CLIでちゃちゃっと済ませたほうが楽だろう。
それに、ネイティブツール(supabase CLI ＝自社謹製)と違って
外部ツール(Prisma等のORM)を使うと色々と不具合が出る可能性もある
例
shadow database問題
Running prisma migrate dev against a Supabase database times out (without the existence of a pre-existing explicit shadow database) · Issue #17160 · prisma/prisma
https://github.com/prisma/prisma/issues/17160
※ベンダーロックイン
特定ベンダー（＝メーカー）の独自技術に大きく依存した製品
たとえばもしsupabaseが解散した時、他のDBへの移行コストが大きい
Prismaを使えばコストが軽い。
todo
書くこと
マイグレーションファイルのまとめ方