Hibernate ORMとJakarta Persistenceの使用

次の章で紹介する手順に沿って、ステップを踏んでアプリケーションを作成することを推奨します。 ただし、完成した例にそのまま進むこともできます。

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

解決策は hibernate-orm-quickstart ディレクトリー にあります。

QuarkusでHibernate ORMを使用する場合は、 設定の為に persistence.xml リソースは必要ありません。

このような古典的な設定ファイルを使用することは選択しとしてありますが、特定の高度なニーズがない限り不要です。 そのため、まずはHibernate ORMを persistence.xml リソース無しで設定できることをみていきましょう。

Quarkusでは、以下の点のみを実行します。

その他の設定の必要性は自動化されています。Quarkusは、いくつかの定見に基づいた選択と経験に基づいた推測を行います。

以下の依存関係をプロジェクトに追加してください:

例えば:

@Entity で永続オブジェクトにアノテーションを付けてから、 application.properties で関連する設定プロパティーを追加します。

これらの設定プロパティーは、通常のHibernate ORMの設定ファイルにあるものとは異なることに注意してください。 多くの場合はHibernate ORMの設定のプロパティーに対応していますが、名前が異なる場合もあり、必ずしも1対1で対応しているわけではありません。

また、Quarkusは多くのHibernate ORMの設定を自動的に設定し、多くの場合、より現代的なデフォルト値を使用します。

application.properties で設定できる項目のリストについては、Hibernate ORM configuration properties を参照してください。

Hibernate ORM エクステンションがプロジェクトの依存関係の中に入っていればQuarkus の datasource の設定に基づいて EntityManagerFactory が作成されます。

ダイアレクトはデータソースに基づいて自動的に選択および設定されます。 configure it to more precisely match your database (データベースにより正確に一致するように設定) することを推奨します。

その後、 EntityManager をうまく注入することができます。

Hibernate ORMの起動時にSQL文をロードするには、 import.sql ファイルをresourcesディレクトリーのルートに追加します。 このスクリプトには、任意のSQL DML文を含めることができます。 各ステートメントは必ずセミコロンで終了させてください。

テストやデモ用のデータセットを用意しておくと便利です。

Hibernate ORM をセットアップして設定するには、using application.properties が推奨されます。 ただし、代わりに META-INF/persistence.xml ファイルを使用することもできます。 これは主に、既存のコードを Quarkus に移行する場合に役立ちます。

pom.xml の依存関係と Java コードは先の例と同じになります。唯一の違いは META-INF/persistence.xml で Hibernate ORM の設定を行うことだけです:

persistence.xml で設定を使用する場合は、Hibernate ORM を直接設定することになるので、その場合は、hibernate.org のドキュメント を参照することが適切です。

これらは Quarkus の application.properties で使用されるプロパティー名と同じではなく、同じデフォルト値が適用されるわけではありませんのでご注意ください。

Quarkus の Hibernate ORM は、XML マッピングを サポートしています。 orm.xml 形式 (Jakarta Persistence) または hbm.xml 形式 (Hibernate ORM 固有、非推奨化) に従ってマッピングファイルを追加できます。

XML マッピングファイルは、ビルド時に解析されます。

QuarkusのHibernate ORMは、エンティティーに対するコンパイル時のバイトコード強化に依存しています。Quarkusアプリケーションを構築するのと同じプロジェクトでエンティティーを定義すれば、すべてがうまく動作します。

エンティティーが外部のプロジェクトやジャーから来ている場合は、空の META-INF/beans.xml ファイルを追加することで、jarがQuarkusアプリケーションライブラリのように扱われるようにすることができます。

これにより、Quarkusは、エンティティが現在のプロジェクトの内部にあるかのようにインデックスを作成し、バイトコード強化をすることができます。

Quarkusの開発モードはフロントエンドやサービス、データベースアクセスが混在するアプリケーションにとても便利です。

それを生かすためにはいくつかの共通したアプローチがあります。

1つ目の選択肢は、 quarkus.hibernate-orm.database.generation=drop-and-create と import.sql を併用することです。

