データ

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 アプリではパスワードがアプリに同梱され、スターターが警告する)

スターターは次のように選びます。優先順位が最も低いデフォルトなので、アプリケーションが自分で設定したものが優先されます。

@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

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}

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);
}

スカラーの結果は、その一つの列から読まれます。

@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}

スキーマ

テーブルは 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 の中 何も変更されない。ステートメントはアドレスのユーザーとして実行される

これは supabaseRlsSessionHook という Bean で、JdbcSessionHook の一つです。

データを守るのはデータベース

どちらの経路も、ユーザーに何ができるかは検査しません。それをするのはデータベースです。行レベルセキュリティ、列の権限 (grant update (name) …)、CHECK 制約です。anon キーで REST API に直接送ったリクエストも、アプリケーションからのリクエストと同じ答えを得ます。だから、ルールはデータベースになければなりません。

Spring (Java) との対応

Spring Data にはストアごとにモジュールがあります。ここでは、一つのリポジトリのインターフェースがどちらの経路でも動きます。REST ストアは、メモリ上のストアや SQL のストアと同じく、このプロジェクトの Spring Data の DataStore です。

関連項目