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 は、テンプレートが型に応じて使うマッパーです。

トランザクションとタイムアウト

複数のデータベース

各 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 な値を返します。

関連項目