そうすることで、アプリケーション、特にエンティティに変更があるたびに、データベーススキーマが適切に再作成され、データフィクスチャ（ import.sql に保存）がゼロから再投入されます。これは環境を完全にコントロールするための最良の方法であり、Quarkusのライブリロードモードでは魔法のように機能します。エンティティの変更や import.sql へのあらゆる変更が即座に反映され、アプリケーションを再起動しなくてもスキーマが更新されます！

2つ目の選択肢は quarkus.hibernate-orm.database.generation=update を使用することです。 この方法は、多くのエンティティを変更するが本番データのコピーで作業する必要がある場合や、特定のデータベースのデータエントリーに基づくバグを再現する場合に最適です。 update は Hibernate ORM によってベストエフォートで実行され、データ損失につながるデータベース構造の変更を含む特定の状況では失敗します。 例えば、外部キー制約に違反する構造を変更する場合、Hibernate ORM の挙動を助けてあげなければならないかもしれません。 しかし、開発中だとこれらの制限は許容範囲内です。

3つ目の選択肢は quarkus.hibernate-orm.database.generation=none を使用することです。この方法は、本番データのコピーで作業しており、スキーマの変更を完全にコントロールしたい場合に最適です。あるいは、 Flyway や Liquibaseのようなデータベーススキーマ移行ツールを使用している場合です。

この方法では、エンティティに変更を加える時にデータベーススキーマに確実に適合させる必要があります。また、 validate を使用して、Hibernateにスキーマが期待どおりかを確認させることもできます。

これらの方法は、Quarkusの設定プロファイルと組み合わせることで非常に強力になります。異なる 設定プロファイルを定義して、環境に応じて異なる動作を選択することができます。これは、現在必要としている開発スタイルに合わせて、Hibernate ORMのプロパティーの異なる組み合わせを定義できるという点で素晴らしいことです。

カスタムプロファイルを使用して開発モードを開始することができます:

Quarkusにはデフォルトのプロファイルが付属しています ( dev , test と prod )。また、様々な環境を記述するために独自のカスタムプロファイルを追加することができます ( staging , prod-us , など )。

Hibernate ORM Quarkusエクステンションでは、いくつかのデフォルト設定が、開発モードとテストモードで他の環境とは異なるように設定されています。

application.properties で明示的にオーバーライドできます。 (例: %prod.quarkus.hibernate-orm.sql-load-script = import.sql) ただし、 実稼働環境で誤ってデータベースをオーバーライドすることは避けたいと考えています :)

ところで、実稼働環境でデータベーススキーマを削除しないようにしてください。 プロパティーファイルに以下を追加してください。

開発モードでで実行している際に Flyway エクステンション をインストールしている場合、 Quarkus は Hibernate ORM によって自動的に生成されたスキーマを使用して Flyway の設定を簡単に初期化する方法を提供します。 これは、Hibernate を使ってスキーマを迅速にセットアップできる初期開発段階から、 Flyway を使ってスキーマの変更を管理する実稼働段階への移行を 容易にすることを目的としています。

この機能を使用するには、 quarkus-flyway エクステンションがインストールされている状態で Dev UI を開き、Flyway ペインの Datasources リンクをクリックします。 Create Initial Migration ボタンを押すと、以下が実行されます。

同じエンティティを頻繁に読み込むアプリケーションでは、Hibernate ORMのL2キャッシュを有効にするとパフォーマンスが向上します。

Hibernate ORMのEnversエクステンションは、エンティティクラスのための簡単な監査/バージョン管理ソリューションを提供することを目的としています。

Quarkusでは、Enversには専用のQuarkus エクステンションがあります。 io.quarkus:quarkus-hibernate-envers ; これをプロジェクトに追加して使用を開始する必要があります。

Quarkusの設定プロパティーを使用して、複数の永続化ユニットを定義することができます。

Hibernate Envers の詳細については、hibernate.org/orm/envers/ を参照してください。

Micrometer または SmallRye Metrics は、 Hibernate ORM が実行時に収集するメトリクスを公開できます。Hibernate のメトリクスを /q/metrics エンドポイントで公開するには、 プロジェクトがメトリクスエクステンションに依存しており、設定プロパティー quarkus.hibernate-orm.metrics.enabled を true に設定していることを確認します。 SmallRye Metrics を使用している場合、メトリクスは vendor スコープ内で利用可能になります。

Quarkusは使用するライブラリを変更しません。このルールはHibernate ORMにも適用されます。このエクステンションを使用すると、元のライブラリを使用した場合とほとんど同じエクスペリエンスが得られます。

ただし、同じコードを共有しているものの、Quarkus は一部のコンポーネントを自動的に設定し、いくつかのエクステンション ポイントに対してカスタム実装を注入します。これは透過的で便利なはずですが、Hibernate のエキスパートであれば、 何が行われているかを知りたいかもしれません。

Hibernate ORM with Panache エクステンションはアクティブレコードスタイルのエンティティ（およびリポジトリ）を提供してHibernate ORMを簡単に使えるようにし、Quarkusでエンティティを簡単に楽しく書けるようにすることに重点を置いています。

データソースの設定は非常にシンプルですが、技術的にはQuarkus用のAgroal接続プールエクステンションによって実装されているため、別のガイドで説明します。

詳細は Quarkus - データソースをご覧ください。

「マルチテナンシーという用語は、一般的にソフトウェア開発において、1 つの実行中のアプリケーションインスタンスが複数のクライアント (テナント) に同時にサービスを提供するアーキテクチャーを指します。これは SaaS ソリューションにおいて非常に一般的です。こうしたシステムでは、各テナントに関連する情報 (データ、カスタマイズなど) を分離することが特に課題となります。これには、データベースに保存される各テナントが所有するデータの分離も含まれます」 (Hibernate ユーザーガイド)

Quarkus は現在、別々のデータベース を使用する方法、別々のスキーマ を使用する方法、および discriminator を使用する方法をサポートしています。

マルチテナンシーの動作を確認するには、 hibernate-orm-multi-tenancy-schema-quickstart または hibernate-orm-multi-tenancy-database-quickstart をご覧ください。

適切な修飾子を持つ CDI Bean を定義するだけで、org.hibernate.Interceptor を SessionFactory に割り当てることができます。

適切な修飾子を持つCDI Beanを定義するだけで、 SessionFactory に org.hibernate.engine.jdbc.spi.StatementInspector を割り当てることができます:

デフォルトでは、Quarkus は利用可能なエクステンションに応じてフォーマットマッパーを自動的に設定しようとします。 Jackson (または JSON-B) が利用可能な場合、グローバルに設定された ObjectMapper (または Jsonb) がシリアル化/デシリアル化操作に使用されます。 Jackson と JSON-B の両方が同時に使用可能な場合は、Jackson が優先されます。

Hibernate ORM における JSON および XML のシリアル化/デシリアル化は、 org.hibernate.type.format.FormatMapper を実装し 適切な修飾子を使用して実装にアノテーションを付けることでカスタマイズできます。

カスタム XML 形式マッパーの場合は、別の CDI 修飾子を適用する必要があります。

Hibernate Validator integration into Hibernate ORM opens up the following capabilities:

From Quarkus’s perspective, this is controlled by the quarkus.hibernate-orm.validation.mode configuration property. The available validation modes are:

While all constraints with corresponding Jakarta Validation rules will apply during the callback validation, in the ddl mode, only a subset of constraints is used to influence the DDL. In the Hibernate Validator documentation, you can find the list of available constraints and their impact on the DDL generation.

Let’s consider having a simple entity with some constraints applied to its properties:

With the ddl mode enabled, the resulting schema would be expected to have the following constraints:

With the callback mode, expect getting a jakarta.validation.ConstraintViolationException thrown:

Since Quarkus has built-in exception mappers for jakarta.validation.ConstraintViolationException, explicitly handling these exceptions might be redundant. See the REST end point validation section of the Hibernate Validator guide for more details.

Both static metamodel and Jakarta Data capabilities of Hibernate ORM are available in Quarkus through the hibernate-jpamodelgen annotation processor. Since it is an annotation processor, you must configure the annotation processor in your build tool: