データベース関数

リポジトリのメソッドに付けた @Procedure('name') は、データベース関数を名前で呼び出します。メソッドのパラメーターが名前付きの引数になり、関数が返すものは、@Query の結果と同じように読まれます。

使う理由

データベースの中にあるべき処理があります。一緒に起きなければならない複数の書き込み、クライアントよりプランナーのほうがうまく扱えるクエリ、すべてのクライアントが従わなければならないルールです。関数は、REST API のようにトランザクションのないストアで、複数の書き込みをアトミックに行う方法でもあります。手で呼び出すには、その SQL、引数の順序、行のマッパーが必要です。@Procedure なら、名前とメソッドのシグネチャーだけです。

例

abstract interface class Accounts
    implements CrudRepository<Account, int> {
  // select * from "transfer"("from_id" => ?, "to_id" => ?, "amount" => ?)
  @Procedure('transfer')
  Future<void> transfer(int fromId, int toId, int amount);

  @Procedure('accounts_over')
  Future<List<Account>> over(int balance);
}
create function accounts_over(balance int) returns setof accounts
language sql stable as $$ select * from accounts where accounts.balance > $1 $$;

引数

結果

関数が返すものは、@Query の行と同じように読まれます。

メソッドが返すもの 何から
Future<List<Account>>、Future<Set<Account>>、Stream<Account> 行。リポジトリのエンティティ、または列から名前で組み立てられるアプリケーションのクラス。Stream は、購読されたときに関数を呼び出す。
Future<List<int>>、Future<Set<String>> 各行の一つの列。
Future<Account?>、Future<int> 一つの値。行がなければ、null 許容の型では null、そうでなければエラー。
Future<List<Map<String, Object?>>> マップとしての行。
Future<void> 何もない。関数が返すものは無視される。

ビルドがメソッドを検査し、誤りはリポジトリの問題の一つになります。

@Procedure の付いたメソッドは、名前が何であっても、派生クエリとして読まれることはありません。

ストア

リポジトリのストアは、データベース関数を持っていなければなりません (ストアとその機能 を参照)。関数のないストアでは、リポジトリは作成されるときに失敗し、ビルドがストアを知っている場合はビルド時に失敗します。

ストア 呼び出し
PostgreSQL 上の SQL select * from "name"("argument" => ?)。呼び出し元の現在のトランザクションの中で実行される。ロールバックは、関数が書き込んだものを取り消す。
SQLite 上の SQL 関数なし
メモリ上 関数なし
supabase (spring_boot_starter_supabase) POST /rest/v1/rpc/name (rpc は REST API 自身のパスです)。現在のユーザーとして。リクエストは一つなので、それ自体でアトミック。

エラー

失敗は、リポジトリの他のメソッドと同じく、DataAccessException です。

ジェネレーターが書くもの

ジェネレーターは、@Procedure メソッドごとに、ProcedureMethod の定数 (メソッドの名前、アノテーション、パラメーター、結果の形と要素) と、リポジトリの操作の呼び出しを書きます。

// For: @Procedure('accounts_over')
//      Future<List<Account>> over(int balance);
static const _over = ProcedureMethod(
  r'over',
  Procedure(r'accounts_over'),
  parameters: [r'balance'],
  element: ClassType<Account>(),
);

@override
Future<List<Account>> over(int balance) =>
    this.operations.procedure<List<Account>>(_over, [balance]);

定数は functions: としてリポジトリの操作に渡され、各メソッドは functions の StoreRequirement として渡されます。

ランタイム

生成されたコードの下には、ライブラリが直接使える二つの層があります。

ストア: FunctionDataStore.callFunction(name, arguments) は関数を呼び出し、その行を、列名から値へのマップとして返します。

final rows = await store.callFunction('restock', {
  'sku': 'A-1',
  'quantity': 5,
});

リポジトリの操作: ProcedureMethod は、一つの @Procedure メソッドを記述します (名前、アノテーション、パラメーター、結果の形と要素)。RepositoryOperations.procedure<R> と procedureStream<E> が、パラメーターの順に並べた引数でそれを呼び出します。

const named = ProcedureMethod(
  'named',
  Procedure('authors_named'),
  parameters: ['prefix'],
  element: ClassType<Author>(),
);

final authors = RepositoryFactory(
  mappingContext: mappingContext,
  converter: converter,
  stores: [store],
).operations<Author, int>(
  'Authors',
  annotations: const [UseStore('jdbc')],
  functions: const [named],
);

final found = await authors.procedure<List<Author>>(named, ['He']);

Spring (Java) との対応

Spring Data JPA の @Procedure("name") です。Spring Data JDBC にはありません。ストアの呼び出しは、SimpleJdbcCall.withFunctionName(name).execute(arguments) に当たります。

関連項目