
# データソース

データソースとは、アプリケーションが接続するデータベースと、その接続のプールです。`spring.datasource.url` を設定すると、スターターはプライマリーの `DataSource` と、その上のすべてを作ります。トランザクションマネージャー、`JdbcTemplate`、`NamedParameterJdbcTemplate`、`JdbcClient` です。各 `spring.datasources.<name>.url` は、独自の Bean を持つ別のデータベースを追加します。

## 使う理由

データベースはコードではなく設定です。開発ではファイル、本番ではサーバー、テストではメモリ上のデータベースです。プロパティを使えば、アプリケーションではなく URL を変えます。プールはいくつかの接続を開いたままにするため、リクエストのたびに新しい接続のコストを払う必要がありません。そしてスターターは、マイグレーションが実行される前にどのコードもデータベースに触れないようにします。

## 例

```properties
# lib/resources/application.properties
spring.datasource.url=postgresql://db.example.com:5432/shop
spring.datasource.username=shop
spring.datasource.password=${SHOP_DB_PASSWORD}
spring.datasource.pool.max-size=10
spring.datasource.pool.connection-timeout=10s

# 2 つ目のデータベース: 独自の Bean、修飾子、設定。
spring.datasources.stats.url=sqlite:file:stats.db
spring.datasources.stats.sql.migration.locations=resources:db/stats
```

```dart
@UseDataSource('stats')                       // 2 つ目のデータベース上のリポジトリ
abstract interface class VisitRepository implements ListCrudRepository<Visit, int> {}

@Service()
class Reports {
  Reports(this.jdbc, @Qualifier('stats') this.statsJdbc);

  final JdbcTemplate jdbc;                    // プライマリーのデータベース
  final JdbcTemplate statsJdbc;               // stats のデータベース

  @Transactional(transactionManager: 'stats')
  Future<int> visits() => statsJdbc.queryForObject<int>('select count(*) from visits');
}

@SpringBootApplication()
Future<void> main(List<String> args) => runApplicationAsync(args);
```

## URL とドライバー

| URL | データベース |
|---|---|
| `sqlite:file:books.db` | SQLite のファイル。`spring.datasource.sqlite.base-directory` (デフォルトは作業ディレクトリ) からの相対。 |
| `sqlite::memory:` | メモリ上の SQLite データベース。接続ごとに独自のものを持つ: `pool.max-size=1` を使う。 |
| `postgresql://user:password@host:5432/shop?sslmode=require` | PostgreSQL ([PostgreSQL](postgresql.md) を参照)。 |
| `jdbc:postgresql://host/shop` | 同じもの。先頭の `jdbc:` は取り除かれるため、Spring Boot から貼り付けた URL が動く。 |

- スターターはドライバーを内蔵していません。`pubspec.yaml` に `sqlite3` か `postgres` を挙げてジェネレーターを実行すると、見つけたドライバーのパッケージごとに `JdbcDriver` の Bean (`SqliteBinding`、`PostgresBinding`) を書きます。
- URL のスキームがドライバーを選びます。2 つがそのスキームを扱う場合は、`spring.datasource.driver` で一つを指定します (`sqlite3`、`postgres`)。
- 挙げたどのドライバーも扱わないスキームは、追加すべきパッケージを示して起動を止めます。
- `username` と `password` は、URL がそれらを持たない場合に使われます。パスワードは決してログに出されません。プールの "Starting..." の行とすべてのメッセージは `password=******` と示します。

## プール

| キー | デフォルト | 意味 |
|---|---|---|
| `pool.max-size` | `10` | 同時に持つ最大の接続数。1 以上。 |
| `pool.min-idle` | `0` | アイドル時に開いておく接続。0 から `max-size` まで。Hikari は `max-size` と同じ数を保つ。 |
| `pool.connection-timeout` | `30s` | 接続を待つ最長時間。その後 `CannotGetJdbcConnectionException`。 |
| `pool.idle-timeout` | `10m` | これより長くアイドルな `min-idle` を超える接続は閉じられる。`0` は永久に保つ。 |
| `pool.max-lifetime` | `30m` | これより古い接続は、プールに戻ったときに閉じられる。上限なしは `0`。 |
| `pool.validation` | `true` | プールで待っていた接続は、渡される前に `isValid` でチェックされる。 |

各キーは、プライマリーのデータベースでは `spring.datasource.` の下に、名前付きのものでは `spring.datasources.<name>.` の下にあります。プールはアプリケーションコンテキストが閉じるときに閉じられます。

## Bean

`spring.datasource.url` があると、スターターは次の Bean を作ります。それぞれ、アプリケーションがその型の Bean を宣言していればスキップされます。

