
# SQL のロギング

リポジトリとテンプレートが実行するすべての文はログに出されます。SQL とその時間は debug で、バインドされた値は trace で、遅い文は warn で出されます。4 つのプロパティが、ログレベルに触れずに表示されるものを変えます: `spring.data.jdbc.show-sql`、`format-sql`、`show-parameters`、`slow-query-threshold`。

## 使う理由

ページが遅いときやクエリが誤った行を返すとき、最初の問いは「どの SQL が、どの値で実行されたか?」です。ログがそれに答えます。本番では値が個人データや秘密であることがあるため、trace に保たれ、名前が秘密に見えるものはマスクされます。

## 例

```properties
# 開発: 文と値を info で、複数行に。
spring.data.jdbc.show-sql=true
spring.data.jdbc.format-sql=true
spring.data.jdbc.show-parameters=true

# 本番: 遅い文だけを warn で。
spring.data.jdbc.slow-query-threshold=500ms
```

```text
INFO  spring.jdbc.core.StatementCreatorUtils  [dataSource tx#12 Catalog.find]   title = Dune (String)
INFO  spring.jdbc.core.JdbcTemplate  [dataSource tx#12 Catalog.find] select * from "books" where "title" = ?  (1 row, 3 ms) {request=7f3a}
WARN  spring.jdbc.core.JdbcTemplate  [dataSource] slow statement, 812 ms: select ...
```

## ロガー

| ロガー | レベル | 内容 |
|---|---|---|
| `spring.jdbc.core.JdbcTemplate` | debug | 各文、その時間、その行数。失敗したものはその時間とともに。 |
| `spring.jdbc.core.StatementCreatorUtils` | trace | バインドされた値。それぞれがバインドされた名前とともに。 |
| `spring.jdbc.core.JdbcTemplate` | warn | `slow-query-threshold` より遅い文。 |
| `spring.sql.migration` | info | 適用したマイグレーション: バージョン、説明、件数。値は決して出さない。 |

行は `[dataSource tx#12 Catalog.find]` で始まります。データソースの名前と、トランザクションの中ではその番号と名前です。Web スターターのリクエスト ID が設定されていれば `{request=7f3a}` で終わるため、遅いページからその文にたどり着けます。

## スイッチ

| キー | デフォルト | 意味 |
|---|---|---|
| `spring.data.jdbc.show-sql` | `false` | 文を debug ではなく info で出し、デフォルトのレベルで表示されるようにする。Spring Boot の `spring.jpa.show-sql`。 |
| `spring.data.jdbc.format-sql` | `false` | SQL を複数行に、主な句ごとに一行で。 |
| `spring.data.jdbc.show-parameters` | `false` | バインドされた値を trace ではなく info で出す。秘密に見える名前はマスクされたまま。 |
| `spring.data.jdbc.slow-query-threshold` | なし | これより遅い文は、debug のレベルにかかわらず warn でログに出される。 |

同じスイッチは、`logging.level.spring.jdbc.core.JdbcTemplate=debug` と `logging.level.spring.jdbc.core.StatementCreatorUtils=trace` でロガーごとにも設定できます。

## リリースビルドでは

`show-sql`、`format-sql`、`show-parameters` の働きは独立したモジュールにあり、ジェネレーターは `spring.data.jdbc.show-sql` (プロファイルのない `application.yml` または `application.properties`) でそれをビルドに含めます。

- `true`: すべてのビルドに含める。
- `false`: どのビルドにも含めない。コードは一切ない。
- 未設定: デバッグビルドとプロファイルビルドだけ。リリースビルドにはそのコードがない。プロファイル (`application-dev.yml`) は、デバッグ実行でスイッチを有効にできる。プロファイルなしの設定が設定していないのに、プロファイルが `show-sql` を設定すると、ビルドが警告する。リリースビルドにはそのコードがないためである。

`slow-query-threshold` はすべてのビルドに残るので、遅い文は warn でログに出されます。モジュールがなければ、文は debug で、その値は trace で、ロガーの設定どおりに出ます。

## 値の表示

各値は、それがバインドされた名前とともにログに出されます。リポジトリの `save`、派生クエリ、`delete` の列、または `@Query` や名前付きのテンプレートの `:name` です。

- **秘密に見える名前はマスクされます。** 大文字小文字と区切り文字を無視して、`password`、`passwd`、`passphrase`、`secret`、`credential`、`token`、`apikey`、`privatekey`、`accesskey`、`signingkey`、`encryptionkey` を含む名前、または単語 `pwd` か `key` を持つ名前の値は、リポジトリのメソッドの行でも `******` と書かれます。そのため `password_hash`、`apiToken`、`clientSecret`、`sslpassword` はマスクされ、`monkey`、`keyword`、`tokenizer`、`secretary` はマスクされません。
- **名前のない値** (`JdbcTemplate` に渡した単なるリスト) は秘密と区別できません。Spring と同じく trace で表示され、`show-parameters` がそれを info にするとマスクされます。
- **秘密を隠す名前** (`pw`、`pin`) はマスクされません。ルールが認識できるように列に名前を付けるか、本番では trace を無効にしておいてください。
- **値が SQL の行に入ることは決してありません。** 常にパラメーターです。

## 起動時のストア

起動時のログで、データがどこに入るかがわかります。データソースのプールは、最初の接続で起動するときにそれを示します (既定の `schema: validate` では起動時です)。

```
sqlite - Starting... (sqlite:file:library.db, max-size 4)
sqlite - Start completed.
```

データソースのないリポジトリはデータをメモリに保持し、そのうち最初のリポジトリが一度だけ info で示します (ロガー `spring.data.memory.InMemoryDataStore`)。

```
memory - Starting... (in memory: the data lives until the application stops)
```

データベースで動かすつもりのアプリケーションにこの行が出るなら、`spring.datasource.url` がありません。

## URL の中のパスワード

URL のユーザー情報のパスワードは決してログに出されず、名前が秘密に見えるクエリパラメーター (`?password=...`、`sslpassword`、`token`) の値も同様です。プールの "Starting..." の行と URL についてのすべてのメッセージは `password=******` と示します。

## Spring (Java) との対応

```properties
logging.level.org.springframework.jdbc.core.JdbcTemplate=debug
logging.level.org.springframework.jdbc.core.StatementCreatorUtils=trace
```

ロガーは、`org.springframework.` を除いた Spring の名前を保っています。`show-sql`、`format-sql`、`show-parameters`、`slow-query-threshold` は、そうしたスイッチを持たない Spring Data JDBC に追加したものです (JPA の `spring.jpa.show-sql` が手本です)。Spring は値をマスクしません。

## 関連項目

- [JdbcTemplate と JdbcClient](jdbc.md)
- [ロギング](../spring-core-dart/logging/index.md)
- [すべてのプロパティ](properties.md)
