データ
Supabase プロジェクトのデータには、Spring Data でアクセスします。spring_boot_starter_data のエンティティ、リポジトリ、派生クエリ、Pageable、Sort です。データベースへの経路は二つあり、リポジトリがどちらを使うかは設定が決めます。
使う理由
Supabase のプロジェクトは、データベースを二通りに提供します。ユーザーのトークンがあればどこからでも使える REST API (PostgREST) と、パスワードを持つサーバーのための素の PostgreSQL です。Flutter アプリが使えるのは前者だけです。サーバーはトランザクションやロックが欲しいことがあり、それがあるのは後者だけです。リポジトリのインターフェースはどちらでも同じなので、選択はプロパティ一つで済み、アプリケーションは起動時に一度、どちらの経路にいるかを伝えます。
例
@Table('todos')
class Todo {
Todo({
required this.title,
required this.listId,
this.done = false,
this.id,
this.createdAt,
this.version,
});
@Id()
int? id;
String title;
String listId;
bool done;
DateTime? createdAt;
@Version()
int? version;
}
abstract interface class Todos implements ListCrudRepository<Todo, int> {
Future<List<Todo>> findByDoneOrderByCreatedAtDesc(bool done);
Future<Page<Todo>> findByListId(String listId, Pageable pageable);
Future<int> countByDone(bool done);
Future<int> deleteByDone(bool done);
}
spring.supabase.url と anon-key だけを設定した場合、findByDoneOrderByCreatedAtDesc(false) は一つのリクエストです。
GET /rest/v1/todos?done=eq.false&order=created_at.desc
apikey: <anon key>
Authorization: Bearer <the user's token, or the anon key>
二つの経路
spring.supabase.db.url なし (デフォルト) |
spring.supabase.db.url あり |
|
|---|---|---|
| ストア | supabase (PostgrestDataStore): 呼び出しごとに /rest/v1 への HTTP リクエスト一つ |
jdbc: PostgreSQL 上の SQL |
| 誰として | 現在のユーザー (SupabaseCredentials)。行レベルセキュリティが適用される |
アドレスのユーザー (通常は postgres で、行レベルセキュリティを通過する)。db.rls: user なら現在のユーザー |
@Transactional、@Lock、SQL の @Query、JdbcClient |
使えない | 使える |
@MappedCollection |
使えない | 使える |
| 場所 | サーバー、Flutter アプリ、Web | サーバー (Flutter アプリではパスワードがアプリに同梱され、スターターが警告する) |
スターターは次のように選びます。優先順位が最も低いデフォルトなので、アプリケーションが自分で設定したものが優先されます。
spring.supabase.db.urlが設定されている:spring.datasource.urlがそのアドレスになります。アプリケーションは、他の PostgreSQL のデータソースと同じく、postgresドライバーのパッケージを依存関係に加えます。- 設定されておらず、アプリケーションに独自の
spring.datasource.urlもない:spring.data.storeがsupabaseになります。 - アプリケーションに独自の
spring.datasource.urlがあり、db.urlがない: デフォルトのストアはアプリケーションのもののままです。リポジトリは@UseStore('supabase')で REST API を使います。
@UseStore('supabase')
abstract interface class Todos implements ListCrudRepository<Todo, int> {}
起動時に、経路が一度だけログに出ます。パスワードは出ません。
Supabase: the repositories use the REST API of abcd.supabase.co, as the current user (row-level security applies); no transactions, locks or SQL (spring.supabase.db.url for those)
Supabase: the repositories use SQL over db.abcd.supabase.co:5432 (direct connection), as the user of the address (row-level security is passed; spring.supabase.db.rls: user to apply it)
REST ストアのフィルター
派生クエリは、PostgREST のクエリパラメーターになります。値は常にデータとして扱われます。API が構文として読んでしまうテキストは、引用符で囲むかエスケープします。
| メソッド名の中 | 送られるもの |
|---|---|
findByDone(false) |
done=eq.false |
findByTitle(null) |
title=is.null |
Not |
neq。null のときは not.is.null |
IsNull、IsNotNull、True、False |
is.null、not.is.null、is.true、is.false |
LessThan、LessThanEqual、GreaterThan、GreaterThanEqual |
lt、lte、gt、gte |
Between |
その列への gte と lte |
In、NotIn |
in.(1,2)、not.in.(…)。テキストの値は二重引用符で囲む |
Like、NotLike |
match。パターンは両端を固定した正規表現になる (% は .*、_ は .) |
StartingWith、EndingWith、Containing、NotContaining |
match。テキストはエスケープされる: title=match.^Buy |
等価またはテキストパターンへの IgnoreCase |
imatch |
And |
条件ごとに一つのパラメーター |
Or |
一つの or=(…) パラメーター。複数の条件のグループは and(…) |
テキストのパターンを正規表現として送るのは、API 自身の like がすべての * をワイルドカードとして読み、文字としての * を表す方法がないためです。そのため、findByTitleStartingWithIgnoreCase('a*b(c') は title=imatch.^a\*b\(c を送ります。
findByListIdAndDoneOrPriority('a,b', true, Priority.high) は、一つのパラメーターを送ります。
or=(and(list_id.eq."a,b",done.eq.true),priority.eq."high")
日付は UTC の ISO 8601 で、enum はその名前で送られます。
ソートとページ
| メソッドの中 | 送られるもの |
|---|---|
OrderByCreatedAtDesc、Sort |
order=created_at.desc。Sort が指定すれば nullsfirst と nullslast が付く |
First、Top3 |
limit |
Pageable |
offset と limit。順序の指定がなければ ID で並べるので、同じページは二度読んでも同じになる |
Page の結果 |
行、そして合計のための件数: 行を返さない (limit=0) Prefer: count=exact 付きの GET |
countBy… |
同じ件数: 行を返さない Prefer: count=exact 付きの GET |
existsBy… |
一行の ID (limit=1) |
final page = await todos.findByListId('l1', PageRequest.of(1, 2));
// GET /rest/v1/todos?list_id=eq.l1&order=id&offset=2&limit=2
// GET /rest/v1/todos?list_id=eq.l1&select=id&limit=0 Prefer: count=exact
合計は、応答の Content-Range ヘッダー (*/0 や 0-24/3573) から読みます。HEAD ではありません。HEAD への応答の後で、サーバーやプロキシが次の呼び出しの下で接続を閉じることがあるためです。
保存と @Version
- 新しいエンティティは
POSTです。nullの ID は送られないので、データベースが生成します。@Versionは 1 から始まります。 - 既存のエンティティは、ID で絞った
PATCHです。 - どちらも行を返すよう求めます (
Prefer: return=representation)。そのためsaveは、デフォルト値やトリガーの結果も含めて、データベースが保存したものを返します。 @Versionはトランザクションなしで動きます。更新は読んだときのバージョンでも絞られ、バージョンを上げます。一行も更新されなければOptimisticLockingFailureExceptionです。他の誰かがその行を変更または削除したか、呼び出し元にそれを更新する権限がありません。
await todos.save(Todo(title: 'Changed', listId: 'l1', id: 9, version: 2));
// PATCH /rest/v1/todos?id=eq.9&version=eq.2 {"title": "Changed", ..., "version": 3}
@Versionがなければ、一行も更新されないのはIncorrectUpdateSemanticsDataAccessExceptionです。- 挿入はできたが読み戻せない行 (ポリシーが挿入を許し、選択を許さない) は、
PermissionDeniedDataAccessExceptionです。 deleteAll()は、条件id=not.is.nullを付けて送られます。プロジェクトのデータベースは、条件のないDELETEを拒否するためです。
JSON の列
@Json を付けたプロパティ (アプリケーションのクラス、リスト、マップ) は、jsonb または json の列に入ります。REST ストアは、それをネストした JSON として送り、応答をクラスに読み戻します。@Json がなければ、REST ストアは単なる Map や List をそのまま JSON として送ります。db.url があるとき、ストアはデータスターターの SQL のストアであり、@Json のない Map、List、Set を、リポジトリが作られるときに直し方とともに拒否します。配列の列 (tags text[]) に入る単純な値の List は、そのまま使えます。
データベース関数
db.url なしでアトミックにしなければならない処理には、データベース関数を書き、@Procedure でリポジトリに宣言します。現在のユーザーとして、一つのリクエスト POST /rest/v1/rpc/<name> で呼び出されます (rpc は REST API 自身のパスです)。
abstract interface class Accounts implements CrudRepository<Account, int> {
// POST /rest/v1/rpc/transfer {"from_id": 1, "to_id": 2, "amount": 50}
@Procedure('transfer')
Future<void> transfer(int fromId, int toId, int amount);
@Procedure('accounts_over')
Future<List<Account>> over(int balance);
}
- 引数は、メソッドのパラメーターを名前で、スネークケースにして渡します。
fromIdはfrom_idです。 - 結果は、データスターターと同じように読まれます。行からはエンティティやその他のクラス、スカラーからは一つの値、
Future<void>では何もありません。 - 名前は単純な識別子です (英字、数字、
_)。@Procedure('schema.name')は、このストアでは拒否されます。関数のスキーマはspring.supabase.db.schemaです。 db.urlがあると、同じメソッドが、呼び出し元のトランザクションの中でselect * from "transfer"(…)を呼び出します。
スカラーの結果は、その一つの列から読まれます。
@UseStore('supabase')
abstract interface class Todos implements ListCrudRepository<Todo, int> {
@Procedure('close_all')
Future<int> closeAll(String listId);
}
final closed = await todos.closeAll('l1');
// POST /rest/v1/rpc/close_all {"list_id": "l1"} the answer 2: closed is 2
API が拒否した関数 (permission denied for function close_all) は、ほかの拒否されたリクエストと同じく、データアクセスの失敗です。
アノテーションの下では、ストアが関数を名前で呼び出します (FunctionDataStore.callFunction)。行を返す関数は、その行を返します。スカラーは、関数名の列を一つ持つ一行になります。何も返さなければ、行はありません。
final store = context.getBean<PostgrestDataStore>();
final rows = await store.callFunction('transfer', {
'from_id': 1,
'to_id': 2,
'amount': 50,
});
// POST /rest/v1/rpc/transfer {"from_id": 1, "to_id": 2, "amount": 50}
行の変更
REST の経路では、ストアが自分の行の変更を Realtime から報告します。そのため、リポジトリは、データスターターの行の変更の二種類のメソッドを持てます。
abstract interface class Todos implements ListCrudRepository<Todo, int> {
// The open todos of a list, now and after every change.
Stream<List<Todo>> watchByListIdAndDoneOrderByIdAsc(String listId, bool done);
// Each insert, update and delete of the todos of a list.
Stream<RowChange<Todo>> changesByListId(String listId);
}
final subscription = todos.changesByListId('l1').listen((change) {
// change.kind is RowChangeKind.insert, update or delete; change.row is the entity
// (null for a delete), change.previous the old one (null without replica identity full).
});
// Realtime join: {event: *, schema: public, table: todos, filter: list_id=eq.l1}
watch…Byは、購読されたときに REST API でクエリを実行し、その条件について Realtime が変更を報告するたびに、もう一度実行します。changes…Byは、各変更を、エンティティを持つRowChangeとして渡します。previousがあるのは、テーブルがreplica identity fullのときだけです。そうでなければ、削除は ID だけを運びます。- 絞り込み。
eq、neq、lt、lte、gt、gteの条件が一つなら、Realtime がサーバーで絞ります。それ以外の条件は、こちら側で検査されます。 - テーブルはパブリケーション
supabase_realtimeに含まれていなければならず、ユーザーはその行を読む権限を持っていなければなりません。 db.urlがあると、リポジトリは SQL のストアを使い、SQL のストアは変更を報告しません。そのようなメソッドは、アプリケーションの起動時に失敗します。監視するリポジトリには@UseStore('supabase')を付けてください。
スキーマ
テーブルは spring.supabase.db.schema のものです (設定しなければ API のデフォルトの public)。読み取りでは Accept-Profile、書き込みでは Content-Profile として送られます。@Table に独自のスキーマを持つエンティティは、そのスキーマを使います。スキーマは、プロジェクトが公開しているスキーマに含まれていなければなりません。
エラー
エラーはデータスターターの DataAccessException で、どちらの経路でも同じです。データベース自身のコードは、SQL の経路と同じように変換されます。
| REST API の応答 | 例外 |
|---|---|
PostgreSQL のコード: 23505 (重複キー) |
DuplicateKeyException |
23503 (外部キー) |
DataIntegrityViolationException |
42501 (権限、行レベルセキュリティのポリシー) |
PermissionDeniedDataAccessException |
| その他の PostgreSQL のコード | PostgreSQL の方言がそのコードに対して返すもの |
PGRST301、PGRST302、PGRST303、またはステータス 401 / 403 (トークンが期限切れ、または受け入れられない) |
PermissionDeniedDataAccessException |
PGRST200、PGRST202、PGRST204、PGRST205、またはステータス 404 (API が知らないテーブル、列、関数) |
InvalidDataAccessResourceUsageException |
| ステータス 409 | DataIntegrityViolationException |
| ステータス 500 以上 | DataAccessResourceFailureException |
| それ以外 (API が読めないフィルター、順序、ボディ) | InvalidDataAccessApiUsageException |
| 応答なし | DataAccessResourceFailureException。タイムアウトは QueryTimeoutException |
メッセージは、API が返したもの (message、details、hint) とそのコードです。
REST ストアにできないこと
どれも、理由と対処を示して拒否されます。
| 対応していないもの | 起きること | 代わりに |
|---|---|---|
@Transactional、@Lock、@Query の SQL |
ストアの機能にそれらがない (functions と、Realtime があれば changes はある)。このストアのリポジトリがそれらを使うとビルドが失敗し、ビルドのデフォルトのストアが supabase のときの @Transactional の Bean も同じ。メッセージに対処が示される |
データベース関数、または db.url |
@MappedCollection を持つエンティティ |
InvalidDataAccessApiUsageException。集約の行は、トランザクションの中でまとめて書き込まれるため |
db.url、または子を独自のリポジトリを持つエンティティにする |
Distinct |
InvalidDataAccessApiUsageException |
データベース関数、または db.url |
| 大文字と小文字を区別しない順序 | InvalidDataAccessApiUsageException |
小文字のテキストを持つ列、または db.url |
LessThan、Between、In などへの IgnoreCase |
InvalidDataAccessApiUsageException |
db.url |
他の集約への参照は普通の列なので、動きます。関連する行の埋め込みと upsert は使われません。
ビルドが知ることができるもの。 スターターは自分のストアをビルドに伝え (@DataStoreDeclaration、ストアを参照)、ビルドは application.yml または application.properties (プロファイルなし) から spring.supabase.url を読みます。spring.supabase.url があり、spring.supabase.db.url、spring.datasource.url、spring.data.store がなければ、デフォルトのストアは supabase で、コードの生成時に検査されます。spring.supabase.db.url だけが設定されているときは、ビルドはデフォルトのストアを判断できず、検査はアプリケーションの起動時に行われます。
SQL: db.url とプーラー
spring:
supabase:
db:
url: postgresql://postgres:${DB_PASSWORD}@db.abcd.supabase.co:5432/postgres
これがあれば、データスターターの SQL ストアのすべてが動きます。トランザクション、@Lock、@Query、JdbcClient、マイグレーションです。接続の種類は、アドレスから読み取られます。
| アドレス | 種類 | 備考 |
|---|---|---|
db.<ref>.supabase.co:5432 |
直接接続 | |
….pooler.supabase.com:5432 |
セッションプーラー | すべて動く |
….pooler.supabase.com:6543 |
トランザクションプーラー | 起動時に警告。トランザクションの間でセッションを保持しないので、プリペアドステートメント、アドバイザリーロック、LISTEN はこれを通しては動かない |
データベースのアドレスでないものは、起動を失敗させます。
SQL での行レベルセキュリティ
db.url 上の SQL は、そのアドレスのユーザーとして実行されます。通常は postgres で、行レベルセキュリティを通過します。spring.supabase.db.rls: user にすると、すべてのトランザクションと、トランザクションの外のすべてのステートメントが、REST API と同じように、呼び出し元として実行されます。
| 呼び出し元 | データベースのセッション |
|---|---|
| サインインしたユーザー | ロール authenticated と、request.jwt.claims に入るトークンのクレーム。auth.uid()、auth.jwt()、ポリシーがそれを見る |
| 誰もいない | ロール anon |
asServiceRole の中 |
何も変更されない。ステートメントはアドレスのユーザーとして実行される |
- トランザクションの中では、ロールとクレームはそのトランザクションだけに設定されます (
set local)。 - トランザクションの外では、接続に設定され、プールに戻る前に取り除かれます。リセットに失敗した接続は閉じられ、再利用されません。
- ロールは固定された二つの名前のどちらかで、クレームは値として渡されます。SQL のテキストに書き込まれることはありません。
- 変更されるのは
db.urlのデータソースだけです。 - サインインしたユーザーのトークンにクレームがなければ、
PermissionDeniedDataAccessExceptionです。 - トランザクションプーラー (ポート 6543) を通すと、
rls: userは起動を失敗させます。トランザクションの外で設定したロールが、別のクライアントのステートメントに使われるおそれがあるためです。
これは supabaseRlsSessionHook という Bean で、JdbcSessionHook の一つです。
データを守るのはデータベース
どちらの経路も、ユーザーに何ができるかは検査しません。それをするのはデータベースです。行レベルセキュリティ、列の権限 (grant update (name) …)、CHECK 制約です。anon キーで REST API に直接送ったリクエストも、アプリケーションからのリクエストと同じ答えを得ます。だから、ルールはデータベースになければなりません。
Spring (Java) との対応
Spring Data にはストアごとにモジュールがあります。ここでは、一つのリポジトリのインターフェースがどちらの経路でも動きます。REST ストアは、メモリ上のストアや SQL のストアと同じく、このプロジェクトの Spring Data の DataStore です。