データソース
データソースとは、アプリケーションが接続するデータベースと、その接続のプールです。spring.datasource.url を設定すると、スターターはプライマリーの DataSource と、その上のすべてを作ります。トランザクションマネージャー、JdbcTemplate、NamedParameterJdbcTemplate、JdbcClient です。各 spring.datasources.<name>.url は、独自の Bean を持つ別のデータベースを追加します。
使う理由
データベースはコードではなく設定です。開発ではファイル、本番ではサーバー、テストではメモリ上のデータベースです。プロパティを使えば、アプリケーションではなく URL を変えます。プールはいくつかの接続を開いたままにするため、リクエストのたびに新しい接続のコストを払う必要がありません。そしてスターターは、マイグレーションが実行される前にどのコードもデータベースに触れないようにします。
例
# 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
@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 を参照)。 |
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 のログ を参照。 |
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 を通して読まれるため、環境変数、コマンドライン引数、ファイルのエントリーでもあります。
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 です。
{"status": "UP", "details": {"database": "PostgreSQL", "validationQuery": "isValid()"}}
management.health.db.enabled=false で無効になります。
Spring (Java) との対応
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>) です。