PostgreSQL

スターターの隣に postgres パッケージを挙げ、ジェネレーターを実行し、postgresql:// の URL を指定します。ジェネレーターはパッケージの上に PostgresBinding と postgresJdbcDriver の Bean を書き、スターターの PostgresJdbcDriver と PostgresDialect が残りを行います。postgres パッケージはアプリケーションの依存関係で、決してスターターのものではありません。

使う理由

PostgreSQL はサーバーアプリケーションの一般的なデータベースです。複数のインスタンスがそれを共有し、本物の行ロックとすべての分離レベルを持ち、制約を強制します。スターターの PostgreSQL のサポートは、そのトランザクションのルールを測定する基準です。304 のシナリオを PostgreSQL に対して、スターターと Spring Boot のアプリケーションの両方で実行し、その結果を比較しています。

例

# pubspec.yaml
dependencies:
  spring_boot_starter_data: ^0.9.0
  postgres: ^3.5.0
# lib/resources/application.properties
spring.datasource.url=postgresql://db.example.com:5432/shop?sslmode=verify-full
spring.datasource.username=shop
spring.datasource.password=${SHOP_DB_PASSWORD}
spring.datasource.postgresql.application-name=shop-api
spring.datasource.postgresql.search-path=shop,public
spring.datasource.postgresql.connect-timeout=5s

# または、Spring Boot から貼り付けたとおりに:
# spring.datasource.url=jdbc:postgresql://db.example.com:5432/shop

URL

設定

キー デフォルト 意味
spring.datasource.postgresql.sslmode prefer 接続が TLS を使うかどうかとその方法: disable、allow、prefer、require、verify-ca、verify-full。
spring.datasource.postgresql.ssl-root-cert システムのルート verify-* モードがサーバーを照合する認証局の PEM ファイル。
spring.datasource.postgresql.connect-timeout 15s 接続と TLS ハンドシェイクを待つ最長時間: 500ms、30s、1m、またはミリ秒。このキーは PT30S を受け取らない。
spring.datasource.postgresql.application-name なし pg_stat_activity に表示される。
spring.datasource.postgresql.search-path サーバーのもの search_path のスキーマ。カンマ区切り。

同じキーが、spring.datasources.<name>.postgresql.* の下に、spring.datasource.postgres.* (ドライバーの名前が優先される) として、そして環境変数 (SPRING_DATASOURCE_POSTGRESQL_SSLMODE=verify-full、名前付きのデータベースには SPRING_DATASOURCES_SHOP_POSTGRESQL_SSLMODE) としても存在します。

TLS

sslmode は libpq のものです。

モード 暗号化 証明書のチェック
disable なし なし
allow、prefer (デフォルト) サーバーが TLS を提供すれば。そうでなければ平文 なし
require あり なし
verify-ca、verify-full あり あり。ホスト名も (verify-ca は verify-full と同じく厳格)

デフォルトの prefer は、サーバーに TLS がなければ平文で接続しますが、接続を遮断できる攻撃者はそれを強制できます。フォールバックすると、ドライバーはデータベースごとに一度警告をログに出します。開発用のデータベース以外には、require か verify-full を使ってください。

値

Dart PostgreSQL
int BIGINT
String、列挙型 TEXT
bool BOOLEAN
double DOUBLE PRECISION
DateTime TIMESTAMPTZ (時点。UTC で読み戻される)
Uint8List BYTEA
BigInt NUMERIC

生成される ID は BIGINT GENERATED BY DEFAULT AS IDENTITY で、RETURNING で読み戻されます。自分で書いた ID はシーケンスを進めません。

トランザクション

ロック

@Lock(LockMode.pessimisticWrite) は FOR UPDATE、pessimisticRead は FOR SHARE です。ゼロの timeout は NOWAIT、より長いものはクエリの前の SET LOCAL lock_timeout、skipLocked は SKIP LOCKED です (ゼロのタイムアウトより優先されます: サーバーは両方の語を拒否するためです)。SQLite と異なり、@Lock のクエリはトランザクションの最初の文である必要はありません。ロック を参照してください。

エラー

エラーは SQL ステートで変換され、サーバーのメッセージを持ちますが、バインドされた値やパスワードは決して持ちません。

SQL ステート 例外
23505 DuplicateKeyException (制約の名前付き)
その他の 23xxx、22xxx DataIntegrityViolationException
40001 CannotSerializeTransactionException
40P01 DeadlockLoserDataAccessException
55P03 (NOWAIT、lock_timeout) CannotAcquireLockException
57014 QueryTimeoutException
42601、42P01、42703 とその他の構文と名前のエラー BadSqlGrammarException
25006 InvalidDataAccessResourceUsageException
42501 (権限がない、行レベルセキュリティのポリシー) PermissionDeniedDataAccessException
08xxx、28xxx、53xxx、57P01、存在しないデータベース DataAccessResourceFailureException

メッセージからは、DETAIL の行 (重複キーのものは値を含みます) と、invalid input syntax for type integer の拒否された値が取り除かれます。

データベースが拒否する引数

長い In のリスト

派生の In / NotIn はリストを一つの配列パラメーターとしてバインドする (= any($1)、<> all($1)) ため、どの長さでも動きます。@Query の in (:ids) は値ごとに一つのマーカーに展開されます。プロトコルの 65 535 個のパラメーターを超えると、文が送られる前に InvalidDataAccessApiUsageException が投げられます。

テキストの順序

テキストに対する ORDER BY と範囲の演算子は、データベースの照合順序を使います。en_US.UTF-8 で作ったデータベースは a_b を Cryptonomicon より前に置きますが、メモリ上のストアと SQLite はコードユニットで比較します。IgnoreCase は lower() で、ロケールが知っている文字を畳み込みます (C: ASCII のみ)。

スキーマ

PostgreSQL でテストを実行する

サーバーを必要とするスターター自身のテストは、SPRING_TEST_POSTGRES_URL が設定されていればそれに対して実行され、そうでなければ Docker があれば PostgreSQL のコンテナを起動します (タグ postgres)。

docker run --rm -d --name spring-pg-test -e POSTGRES_PASSWORD=test -p 55432:5432 postgres:17
SPRING_TEST_POSTGRES_URL=postgresql://postgres:test@localhost:55432/postgres dart test -t postgres
docker stop spring-pg-test

Spring (Java) との対応

spring.datasource.url=jdbc:postgresql://db.example.com:5432/shop?sslmode=verify-full

同じ URL がここでも動きます。エラーは Spring の PostgreSQL のエラーコードの表に対応するため、クラスは SQL ステートで変換する Spring 7 の JdbcTemplate より細かくなります。たとえば、Spring が CannotAcquireLockException を返すところで CannotSerializeTransactionException です。スーパータイプは同じなので、ConcurrencyFailureException を捕まえるリトライのコードは同じように動きます。

関連項目