
# JdbcTemplate と JdbcClient

リポジトリが適切な道具でないとき (レポート、一括インポート、マッピングが知らない文) は、SQL を直接使います。スターターはプライマリーのデータソースの上に 3 つの Bean を作ります。`JdbcTemplate` (位置指定の `?` マーカー)、`NamedParameterJdbcTemplate` (`:name` マーカー)、`JdbcClient` (両者の上の Spring 6.1 の流れるような API) です。これらは実行中のトランザクションに参加し、エラーを `DataAccessException` に変換し、リポジトリと同じようにログを出します。

## 使う理由

リポジトリは集約をカバーします。行の集計 (`count`、`sum`、`group by`)、エンティティでないデータ、アプリケーションが手で調整する文には、依然として素の SQL が必要です。テンプレートは、接続の扱い、バインド、エラーの変換を取り除き、値をテキストに貼り付けず、常にパラメーターとして保ちます。

## 例

```dart
@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 のロギング](logging.md) を参照)。

```dart
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` 拡張は型付きの読み取りを提供します。

```dart
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` を得ます。

```dart
Reports(@Qualifier('stats') JdbcClient stats) : _stats = stats;
```

## Spring (Java) との対応

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

## 関連項目

- [@Query](query.md)
- [トランザクション](transactions.md)
- [SQL のロギング](logging.md)