| Bean | 内容 |
|---|---|
| `dataSource` | プライマリーの `DataSource` (プール、`@Primary`)。最初の接続の前にスキーマが準備される。 |
| `transactionManager` | その上の `DataSourceTransactionManager`。データソースがなければ、代わりにメモリ上のトランザクションマネージャー。 |
| `jdbcTemplate`、`namedParameterJdbcTemplate`、`jdbcClient` | プライマリーのデータソースの上に。 |
| `transactionTemplate` | 唯一のトランザクションマネージャーの上に。 |
| `<name>DataSource`、`<name>TransactionManager`、`<name>JdbcTemplate`、`<name>NamedParameterJdbcTemplate`、`<name>JdbcClient` | 各 `spring.datasources.<name>.url` のために、修飾子 `<name>` 付きで。これらはフォールバックなので、型による注入は引き続きプライマリーを見つける。 |
| `jdbcLogSettings` | `spring.data.jdbc.*` のログのスイッチ。`spring.data.jdbc.show-sql` でビルドに含まれる。[SQL のログ](logging.md#リリースビルドでは) を参照。 |
| `jdbcSlowQueryLogSettings` | `jdbcLogSettings` のないビルドで、`spring.data.jdbc.slow-query-threshold` だけを読む。 |
| `dataFailureAnalyzer` | どのドライバーも扱わない URL、失敗したマイグレーション、合わないスキーマを説明する。起動時チェック: `spring.main.startup-checks.enabled` でビルドに含まれ、`true` でない限りデバッグビルドとプロファイルビルドだけ。 |
| `dbHealthContributor` | Actuator の `db` のヘルス。データソースごとに一つのインジケーター。 |

`@UseStore` のないリポジトリは、プライマリーのデータソースがあれば `jdbc` ストアを、なければ `memory` ストアを使います。

## 名前付きのデータベース

`spring.datasources.<name>.*` は `spring.datasource.*` と同じキー (URL、クレデンシャル、ドライバー、プール、`sqlite.*`、`postgresql.*`) に加えて、独自のスキーマの設定を受け取ります: `sql.init.*`、`sql.migration.*`、`data.jdbc.schema`。

- リポジトリは `@UseDataSource('<name>')` で、トランザクションは `@Transactional(transactionManager: '<name>')` で、注入は `@Qualifier('<name>')` でそれを使います。
- 名前は、キーを列挙するプロパティソース (ファイル、コマンドライン) の中で見つけられ、環境変数だけからは見つけられません。URL をファイルで宣言し、変数で上書きしてください。

## 起動の順序

**スキーマはどの使用より前に準備されます。** 起動時、コンテキストはマイグレーションを適用し、エンティティをスキーマと照合し、失敗するとそのメッセージとともに起動を止めます。データソース自身が、それが終わるまですべての接続を差し止めるため、クエリを開始するリポジトリ、`JdbcTemplate`、ランナー、同期的な `@PostConstruct` が、マイグレーションされていないデータベースを見ることは決してありません。

チェックまたは作成されるエンティティは、そのデータソース上のリポジトリのものと、その子です。どのリポジトリも使わないエンティティは、アプリケーション自身のテーブルです。

アプリケーションが自分で宣言した `DataSource` の Bean も、起動時に同じ準備を受けますが、早期のクエリを差し止めはしません。

**非同期に起動してください。** スキーマは接続の上で準備されますが、Dart は `await` なしにそれを待てません。SQL のデータソースがある場合は、`await runApplicationAsync(args)` (`SpringApplication.runAsync`。テストでは `ApplicationContextRunner.runAsync`) でアプリケーションを起動してください。同期的な `runApplication(args)` は、その旨を示すレポートとともに起動時に失敗します。

## Environment からのドライバーの設定

すべてのドライバーのキー (`sqlite.*`、`postgresql.*`) は Environment を通して読まれるため、環境変数、コマンドライン引数、ファイルのエントリーでもあります。

```bash
SPRING_DATASOURCE_POSTGRESQL_SSLMODE=verify-full
SPRING_DATASOURCES_SHOP_SQLITE_BUSYTIMEOUT=2000
```

ドライバーが知らないキーは拒否されます。ドライバーのキーは、URL のスキームのもとと、ドライバーの名前のもとで読まれ、ドライバーの名前が優先されます: `spring.datasource.sqlite3.busy-timeout` は `sqlite.busy-timeout`、`spring.datasource.postgres.sslmode` は `postgresql.sslmode` です。

## ヘルス

Actuator がある場合、`db` のヘルスコントリビューターが各データソースをチェックします。接続を取得でき、それが有効なら `UP`、そうでなければエラー付きの `DOWN` です。

```json
{"status": "UP", "details": {"database": "PostgreSQL", "validationQuery": "isValid()"}}
```

`management.health.db.enabled=false` で無効になります。

## Spring (Java) との対応

```properties
spring.datasource.url=jdbc:postgresql://db.example.com:5432/shop
spring.datasource.hikari.maximum-pool-size=10
```

プールはスターター独自のもので、`spring.datasource.hikari.*` ではなく `spring.datasource.pool.*` の下で設定します。2 つ目のデータベースは、独自の `DataSource`、`JdbcTemplate`、`@EnableJdbcRepositories` を持つ 2 つ目の `@Configuration` ではなく、プロパティ (`spring.datasources.<name>`) です。

## 関連項目

- [SQLite](sqlite.md)
- [PostgreSQL](postgresql.md)
- [スキーマとマイグレーション](schema.md)
- [すべてのプロパティ](properties.md)
