Hibernate ORMとJakarta Persistenceの使用

次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

Gitリポジトリをクローンする： git clone https://github.com/quarkusio/quarkus-quickstarts.git 、または archive をダウンロードする。

ソリューションは hibernate-orm-quickstart ディレクトリ にあります。

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

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

Quarkusでは、次のことを行うだけです:

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

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

例:

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

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

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

For a list of the items that you can set in application.properties, see Hibernate ORM configuration properties.

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

The dialect will be selected and configured automatically based on your datasource; you may want to configure it to more precisely match your database.

その後、 EntityManager をうまくインジェクションすることができます:

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

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

To set up and configure Hibernate ORM, using application.properties is recommended, but you can alternatively use a META-INF/persistence.xml file. This is mainly useful for migrating existing code to 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 )、prod で誤ってデータベースをオーバーライドしないようにしたいと思いました :)

そういえば、本番ではデータベーススキーマを落とさないようにしましょう!プロパティーファイルに以下を追加します。

If you have the Flyway extension installed when running in development mode, Quarkus provides a simple way to initialize your Flyway configuration using the schema generated automatically by Hibernate ORM. This is intended to ease the move from the early development phase, where Hibernate can be used to quickly set up the schema, to the production phase, where Flyway is used to manage schema changes.

この機能を使用するには、 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/を参照してください。

Either Micrometer or SmallRye Metrics are capable of exposing metrics that Hibernate ORM collects at runtime. To enable exposure of Hibernate metrics on the /q/metrics endpoint, make sure your project depends on a metrics extension and set the configuration property quarkus.hibernate-orm.metrics.enabled to true. When using SmallRye Metrics, metrics will be available under the vendor scope.

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

しかし、両者は同じコードを共有していますが、Quarkusはいくつかのコンポーネントを自動的に設定し、いくつかの拡張ポイントにカスタム実装をインジェクションしています。

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

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

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

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

Quarkusは現在、 分離データベース アプローチ、 分離スキーマ アプローチ、 discriminator アプローチをサポートしています。

マルチテナンシーの動作を確認するには、 hibernate-orm-multi-tenancy-quickstart クイックスタートをご覧ください。

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

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

By default, Quarkus will try to automatically configure format mappers depending on available extensions. Globally configured ObjectMapper (or Jsonb) will be used for serialization/deserialization operations when Jackson (or JSON-B) is available. Jackson will take precedence if both Jackson and JSON-B are available at the same time.

JSON and XML serialization/deserialization in Hibernate ORM can be customized by implementing a org.hibernate.type.format.FormatMapper and annotating the implementation with the appropriate qualifiers:

In case of a custom XML format mapper, a different CDI qualifier must be applied: