JdbcTemplate と JdbcClient
リポジトリが適切な道具でないとき (レポート、一括インポート、マッピングが知らない文) は、SQL を直接使います。スターターはプライマリーのデータソースの上に 3 つの Bean を作ります。JdbcTemplate (位置指定の ? マーカー)、NamedParameterJdbcTemplate (:name マーカー)、JdbcClient (両者の上の Spring 6.1 の流れるような API) です。これらは実行中のトランザクションに参加し、エラーを DataAccessException に変換し、リポジトリと同じようにログを出します。
使う理由
リポジトリは集約をカバーします。行の集計 (count、sum、group by)、エンティティでないデータ、アプリケーションが手で調整する文には、依然として素の SQL が必要です。テンプレートは、接続の扱い、バインド、エラーの変換を取り除き、値をテキストに貼り付けず、常にパラメーターとして保ちます。
例
@Service()
class Reports {
Reports(this.jdbc, this.named, this.client);
final JdbcTemplate jdbc;
final NamedParameterJdbcTemplate named;
final JdbcClient client;
Future<int> booksAfter(int year) =>
jdbc.queryForObject<int>('select count(*) from books where year > ?', [year]);
Future<List<String>> titles(int authorId) => named.queryForList<String>(
'select title from books where author_id = :author',
{'author': authorId},
);
Future<Book?> find(int id) => client
.sql('select * from books where id = :id')
.param('id', id)
.query<Book>() // ジェネレーターが記述するクラス: 列は名前で
.optional();
Future<int> rename(int id, String title) => client
.sql('update books set title = ? where id = ?')
.param(title)
.param(id)
.update();
}
JdbcTemplate
| メソッド | 戻り値 |
|---|---|
query<T>(sql, params, mapper) |
mapper でマッピングした各行。 |
queryWithExtractor<T>(sql, params, extractor) |
extractor が JdbcResult 全体から作るもの。 |
queryForObject<T>(sql, [params, mapper]) |
マッピングした唯一の行、またはその唯一の列を T として。行がなければ EmptyResultDataAccessException、複数なら IncorrectResultSizeDataAccessException。 |
queryForList<T>(sql, [params, mapper]) |
各行の唯一の列 (または各行をマッピングしたもの)。 |
queryForMap(sql, [params]) |
唯一の行を Map<String, Object?> として。 |
queryForMaps(sql, [params]) |
各行をマップとして。 |
queryForStream<T>(sql, params, mapper) |
データベースが送るそばから読む、マッピングした行の Stream。 |
update(sql, [params]) |
変更された行の数。 |
updateReturningKey(sql, [params]) |
挿入で生成されたキー。 |
updateWithKeyHolder(sql, params, holder) |
件数。キーは KeyHolder に (holder.keyAs<int>())。 |
batchUpdate(sql, batch) |
値のリストごとに実行する一つの文。件数。 |
execute(sql) |
パラメーターのない文 (DDL) を実行する。 |
params は List<Object?> で、順に ? マーカーにバインドされます。
NamedParameterJdbcTemplate
同じメソッドで、:name マーカーを使い、値は Map<String, Object?>、またはジェネレーターがクラスを記述するオブジェクト (そのプロパティを名前で) として与えます。コレクションの値は要素ごとに一つのマーカーに展開されます: where id in (:ids)。名前が秘密に見える値はログでマスクされます (SQL のロギング を参照)。
await named.update(
'insert into visits (page, at) values (:page, :at)',
{'page': '/books', 'at': DateTime.now()},
);
await named.batchUpdate('delete from visits where id = :id', [
{'id': 1},
{'id': 2},
]);
JdbcClient
| ステップ | 意味 |
|---|---|
client.sql(text) |
文を始める。 |
.param(name, value) |
名前付きの値。 |
.param(value) |
次の位置指定の値。 |
.params(map) または .params(list) |
複数の値を一度に。 |
.paramSource(object) |
オブジェクトのプロパティからの名前付きの値。 |
.query<T>([mapper]) |
クエリ。マッパーがなければ型 T で: 単純な型 (int、String、列挙型) なら唯一の列、Map<String, Object?> ならマップ、記述されたクラスならデータクラスのマッピング (author_name は authorName を埋める)。 |
.list()、.set()、.single()、.optional()、.stream() |
クエリの結果。 |
.update([keyHolder]) |
変更を実行し、変更された行を返す。 |
一つの文は名前付きか位置指定のパラメーターのどちらかを使い、両方は使いません。混ぜると InvalidDataAccessApiUsageException です。
行を手でマッピングする
RowMapper<T> は T Function(JdbcRow row) です。row['title'] は列をそのラベル (大文字小文字を問わない) で読み、JdbcRowReaders 拡張は型付きの読み取りを提供します。
Book mapBook(JdbcRow row) => Book(
id: row.int_('id'),
title: row.string('title'),
year: row.intOrNull('year'),
);
final books = await jdbc.query('select * from books', const [], mapBook);
| リーダー | 読むもの |
|---|---|
string、stringOrNull |
テキスト |
int_、intOrNull |
整数 |
double_、doubleOrNull |
数値 (int は拡張される) |
bool_、boolOrNull |
真偽値 (0 は false) |
dateTime、dateTimeOrNull |
時点 (ISO 8601 のテキストは解析される) |
bytesOrNull |
バイト |
null を受け取った非 null のリーダーは InvalidDataAccessApiUsageException で失敗します。OrNull の形を使ってください。SingleColumnRowMapper、ColumnMapRowMapper、DataClassRowMapper は、テンプレートが型に応じて使うマッパーです。
トランザクションとタイムアウト
@TransactionalメソッドやTransactionTemplateの中のテンプレートの文はトランザクションの接続で実行されます。外では、自分のために接続を取り、オートコミットで実行されます。spring.jdbc.template.query-timeoutは、テンプレートの Bean の各文を制限します (500ms、10s)。デフォルトはなしです。それを超えた文はQueryTimeoutExceptionです。
複数のデータベース
各 spring.datasources.<name> は、修飾子 <name> 付きの <name>JdbcTemplate、<name>NamedParameterJdbcTemplate、<name>JdbcClient を得ます。
Reports(@Qualifier('stats') JdbcClient stats) : _stats = stats;
Spring (Java) との対応
jdbc.queryForObject("select count(*) from books where year > ?", Integer.class, year);
client.sql("select * from books where id = :id").param("id", id).query(Book.class).optional();
API は Spring のものを Dart に合わせたものです。結果は Future か Stream、型は Class ではなく型引数 (query<Book>())、optional() は nullable な値を返します。