
# データ

Supabase プロジェクトのデータには、Spring Data でアクセスします。[spring_boot_starter_data](../spring-boot-starter-data/index.md) のエンティティ、リポジトリ、派生クエリ、`Pageable`、`Sort` です。データベースへの経路は二つあり、リポジトリがどちらを使うかは設定が決めます。

## 使う理由

Supabase のプロジェクトは、データベースを二通りに提供します。ユーザーのトークンがあればどこからでも使える REST API (PostgREST) と、パスワードを持つサーバーのための素の PostgreSQL です。Flutter アプリが使えるのは前者だけです。サーバーはトランザクションやロックが欲しいことがあり、それがあるのは後者だけです。リポジトリのインターフェースはどちらでも同じなので、選択はプロパティ一つで済み、アプリケーションは起動時に一度、どちらの経路にいるかを伝えます。

## 例

```dart
@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)` は一つのリクエストです。

```text
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`](credentials.md))。行レベルセキュリティが適用される | アドレスのユーザー (通常は `postgres` で、行レベルセキュリティを通過する)。`db.rls: user` なら現在のユーザー |
| `@Transactional`、`@Lock`、SQL の `@Query`、`JdbcClient` | 使えない | 使える |
| `@MappedCollection` | 使えない | 使える |
| 場所 | サーバー、Flutter アプリ、Web | サーバー (Flutter アプリではパスワードがアプリに同梱され、スターターが警告する) |

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

- `spring.supabase.db.url` が設定されている: `spring.datasource.url` がそのアドレスになります。アプリケーションは、他の [PostgreSQL](../spring-boot-starter-data/postgresql.md) のデータソースと同じく、`postgres` ドライバーのパッケージを依存関係に加えます。
- 設定されておらず、アプリケーションに独自の `spring.datasource.url` もない: `spring.data.store` が `supabase` になります。
- アプリケーションに独自の `spring.datasource.url` があり、`db.url` がない: デフォルトのストアはアプリケーションのもののままです。リポジトリは `@UseStore('supabase')` で REST API を使います。

```dart
@UseStore('supabase')
abstract interface class Todos implements ListCrudRepository<Todo, int> {}
```

起動時に、経路が一度だけログに出ます。パスワードは出ません。

```text
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)` は、一つのパラメーターを送ります。

```text
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`) |

```dart
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` です。他の誰かがその行を変更または削除したか、呼び出し元にそれを更新する権限がありません。

```dart
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`](../spring-boot-starter-data/json-columns.md) を付けたプロパティ (アプリケーションのクラス、リスト、マップ) は、`jsonb` または `json` の列に入ります。REST ストアは、それをネストした JSON として送り、応答をクラスに読み戻します。`@Json` がなければ、REST ストアは単なる `Map` や `List` をそのまま JSON として送ります。`db.url` があるとき、ストアはデータスターターの SQL のストアであり、`@Json` のない `Map`、`List`、`Set` を、リポジトリが作られるときに直し方とともに拒否します。配列の列 (`tags text[]`) に入る単純な値の `List` は、そのまま使えます。

## データベース関数

`db.url` なしでアトミックにしなければならない処理には、データベース関数を書き、[`@Procedure`](../spring-boot-starter-data/database-functions.md) でリポジトリに宣言します。現在のユーザーとして、一つのリクエスト `POST /rest/v1/rpc/<name>` で呼び出されます (`rpc` は REST API 自身のパスです)。

```dart
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"(…)` を呼び出します。

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

```dart
@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`)。行を返す関数は、その行を返します。スカラーは、関数名の列を一つ持つ一行になります。何も返さなければ、行はありません。

```dart
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](realtime.md) から報告します。そのため、リポジトリは、データスターターの[行の変更](../spring-boot-starter-data/changes.md)の二種類のメソッドを持てます。

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

```dart
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`](../spring-boot-starter-data/errors.md) で、どちらの経路でも同じです。データベース自身のコードは、SQL の経路と同じように変換されます。

| REST API の応答 | 例外 |
|---|---|
| PostgreSQL のコード: `23505` (重複キー) | `DuplicateKeyException` |
| `23503` (外部キー) | `DataIntegrityViolationException` |
| `42501` (権限、行レベルセキュリティのポリシー) | `PermissionDeniedDataAccessException` |
| その他の PostgreSQL のコード | [PostgreSQL](../spring-boot-starter-data/postgresql.md) の方言がそのコードに対して返すもの |
| `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 | ストアの[機能](../spring-boot-starter-data/stores.md)にそれらがない (`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`、[ストア](../spring-boot-starter-data/stores.md)を参照)、ビルドは `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 とプーラー

```yaml
spring:
  supabase:
    db:
      url: postgresql://postgres:${DB_PASSWORD}@db.abcd.supabase.co:5432/postgres
```

これがあれば、データスターターの SQL ストアのすべてが動きます。[トランザクション](../spring-boot-starter-data/transactions.md)、[`@Lock`](../spring-boot-starter-data/locks.md)、`@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`](../spring-boot-starter-data/session-hooks.md) の一つです。

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

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

## Spring (Java) との対応

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

## 関連項目

- [リポジトリ](../spring-boot-starter-data/repositories.md)
- [派生クエリ](../spring-boot-starter-data/derived-queries.md)
- [ストアとその機能](../spring-boot-starter-data/stores.md)
- [エラー](../spring-boot-starter-data/errors.md)
- [誰として呼び出すか](credentials.md)
- [Realtime](realtime.md)
