Using Hibernate ORM and Jakarta Persistence

我们建议您按照下一节的说明逐步创建应用程序。然而，您可以直接转到已完成的示例。

克隆 Git 仓库: git clone https://github.com/quarkusio/quarkus-quickstarts.git ，或下载一个 存档 。

The solution is located in the hibernate-orm-quickstart directory.

When using Hibernate ORM in Quarkus, you don’t need to have a persistence.xml resource to configure it.

Using such a classic configuration file is an option, but unnecessary unless you have specific advanced needs; so we’ll see first how Hibernate ORM can be configured without a persistence.xml resource.

In Quarkus, you only need to:

Other configuration needs have been automated: Quarkus will make some opinionated choices and educated guesses.

Add the following dependencies to your project:

比如：

Annotate your persistent objects with @Entity, then add the relevant configuration properties in application.properties.

Note that these configuration properties are not the same ones as in your typical Hibernate ORM configuration file. They will often map to Hibernate ORM configuration properties but could have different names and don’t necessarily map 1:1 to each other.

Also, Quarkus will set many Hibernate ORM configuration settings automatically, and will often use more modern defaults.

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

An EntityManagerFactory will be created based on the Quarkus datasource configuration as long as the Hibernate ORM extension is listed among your project dependencies.

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

You can then happily inject your EntityManager:

To load SQL statements when Hibernate ORM starts, add an import.sql file to the root of your resources directory. This script can contain any SQL DML statements. Make sure to terminate each statement with a semicolon.

This is useful to have a data set ready for your tests or demos.

Alternatively, you can use a META-INF/persistence.xml to set up Hibernate ORM. This is useful for:

Your pom.xml dependencies as well as your Java code would be identical to the precedent example. The only difference is that you would specify your Hibernate ORM configuration in META-INF/persistence.xml:

When using the persistence.xml configuration you are configuring Hibernate ORM directly, so in this case the appropriate reference is the documentation on hibernate.org.

Please remember these are not the same property names as the ones used in the Quarkus application.properties, nor will the same defaults be applied.

Hibernate ORM in Quarkus supports XML mapping. You can add mapping files following the orm.xml format (Jakarta Persistence) or the hbm.xml format (specific to Hibernate ORM, deprecated):

XML mapping files are parsed at build time.

Hibernate ORM in Quarkus relies on compile-time bytecode enhancements to your entities. If you define your entities in the same project where you build your Quarkus application, everything will work fine.

If the entities come from external projects or jars, you can make sure that your jar is treated like a Quarkus application library by adding an empty META-INF/beans.xml file.

This will allow Quarkus to index and enhance your entities as if they were inside the current project.

Quarkus development mode is really useful for applications that mix front end or services and database access.

There are a few common approaches to make the best of it.

The first choice is to use quarkus.hibernate-orm.database.generation=drop-and-create in conjunction with import.sql.

That way for every change to your app and in particular to your entities, the database schema will be properly recreated and your data fixture (stored in import.sql) will be used to repopulate it from scratch. This is best to perfectly control your environment and works magic with Quarkus live reload mode: your entity changes or any change to your import.sql is immediately picked up and the schema updated without restarting the application!

The second approach is to use quarkus.hibernate-orm.database.generation=update. This approach is best when you do many entity changes but still need to work on a copy of the production data or if you want to reproduce a bug that is based on specific database entries. update is a best effort from Hibernate ORM and will fail in specific situations including altering your database structure which could lead to data loss. For example if you change structures which violate a foreign key constraint, Hibernate ORM might have to bail out. But for development, these limitations are acceptable.

The third approach is to use quarkus.hibernate-orm.database.generation=none. This approach is best when you are working on a copy of the production data but want to fully control the schema evolution. Or if you use a database schema migration tool like Flyway or Liquibase.

With this approach when making changes to an entity, make sure to adapt the database schema accordingly; you could also use validate to have Hibernate verify the schema matches its expectations.

These approaches become really powerful when combined with Quarkus configuration profiles. You can define different configuration profiles to select different behaviors depending on your environment. This is great because you can define different combinations of Hibernate ORM properties matching the development style you currently need.

You can start dev mode using a custom profile:

Quarkus comes with default profiles (dev, test and prod). And you can add your own custom profiles to describe various environments (staging, prod-us, etc).

The Hibernate ORM Quarkus extension sets some default configurations differently in dev and test modes than in other environments.

You can override it in your application.properties explicitly (e.g. %prod.quarkus.hibernate-orm.sql-load-script = import.sql) but we wanted you to avoid overriding your database by accident in prod :)

Speaking of, make sure to not drop your database schema in production! Add the following in your properties file.

If you have the Flyway extension installed when running in development mode, Quarkus provides a simple way to turn your Hibernate ORM auto generated schema into a Flyway migration file. This is intended to make is easy to 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.

To use this feature simply open the Dev UI when the quarkus-flyway extension is installed and click in the Datasources link in the Flyway pane. Hit the Create Initial Migration button and the following will happen:

Applications that frequently read the same entities can see their performance improved when the Hibernate ORM second-level cache is enabled.

The Envers extension to Hibernate ORM aims to provide an easy auditing / versioning solution for entity classes.

In Quarkus, Envers has a dedicated Quarkus Extension io.quarkus:quarkus-hibernate-envers; you just need to add this to your project to start using it.

At this point the extension does not expose additional configuration properties.

For more information about Hibernate Envers, see 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 does not modify the libraries it uses; this rule applies to Hibernate ORM as well: when using this extension you will mostly have the same experience as using the original library.

But while they share the same code, Quarkus does configure some components automatically and injects custom implementations for some extension points; this should be transparent and useful but if you’re an expert of Hibernate you might want to know what is being done.

The Hibernate ORM with Panache extension facilitates the usage of Hibernate ORM by providing active record style entities (and repositories) and focuses on making your entities trivial and fun to write in Quarkus.

Datasource configuration is extremely simple, but is covered in a different guide as technically it’s implemented by the Agroal connection pool extension for Quarkus.

Jump over to Quarkus - Datasources for all details.

"The term multitenancy, in general, is applied to software development to indicate an architecture in which a single running instance of an application simultaneously serves multiple clients (tenants). This is highly common in SaaS solutions. Isolating information (data, customizations, etc.) pertaining to the various tenants is a particular challenge in these systems. This includes the data owned by each tenant stored in the database" (Hibernate User Guide).

Quarkus currently supports the separate database approach, the separate schema approach and the discriminator approach.

To see multitenancy in action, you can check out the hibernate-orm-multi-tenancy-quickstart quickstart.

You can assign an org.hibernate.Interceptor to your SessionFactory by simply defining a CDI bean with the appropriate qualifier:

You can assign a org.hibernate.engine.jdbc.spi.StatementInspector to your SessionFactory by simply defining a CDI bean with the appropriate qualifier:

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: