データベース関数
リポジトリのメソッドに付けた @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 $$;
引数
- メソッドの各パラメーターが関数の一つの引数になり、名前で渡されます。
- 名前は、列と同じく、パラメーターの名前をスネークケースにしたものです。
accountIdはaccount_idになります。マッピングの命名戦略が名前を決めます。 - 値は、列の値と同じように変換されます。enum はその
nameです。 - リストは、一つの配列の引数になります。
@Procedure('schema.name')は、サーチパスの外にある関数を呼び出します。
結果
関数が返すものは、@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> |
何もない。関数が返すものは無視される。 |
ビルドがメソッドを検査し、誤りはリポジトリの問題の一つになります。
PageやSliceは返せません。関数は、件数を数えられるクエリではないためです。PageableやSortのパラメーターはありません。メソッドのパラメーターは、どれも関数の引数です。@Procedureは、@Query、@Modifying、@Lockと一緒には使えません。- 関数の名前は空ではいけません。
@Procedure の付いたメソッドは、名前が何であっても、派生クエリとして読まれることはありません。
ストア
リポジトリのストアは、データベース関数を持っていなければなりません (ストアとその機能 を参照)。関数のないストアでは、リポジトリは作成されるときに失敗し、ビルドがストアを知っている場合はビルド時に失敗します。
| ストア | 呼び出し |
|---|---|
| PostgreSQL 上の SQL | select * from "name"("argument" => ?)。呼び出し元の現在のトランザクションの中で実行される。ロールバックは、関数が書き込んだものを取り消す。 |
| SQLite 上の SQL | 関数なし |
| メモリ上 | 関数なし |
supabase (spring_boot_starter_supabase) |
POST /rest/v1/rpc/name (rpc は REST API 自身のパスです)。現在のユーザーとして。リクエストは一つなので、それ自体でアトミック。 |
エラー
失敗は、リポジトリの他のメソッドと同じく、DataAccessException です。
- 存在しない関数は、PostgreSQL では
BadSqlGrammarExceptionです。 - 呼び出し元にない権限、または関数がステート
42501で発生させた例外は、PermissionDeniedDataAccessExceptionです。 - 引数の数が違うのは、
InvalidDataAccessApiUsageExceptionです。
ジェネレーターが書くもの
ジェネレーターは、@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) に当たります。