Hibernate Reactiveの使用
Hibernate Reactiveは、Hibernate ORMのリアクティブAPIで、ノンブロッキングのデータベースドライバと、データベースとのインタラクションのリアクティブなスタイルをサポートしています。
|
Hibernate Reactiveは、 Hibernate ORM の置き換えでも、Hibernate ORMの将来でもありません。これは、高い並行性が必要なリアクティブなユースケース向けに調整された別のスタックです。 また、デフォルトのRESTレイヤであるQuarkus REST（旧RESTEasy Reactive）を使用する場合、Hibernate Reactiveを使用する必要はありません。 Quarkus RESTとHibernate ORMを併用することはまったく問題ありません。 高い同時性が必要ない場合やリアクティブパラダイムに慣れていない場合は、Hibernate ORMを使用することをお勧めします。 |
|
Hibernate Reactiveは、 Hibernate ORMガイド で説明されている同じアノテーションと、ほとんどの設定で動作します。このガイドでは、Hibernate Reactiveに特有のものにのみ焦点を当てます。 |
|
この技術は、previewと考えられています。 preview では、下位互換性やエコシステムでの存在は保証されていません。具体的な改善には設定や API の変更が必要になるかもしれませんが、 stable になるための計画は現在進行中です。フィードバックは メーリングリスト や GitHub の課題管理 で受け付けています。 とりうるステータスの完全なリストについては、 FAQの項目 を参照してください。 |
ソリューション
次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。
Gitレポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.git 、 アーカイブ をダウンロードします。
ソリューションは hibernate-reactive-quickstart ディレクトリ にあります。
Hibernate Reactiveのセットアップと設定
QuarkusでHibernate Reactiveを使用する場合、以下が必要です:
-
application.propertiesに設定を追加 -
エンティティに
@Entityやその他のマッピングアノテーションを通常通り付与
その他の設定の必要性は自動化されています。Quarkusは、いくつかの定見に基づいた選択と経験に基づいた推測を行います。
以下の依存関係をプロジェクトに追加してください:
-
Hibernate Reactive エクステンション:
io.quarkus:quarkus-hibernate-reactive -
選択したデータベース用の Reactive SQLクライアントエクステンション。以下のオプションが利用できます:
-
quarkus-reactive-pg-client: PostgreSQLやCockroachDBのクライアント -
quarkus-reactive-mysql-client: MySQL または MariaDBのクライアント -
quarkus-reactive-mssql-client: Microsoft SQL Server のクライアント -
quarkus-reactive-db2-client: IBM Db2 のクライアント -
quarkus-reactive-oracle-client: Oracleのクライアント
-
例えば
<!-- Hibernate Reactive dependency -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-hibernate-reactive</artifactId>
</dependency>
<!-- Reactive SQL client for PostgreSQL -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-reactive-pg-client</artifactId>
</dependency>// Hibernate Reactive dependency
implementation("io.quarkus:quarkus-hibernate-reactive")
Reactive SQL client for PostgreSQL
implementation("io.quarkus:quarkus-reactive-pg-client")@Entity でパーシステント・オブジェクトにアノテーションを付け、 application.properties で関連する設定プロパティを追加します。
application.properties# datasource configuration
quarkus.datasource.db-kind = postgresql
quarkus.datasource.username = quarkus_test
quarkus.datasource.password = quarkus_test
quarkus.datasource.reactive.url = vertx-reactive:postgresql://localhost/quarkus_test (1)
# drop and create the database at startup (use `update` to only update the schema)
quarkus.hibernate-orm.database.generation=drop-and-create| 1 | Hibernate ORMの設定と唯一異なるプロパティ |
これらの設定プロパティは、典型的なHibernate Reactive設定ファイルにあるものと同じではないことに注意してください。これらはしばしばHibernate Reactive設定プロパティにマッピングされますが、名前が異なる可能性があり、必ずしも1対1でマッピングされるわけではありません。
Blocking (non-reactive) and reactive configuration can be mixed together in the same project.
標準の persistence.xml 設定ファイルを使用してHibernate Reactiveを設定することはサポートされていません。
|
application.properties で設定できるプロパティの一覧は Hibernate Reactive 設定プロパティ を参照してください。
プロジェクトの依存関係の中にHibernate Reactiveエクステンションがリストアップされていれば、Quarkus datasource の設定に基づいて Mutiny.SessionFactory が作成されます。
dialectは、Reactive SQLクライアントに基づいて選択されます（明示的に設定しない限り）。
その後、 Mutiny.SessionFactory を注入することができます。
@ApplicationScoped
public class SantaClausService {
@Inject
Mutiny.SessionFactory sf; (1)
public Uni<Void> createGift(String giftDescription) {
Gift gift = new Gift();
gift.setName(giftDescription);
return sf.withTransaction(session -> session.persist(gift)) (2)
}
}| 1 | セッションファクトリを注入して楽しもう |
| 2 | .withTransaction() はコミット時に自動的にフラッシュされます。 |
データベースを変更するメソッド（例： session.persist(entity) ）は、必ずトランザクション内にラップしてください。
|
@Entity
public class Gift {
private Long id;
private String name;
@Id
@SequenceGenerator(name = "giftSeq", sequenceName = "gift_id_seq", allocationSize = 1, initialValue = 1)
@GeneratedValue(generator = "giftSeq")
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}Hibernate Reactive の起動時に SQL 文をロードするには、 src/main/resources/ ディレクトリに import.sql ファイルを追加します。このスクリプトには、任意の SQL DML ステートメントを含めることができます。各ステートメントは必ずセミコロンで終了させてください。
テストやデモ用のデータセットを用意しておくと便利です。
Hibernate Reactiveの設定プロパティ
セッションファクトリを改良したり、Quarkusの推測を導くのに役立つ様々なオプションのプロパティがあります。
プロパティが設定されていない場合、Quarkusは通常、Hibernate Reactiveのセットアップに必要なすべてを推測し、デフォルトのデータソースを使用するようにします。
ここに記載されている設定プロパティーでは、このようなデフォルトを上書きしたり、様々な面をカスタマイズしたり調整したりすることができます。
Hibernate Reactive は、Hibernate ORM で使用するのと同じプロパティを使用します。一部のプロパティの名前に jdbc が含まれていますが、Hibernate Reactive には JDBC がないため、これらは単にレガシー プロパティ名です。
ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは実行時にオーバーライド可能
Configuration property |
型 |
デフォルト |
||
|---|---|---|---|---|
Whether Hibernate ORM is enabled during the build. If Hibernate ORM is disabled during the build, all processing related to Hibernate ORM will be skipped,
but it will not be possible to activate Hibernate ORM at runtime:
Environment variable: Show more |
boolean |
|
||
Whether Hibernate ORM is working in blocking mode. Hibernate ORM’s blocking Environment variable: Show more |
boolean |
|
||
If Environment variable: Show more |
boolean |
|
||
Whether statistics collection is enabled. If 'metrics.enabled' is true, then the default here is considered true, otherwise the default is false. Environment variable: Show more |
boolean |
|||
Whether session metrics should be appended into the server log for each Hibernate session. This only has effect if statistics are enabled ( Environment variable: Show more |
boolean |
|||
Whether metrics are published if a metrics extension is enabled. Environment variable: Show more |
boolean |
|
||
Allow hql queries in the Dev UI page Environment variable: Show more |
boolean |
|
||
Enable or disable access to a Hibernate ORM Environment variable: Show more |
boolean |
|
||
The name of the datasource which this persistence unit uses. If undefined, it will use the default datasource. Environment variable: Show more |
string |
|||
The packages in which the entities affected to this persistence unit are located. Environment variable: Show more |
list of string |
|||
Paths to files containing the SQL statements to execute when Hibernate ORM starts. The files are retrieved from the classpath resources,
so they must be located in the resources directory (e.g. The default value for this setting differs depending on the Quarkus launch mode:
If you need different SQL statements between dev mode, test ( application.properties
Environment variable: Show more |
list of string |
|
||
Pluggable strategy contract for applying physical naming rules for database object names. Class name of the Hibernate PhysicalNamingStrategy implementation Environment variable: Show more |
string |
|||
Pluggable strategy for applying implicit naming rules when an explicit name is not given. Class name of the Hibernate ImplicitNamingStrategy implementation Environment variable: Show more |
string |
|||
Class name of a custom
Environment variable: Show more |
string |
|||
XML files to configure the entity mapping, e.g. Defaults to Environment variable: Show more |
list of string |
|
||
Identifiers can be quoted using one of the available strategies. Set to Environment variable: Show more |
|
|
||
The default in Quarkus is for 2nd level caching to be enabled, and a good implementation is already integrated for you. Just cherry-pick which entities should be using the cache. Set this to false to disable all 2nd level caches. Environment variable: Show more |
boolean |
|
||
Defines how the Bean Validation integration behaves. Environment variable: Show more |
list of |
|
||
Defines the method for multi-tenancy (DATABASE, NONE, SCHEMA). The complete list of allowed values is available in the Hibernate ORM JavaDoc. The type DISCRIMINATOR is currently not supported. The default value is NONE (no multi-tenancy). Environment variable: Show more |
string |
|||
If hibernate is not auto generating the schema, and Quarkus is running in development mode then Quarkus will attempt to validate the database after startup and print a log message if there are any problems. Environment variable: Show more |
boolean |
|
||
Whether this persistence unit should be active at runtime. Note that if Hibernate ORM is disabled (i.e. Environment variable: Show more |
boolean |
|
||
Properties that should be passed on directly to Hibernate ORM.
Use the full configuration property key here,
for instance
Consider using a supported configuration property before falling back to unsupported ones. If none exists, make sure to file a feature request so that a supported configuration property can be added to Quarkus, and more importantly so that the configuration property is tested regularly. Environment variable: Show more |
Map<String,String> |
|||
型 |
デフォルト |
|||
When set, attempts to exchange data with the database as the given version of Hibernate ORM would have, on a best-effort basis. Please note:
Environment variable: Show more |
|
|
||
The charset of the database. Used for DDL generation and also for the SQL import scripts. Environment variable: Show more |
|
|||
Select whether the database schema is generated or not. Environment variable: Show more |
string |
|
||
If Hibernate ORM should create the schemas automatically (for databases supporting them). Environment variable: Show more |
boolean |
|
||
Whether we should stop on the first error when applying the schema. Environment variable: Show more |
boolean |
|
||
The default catalog to use for the database objects. Environment variable: Show more |
string |
|||
The default schema to use for the database objects. Environment variable: Show more |
string |
|||
Whether Hibernate ORM should check on startup
that the version of the database matches the version configured on the dialect
(either the default version, or the one set through This should be set to Environment variable: Show more |
boolean |
|
||
型 |
デフォルト |
|||
Name of the Hibernate ORM dialect. For supported databases, this property does not need to be set explicitly: it is selected automatically based on the datasource, and configured using the DB version set on the datasource to benefit from the best performance and latest features. If your database does not have a corresponding Quarkus extension, you will need to set this property explicitly. In that case, keep in mind that the JDBC driver and Hibernate ORM dialect may not work properly in GraalVM native executables. For built-in dialects, the expected value is one of the names
in the official list of dialects,
without the For third-party dialects, the expected value is the fully-qualified class name,
for example Environment variable: Show more |
string |
|
||
The storage engine to use when the dialect supports multiple storage engines. E.g. Environment variable: Show more |
string |
|||
型 |
デフォルト |
|||
How to store timezones in the database by default
for properties of type This default may be overridden on a per-property basis using
Environment variable: Show more |
|
|
||
The optimizer to apply to identifier generators whose optimizer is not configured explicitly. Only relevant for table- and sequence-based identifier generators. Other generators, such as UUID-based generators, will ignore this setting. The optimizer is responsible for pooling new identifier values, in order to reduce the frequency of database calls to retrieve those values and thereby improve performance. Environment variable: Show more |
|
|
||
型 |
デフォルト |
|||
The maximum size of the query plan cache. see # Environment variable: Show more |
int |
|
||
Default precedence of null values in Valid values are: Environment variable: Show more |
|
|
||
Enables IN clause parameter padding which improves statement caching. Environment variable: Show more |
boolean |
|
||
型 |
デフォルト |
|||
The time zone pushed to the JDBC driver. See Environment variable: Show more |
string |
|||
How many rows are fetched at a time by the JDBC driver. Environment variable: Show more |
int |
|||
The number of updates (inserts, updates and deletes) that are sent by the JDBC driver at one time for execution. Environment variable: Show more |
int |
|||
型 |
デフォルト |
|||
The size of the batches used when loading entities and collections.
Environment variable: Show more |
int |
|
||
The maximum depth of outer join fetch tree for single-ended associations (one-to-one, many-to-one). A Environment variable: Show more |
int |
|||
型 |
デフォルト |
|||
The maximum time before an object of the cache is considered expired. Environment variable: Show more |
||||
The maximum number of objects kept in memory in the cache. Environment variable: Show more |
長 |
|||
型 |
デフォルト |
|||
Existing applications rely (implicitly or explicitly) on Hibernate ignoring any DiscriminatorColumn declarations on joined inheritance hierarchies. This setting allows these applications to maintain the legacy behavior of DiscriminatorColumn annotations being ignored when paired with joined inheritance. Environment variable: Show more |
boolean |
|
||
型 |
デフォルト |
|||
Logs SQL bind parameters. Setting it to true is obviously not recommended in production. Environment variable: Show more |
boolean |
|
||
Show SQL logs and format them nicely. Setting it to true is obviously not recommended in production. Environment variable: Show more |
boolean |
|
||
Format the SQL logs if SQL log is enabled Environment variable: Show more |
boolean |
|
||
Highlight the SQL logs if SQL log is enabled Environment variable: Show more |
boolean |
|
||
Whether JDBC warnings should be collected and logged. Environment variable: Show more |
boolean |
|
||
If set, Hibernate will log queries that took more than specified number of milliseconds to execute. Environment variable: Show more |
長 |
|||
型 |
デフォルト |
|||
Select whether the database schema DDL files are generated or not. Accepted values: Environment variable: Show more |
string |
|
||
Filename or URL where the database create DDL file should be generated. Environment variable: Show more |
string |
|||
Filename or URL where the database drop DDL file should be generated. Environment variable: Show more |
string |
|||
型 |
デフォルト |
|||
The default flushing strategy, or when to flush entities to the database in a Hibernate session: before every query, on commit, … This default can be overridden on a per-session basis with See the javadoc of Environment variable: Show more |
|
|
|
期間フォーマットについて
期間の値を書くには、標準の 数字で始まる簡略化した書式を使うこともできます:
その他の場合は、簡略化されたフォーマットが解析のために
|
|
PostgreSQLサーバをDockerで起動したいですか？ これは、永続化されない空のデータベースを起動します。簡単な実験に最適です! |
Hibernate ORM and Reactive extensions simultaneously
If you add both Hibernate ORM and Hibernate Reactive extensions to your Quarkus app, they can be mixed together in the same project.
This is useful if your app normally uses Hibernate ORM (which is blocking), but you want to try Hibernate Reactive to see if it works better for your case.
By adding the second extension, you can use the reactive API in another part of your code - without needing to create a separate app.
| Hibernate ORM and Hibernate Reactive won’t share the same persistence context, so it’s recommended you stick to one or the other in a given method. For example use Hibernate ORM in blocking REST endpoints, and use Hibernate Reactive in reactive REST endpoints. |
-
To use the both extension simultaneously, add both extension to the
pom.xmlfile:<!-- Hibernate reactive --> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-hibernate-reactive</artifactId> </dependency> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-reactive-pg-client</artifactId> </dependency> <!-- Hibernate ORM --> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-jdbc-postgresql</artifactId> </dependency> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-hibernate-orm</artifactId> </dependency> -
Also update the
applications.propertiesfile:
%prod.quarkus.datasource.reactive.url=postgresql:///your_database %prod.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
-
The presence of the JDBC driver will enable Hibernate ORM. If you want to disable it, and only use Hibernate Reactive, you can use:
quarkus.hibernate-orm.blocking=false
Quarkus will set many Hibernate Reactive configuration settings automatically, and will often use more modern defaults.
CDI統合
QuarkusでHibernate Reactiveを使用することに慣れている方は、CDIを使用して Mutiny.SessionFactory を注入したことがあると思います。
@Inject
Mutiny.SessionFactory sessionFactory;これにより、デフォルトの永続化ユニットの Mutiny.SessionFactory が注入されます。
Quarkus 3.0以前は、 Mutiny.Session に @RequestScoped Beanを注入することも可能でした。しかし、リアクティブセッションのライフサイクルは、CDIリクエストコンテキストのライフサイクルに適合しません。そのため、Quarkus 3.0では、このBeanは削除されました。
|
スキーマを管理するためのFlywayへの自動移行
Hibernate Reactive は Flyway と同じアプリケーションで使用できます。 リアクティブアプリケーションでの Flyway の設定に関する詳細は、 Flyway エクステンションドキュメントのこのセクション を参照してください。
|
開発モードで実行しているときに Flywayエクステンション がインストールされている場合、Quarkusには、Hibernate Reactiveによって自動的に生成されたスキーマを使用してFlyway設定を初期化する簡単な方法があります。 詳細は Hibernate ORM ガイド を参照してください。 |
テスト
@QuarkusTest で Hibernate Reactive を使用する場合、API の非同期性とすべての操作を Vert.x イベントループで実行する必要から、Hibernate ORM を使用するより少し複雑です。
これらのテストを書くには、2つの要素が必要です。
-
テストメソッドでの
@io.quarkus.test.vertx.RunOnVertxContextまたは@io.quarkus.test.TestReactiveTransactionの使用 -
テストメソッドのパラメータとして
io.quarkus.test.vertx.UniAsserterの使用
これらのクラスは、 quarkus-test-vertx の依存関係によって提供されます。
|
非常にシンプルな使用例は、次のようになります:
@QuarkusTest
public class SomeTest {
@Inject
Mutiny.SessionFactory sessionFactory;
@Test
@RunOnVertxContext
public void testQuery(UniAsserter asserter) {
asserter.assertThat(() -> sessionFactory.withSession(s -> s.createQuery(
"from Gift g where g.name = :name").setParameter("name", "Lego").getResultList()),
list -> org.junit.jupiter.api.Assertions.assertEquals(list.size(), 1));
}
}
アサーション作成に使用できる様々なメソッドの詳細については、 UniAsserter の Javadoc を参照してください。
|
|
また、 |
制限事項など知っておくべきこと
Quarkusは使用しているライブラリを修正しません。このルールはHibernate Reactiveにも適用されます。このエクステンションを使用すると、ほとんどの場合、元のライブラリを使用するのと同じ経験ができます。
しかし、両者は同じコードを共有していますが、Quarkusはいくつかのコンポーネントを自動的に設定し、いくつかの拡張ポイントにカスタム実装を注入しています。
ここでは、QuarkusでHibernate Reactiveを使用する際に注意すべき点を紹介します。
-
Hibernate Reactiveは、
persistence.xmlファイルで設定できません。 -
このエクステンションは、現時点ではデフォルトの永続化ユニットのみを考慮します。 複数の永続化ユニットや、単一の名前付き永続化ユニットを設定することはできません。
-
This extension does not support database-based multitenancy or schema-based multitenancy at the moment. Discriminator-based multitenancy, on the other hand, is expected to work correctly. See https://github.com/quarkusio/quarkus/issues/15959.
-
Enversエクステンションとの統合はサポートされていません。
-
トランザクションの分割は、
jakarta.transaction.TransactionalまたはQuarkusTransactionを使用して行うことはできません。 Hibernate Reactive with Panache を使用する場合は、 代わりに @WithTransaction またはPanache.withTransaction() を使用する ことを検討してください。
PanacheでHibernate Reactiveをシンプルに
Hibernate Reactive with Panacheエクステンションは、Active Recordスタイルのエンティティ（およびリポジトリ）を提供することで、Hibernate Reactiveの使用を促進し、Quarkusでエンティティを簡単に楽しく書けるようにすることに重点を置いています。
Validation modes and Hibernate Validator integration
To find out more on how the quarkus.hibernate-orm.validation.mode configuration property.
influence your Hibernate Reactive application see the corresponding Hibernate ORM guide,
as these modes work the same in both cases.
