By Version

Usando Hibernate ORM e Jakarta Persistence

O Hibernate ORM é a implementação padrão de fato da Jakarta Persistence (anteriormente conhecida como JPA) e oferece toda a abrangência de um Mapeador Objeto-Relacional. Ele funciona perfeitamente no Quarkus.

Solução

Recomendamos que siga as instruções nas seções seguintes e crie a aplicação passo a passo. No entanto, você pode ir diretamente para o exemplo completo.

Clone o repositório Git: git clone -b 3.20 https://github.com/quarkusio/quarkus-quickstarts.git, ou baixe um arquivo.

A solução está localizada no hibernate-orm-quickstart diretório.

Configurando e definido o Hibernate ORM

Ao usar o Hibernate ORM no Quarkus, você não precisa ter um recurso persistence.xml para configurá-lo.

Usar esse arquivo de configuração clássico é uma opção, mas desnecessária a menos que você tenha necessidades avançadas específicas. Então veremos primeiro como o Hibernate ORM pode ser configurado sem um recurso persistence.xml.

No Quarkus, você só precisa:

adicionar suas configurações no application.properties
anotar suas entidades com @Entity e qualquer outras anotações de mapeamento como de costume

Outras necessidades de configuração foram automatizadas: O Quarkus fará algumas escolhas opinativas e suposições bem fundamentadas.

Adicione as seguintes dependências ao seu projeto:

a extensão Hibernate ORM: io.quarkus:quarkus-hibernate-orm
A extensão do seu driver JDBC, as seguintes opções estão disponíveis:
- quarkus-jdbc-db2 para IBM DB2
- quarkus-jdbc-derby for Apache Derby
- quarkus-jdbc-h2 para H2
- quarkus-jdbc-mariadb para MariaDB
- quarkus-jdbc-mssql para Microsoft SQL Server
- quarkus-jdbc-mysql para MySQL
- quarkus-jdbc-oracle para o Oracle Database
- quarkus-jdbc-postgresql para PostgreSQL

Por exemplo:

pom.xml

<!-- Hibernate ORM specific dependencies -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-orm</artifactId>
</dependency>

<!-- JDBC driver dependencies -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>

build.gradle

// Hibernate ORM specific dependencies
implementation("io.quarkus:quarkus-hibernate-orm")

// JDBC driver dependencies
implementation("io.quarkus:quarkus-jdbc-postgresql")

Anote seus objetos persistentes com @Entity, em seguida, adicione as propriedades de configuração relevantes em application.properties .

Exemplo application.properties

quarkus.datasource.db-kind = postgresql (1)
quarkus.datasource.username = hibernate
quarkus.datasource.password = hibernate
quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:5432/hibernate_db

quarkus.hibernate-orm.database.generation=drop-and-create (2)

1	Configure a fonte de dados.
2	Remove e crie o banco de dados na inicialização (use `update` para atualizar apenas o schema).

Observe que essas propriedades de configuração não são as mesmas do arquivo de configuração típico do Hibernate ORM. Elas geralmente correspondem às propriedades de configuração do Hibernate ORM, mas podem ter nomes diferentes e não necessariamente possuem uma correspondência de 1:1 entre si.

Além disso, o Quarkus definirá automaticamente muitas definições de configuração do Hibernate ORM e, com frequência, usará padrões mais modernos.

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

Uma EntityManagerFactory será criada com base na configuração do Quarkus datasource , desde que a extensão Hibernate ORM esteja listada entre as dependências do seu projeto.

O dialeto será selecionado e configurado automaticamente com base na sua fonte de dados. você pode querer configurá-lo para corresponder mais precisamente ao seu banco de dados.

Você pode então injetar seu EntityManager sem problemas:

Exemplo de bean da aplicação usando o Hibernate

@ApplicationScoped
public class SantaClausService {
    @Inject
    EntityManager em; (1)

    @Transactional (2)
    public void createGift(String giftDescription) {
        Gift gift = new Gift();
        gift.setName(giftDescription);
        em.persist(gift);
    }
}

1	Injete seu gerenciador de entidades e divirta-se
2	Marque o método do seu bean CDI como `@Transactional` e o `EntityManager` será inscrito e fará o flush no commit.

Exemplo de entidade

@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;
    }
}

Para carregar instruções SQL quando o Hibernate ORM for iniciar, adicione um arquivo import.sql na raiz do seu diretório resources. Esse script pode conter quaisquer instruções SQL DML. Certifique-se de terminar cada instrução com um ponto e vírgula.

Isso é útil para ter um conjunto de dados pronto para seus testes ou demonstrações.

Certifique-se de envolver os métodos que modificam o banco de dados (por exemplo, entity.persist() ) em uma transação. Marcar um método do bean CDI como @Transactional fará isso por você e tornará esse método um limite de transação. Recomendamos fazer isso nos limites do ponto de entrada da sua aplicação, como seus controladores de endpoint REST.

Dialeto

Bancos de dados suportados

Para bancos de dados compatíveis, o dialeto do Hibernate ORM não precisa ser definido explicitamente: ele é selecionado automaticamente com base na fonte de dados.

Por padrão, o dialeto é configurado para a versão mínima suportada do banco de dados.

Para que o Hibernate ORM gere SQL mais eficiente, evite soluções alternativas e aproveite mais recursos do banco de dados, você pode definir a versão do banco de dados explicitamente:

application.properties com uma db-version explícita

quarkus.datasource.db-kind = postgresql
quarkus.datasource.db-version = 14.0 (1)
quarkus.datasource.username = hibernate
quarkus.datasource.password = hibernate
quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:5432/hibernate_db

1	Defina a versão do banco de dados. O dialeto do Hibernate ORM terá como alvo essa versão.

Como regra geral, a versão definida aqui deve ser a mais alta possível, mas deve ser menor ou igual à versão de qualquer banco de dados ao qual sua aplicação Irã se conectar.

Conforme descrito acima, a versão pode ser pré-configurada explicitamente por meio da propriedade de configuração quarkus.datasource.db-version ou definida implicitamente pelo processo de compilação do Quarkus para uma versão mínima suportada do banco de dados. O Quarkus tentará verificar essa versão pré-configurada em relação à versão real do banco de dados na inicialização, resultando em falha na inicialização quando a versão real for inferior.

Essa é uma proteção: para versões do banco de dados mais antigas do que as configuradas, o Hibernate ORM pode gerar SQL inválido, o que levaria a exceções de tempo de execução.

Se o banco de dados não puder ser acessado, será registrado um aviso, mas a inicialização continuará. Opcionalmente, você pode desativar a verificação de versão se souber que o banco de dados não poderá ser acessado na inicialização usando quarkus.hibernate-orm.database.version-check.enabled=false.

The version check is disabled by default when a dialect is set explicitly, as a workaround for #42255/#43703.

Outros bancos de dados

Se o seu banco de dados não tiver uma extensão Quarkus correspondente ou se os padrões não corresponderem às suas necessidades por algum motivo, será necessário definir explicitamente o dialeto Hibernate ORM :

application.properties com um dialect explícito

quarkus.datasource.db-kind = postgresql
quarkus.datasource.username = hibernate
quarkus.datasource.password = hibernate
quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:26257/hibernate_db

quarkus.hibernate-orm.dialect=Cockroach (1)

Defina o dialeto do Hibernate ORM.

Para dialetos integrados, o valor esperado é um dos nomes No lista oficial de dialetos, sem o sufixo Dialect, por exemplo, Cockroach para CockroachDialect.

Para dialetos de terceiros, o valor esperado é o nome completo da classe, por exemplo com.acme.hibernate.AcmeDbDialect .

Nesse caso, lembre-se de que o driver JDBC ou o dialeto Hibernate ORM pode não funcionar corretamente nos executáveis nativos do GraalVM.

Assim como nos banco de dados compatíveis, você pode configurar a versão do banco de dados explicitamente para aproveitar ao máximo o Hibernate ORM:

application.properties com um dialect explícito e o db-version

quarkus.datasource.db-kind = postgresql
quarkus.datasource.db-version = 22.2 (1)
quarkus.datasource.username = hibernate
quarkus.datasource.password = hibernate
quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:26257/hibernate_db

quarkus.hibernate-orm.dialect=Cockroach (2)

1	Defina a versão do banco de dados. O dialeto do Hibernate ORM terá como alvo essa versão. Como estamos direcionando o CockroachDB aqui, estamos passando a versão do CockroachDB, não a versão do PostgreSQL.
2	Defina o dialeto do Hibernate ORM.

Banco de dados variável

Ao ativar o banco de dados multi-tenancy, o Hibernate ORM usará várias fontes de dados em tempo de execução para a mesma unidade de persistência e, por padrão, o Quarkus não pode dizer qual fonte de dados será usada, portanto, não poderá detectar um dialeto a ser usado no Hibernate ORM.

Por esse motivo, ao ativar o banco de dados multi-tenancy, é recomendável apontar explicitamente a configuração do Hibernate ORM para um recurso de dados entre os que serão usados em tempo de execução, por exemplo, com quarkus.hibernate-orm.datasource=base ( base é o nome de um recurso de dados).

Ao fazer isso, o Quarkus inferirá a versão do banco de dados e (se possível) o dialeto a partir dessa fonte de dados. Para bancos de dados não suportados, ainda pode ser necessário definir explicitamente o dialeto do Hibernate ORM, conforme explicado em esta seção.

Propriedades de configuração do Hibernate ORM

Há várias propriedades opcionais úteis para refinar seu EntityManagerFactory ou orientar suposições de Quarkus.

Não há propriedades obrigatórias, desde que uma fonte de dados padrão esteja configurada.

Quando nenhuma propriedade é definida, o Quarkus normalmente pode inferir tudo o que é necessário para configurar o Hibernate ORM e fará com que ele use a fonte de dados padrão.

The configuration properties listed here allow you to override such defaults, and customize and tune various aspects.

Propriedade de Configuração Fixa no Momento da Compilação - Todas as outras propriedades de configuração podem ser sobrepostas em tempo de execução.

Configuration property

Tipo

Padrão

quarkus.hibernate-orm.enabled

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: quarkus.hibernate-orm.active will default to false and setting it to true will lead to an error.

Environment variable: QUARKUS_HIBERNATE_ORM_ENABLED

booleano

true

quarkus.hibernate-orm.persistence-xml.ignore

If true, Quarkus will ignore any persistence.xml file in the classpath and rely exclusively on the Quarkus configuration.

Environment variable: QUARKUS_HIBERNATE_ORM_PERSISTENCE_XML_IGNORE

booleano

false

quarkus.hibernate-orm.statistics

Whether statistics collection is enabled. If 'metrics.enabled' is true, then the default here is considered true, otherwise the default is false.

Environment variable: QUARKUS_HIBERNATE_ORM_STATISTICS

booleano

quarkus.hibernate-orm.log-session-metrics

Whether session metrics should be appended into the server log for each Hibernate session. This only has effect if statistics are enabled (quarkus.hibernate-orm.statistics). The default is false (which means both statistics and log-session-metrics need to be enabled for the session metrics to appear in the log).

Environment variable: QUARKUS_HIBERNATE_ORM_LOG_SESSION_METRICS

booleano

quarkus.hibernate-orm.metrics.enabled

Whether metrics are published if a metrics extension is enabled.

Environment variable: QUARKUS_HIBERNATE_ORM_METRICS_ENABLED

booleano

false

quarkus.hibernate-orm.request-scoped.enabled

Enable or disable access to a Hibernate ORM EntityManager/Session/StatelessSession *when no transaction is active* but a request scope is. When enabled, the corresponding sessions will be read-only. Defaults to enabled for backwards compatibility, but disabling this is recommended, to avoid inconsistent resulsts caused by queries running outside of transactions.

Environment variable: QUARKUS_HIBERNATE_ORM_REQUEST_SCOPED_ENABLED

booleano

true

quarkus.hibernate-orm.datasource

quarkus.hibernate-orm."persistence-unit-name".datasource

The name of the datasource which this persistence unit uses.

If undefined, it will use the default datasource.

Environment variable: QUARKUS_HIBERNATE_ORM_DATASOURCE

string

quarkus.hibernate-orm.packages

quarkus.hibernate-orm."persistence-unit-name".packages

The packages in which the entities affected to this persistence unit are located.

Environment variable: QUARKUS_HIBERNATE_ORM_PACKAGES

list of string

quarkus.hibernate-orm.sql-load-script

quarkus.hibernate-orm."persistence-unit-name".sql-load-script

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. src/main/resources).

The default value for this setting differs depending on the Quarkus launch mode:

In dev and test modes, it defaults to import.sql. Simply add an import.sql file in the root of your resources directory and it will be picked up without having to set this property. Pass no-file to force Hibernate ORM to ignore the SQL import file.
In production mode, it defaults to no-file. It means Hibernate ORM won’t try to execute any SQL import file by default. Pass an explicit value to force Hibernate ORM to execute the SQL import file.

If you need different SQL statements between dev mode, test (@QuarkusTest) and in production, use Quarkus configuration profiles facility.

application.properties

%dev.quarkus.hibernate-orm.sql-load-script = import-dev.sql
%test.quarkus.hibernate-orm.sql-load-script = import-test.sql
%prod.quarkus.hibernate-orm.sql-load-script = no-file

Quarkus supports .sql file with SQL statements or comments spread over multiple lines. Each SQL statement must be terminated by a semicolon.

Environment variable: QUARKUS_HIBERNATE_ORM_SQL_LOAD_SCRIPT

list of string

import.sql in dev and test modes ; no-file otherwise

quarkus.hibernate-orm.physical-naming-strategy

quarkus.hibernate-orm."persistence-unit-name".physical-naming-strategy

Pluggable strategy contract for applying physical naming rules for database object names. Class name of the Hibernate PhysicalNamingStrategy implementation

Environment variable: QUARKUS_HIBERNATE_ORM_PHYSICAL_NAMING_STRATEGY

string

quarkus.hibernate-orm.implicit-naming-strategy

quarkus.hibernate-orm."persistence-unit-name".implicit-naming-strategy

Pluggable strategy for applying implicit naming rules when an explicit name is not given. Class name of the Hibernate ImplicitNamingStrategy implementation

Environment variable: QUARKUS_HIBERNATE_ORM_IMPLICIT_NAMING_STRATEGY

string

quarkus.hibernate-orm.metadata-builder-contributor

quarkus.hibernate-orm."persistence-unit-name".metadata-builder-contributor

Class name of a custom org.hibernate.boot.spi.MetadataBuilderContributor implementation.

Not all customization options exposed by org.hibernate.boot.MetadataBuilder will work correctly. Stay clear of options related to classpath scanning in particular.

This setting is exposed mainly to allow registration of types, converters and SQL functions.

Environment variable: QUARKUS_HIBERNATE_ORM_METADATA_BUILDER_CONTRIBUTOR

string

quarkus.hibernate-orm.mapping-files

quarkus.hibernate-orm."persistence-unit-name".mapping-files

XML files to configure the entity mapping, e.g. META-INF/my-orm.xml.

Defaults to META-INF/orm.xml if it exists. Pass no-file to force Hibernate ORM to ignore META-INF/orm.xml.

Environment variable: QUARKUS_HIBERNATE_ORM_MAPPING_FILES

list of string

META-INF/orm.xml if it exists; no-file otherwise

quarkus.hibernate-orm.quote-identifiers.strategy

quarkus.hibernate-orm."persistence-unit-name".quote-identifiers.strategy

Identifiers can be quoted using one of the available strategies.

Set to none by default, meaning no identifiers will be quoted. If set to all, all identifiers and column definitions will be quoted. Additionally, setting it to all-except-column-definitions will skip the column definitions, which can usually be required when they exist, or else use the option only-keywords to quote only identifiers deemed SQL keywords by the Hibernate ORM dialect.

Environment variable: QUARKUS_HIBERNATE_ORM_QUOTE_IDENTIFIERS_STRATEGY

none, all, all-except-column-definitions, only-keywords

none

quarkus.hibernate-orm.second-level-caching-enabled

quarkus.hibernate-orm."persistence-unit-name".second-level-caching-enabled

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: QUARKUS_HIBERNATE_ORM_SECOND_LEVEL_CACHING_ENABLED

booleano

true

quarkus.hibernate-orm.validation.mode

quarkus.hibernate-orm."persistence-unit-name".validation.mode

Defines how the Bean Validation integration behaves.

Environment variable: QUARKUS_HIBERNATE_ORM_VALIDATION_MODE

list of auto, callback, ddl, none

auto

quarkus.hibernate-orm.multitenant

quarkus.hibernate-orm."persistence-unit-name".multitenant

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: QUARKUS_HIBERNATE_ORM_MULTITENANT

string

quarkus.hibernate-orm.validate-in-dev-mode

quarkus.hibernate-orm."persistence-unit-name".validate-in-dev-mode

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: QUARKUS_HIBERNATE_ORM_VALIDATE_IN_DEV_MODE

booleano

true

quarkus.hibernate-orm.active

quarkus.hibernate-orm."persistence-unit-name".active

Whether this persistence unit should be active at runtime.

See this section of the documentation.

Note that if Hibernate ORM is disabled (i.e. quarkus.hibernate-orm.enabled is set to false), all persistence units are deactivated, and setting this property to true will fail.

Environment variable: QUARKUS_HIBERNATE_ORM_ACTIVE

booleano

'true' if Hibernate ORM is enabled; 'false' otherwise

quarkus.hibernate-orm.unsupported-properties."full-property-key"

quarkus.hibernate-orm."persistence-unit-name".unsupported-properties."full-property-key"

Properties that should be passed on directly to Hibernate ORM. Use the full configuration property key here, for instance quarkus.hibernate-orm.unsupported-properties."hibernate.order_inserts" = true.

Properties set here are completely unsupported: as Quarkus doesn’t generally know about these properties and their purpose, there is absolutely no guarantee that they will work correctly, and even if they do, that may change when upgrading to a newer version of Quarkus (even just a micro/patch version).

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: QUARKUS_HIBERNATE_ORM_UNSUPPORTED_PROPERTIES__FULL_PROPERTY_KEY_

Map<String,String>

Database related configuration

Tipo

Padrão

quarkus.hibernate-orm.database.orm-compatibility.version

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:

schema validation may still fail in some cases: this attempts to make Hibernate ORM 6+ behave correctly at runtime, but it may still expect a different (but runtime-compatible) schema.
robust test suites are still useful and recommended: you should still check that your application behaves as intended with your legacy schema.
this feature is inherently unstable: some aspects of it may stop working in future versions of Quarkus, and older versions will be dropped as Hibernate ORM changes pile up and support for those older versions becomes too unreliable.
you should still plan a migration of your schema to a newer version of Hibernate ORM. For help with migration, refer to the Quarkus 3 migration guide from Hibernate ORM 5 to 6.

Environment variable: QUARKUS_HIBERNATE_ORM_DATABASE_ORM_COMPATIBILITY_VERSION

5.6, latest

latest

quarkus.hibernate-orm.database.charset

quarkus.hibernate-orm."persistence-unit-name".database.charset

The charset of the database.

Used for DDL generation and also for the SQL import scripts.

Environment variable: QUARKUS_HIBERNATE_ORM_DATABASE_CHARSET

Charset

UTF-8

quarkus.hibernate-orm.database.generation

quarkus.hibernate-orm."persistence-unit-name".database.generation

Select whether the database schema is generated or not. drop-and-create is awesome in development mode. This defaults to 'none', however if Dev Services is in use and no other extensions that manage the schema are present this will default to 'drop-and-create'. Accepted values: none, create, drop-and-create, drop, update, validate.

Environment variable: QUARKUS_HIBERNATE_ORM_DATABASE_GENERATION

string

none

quarkus.hibernate-orm.database.generation.create-schemas

quarkus.hibernate-orm."persistence-unit-name".database.generation.create-schemas

If Hibernate ORM should create the schemas automatically (for databases supporting them).

Environment variable: QUARKUS_HIBERNATE_ORM_DATABASE_GENERATION_CREATE_SCHEMAS

booleano

false

quarkus.hibernate-orm.database.generation.halt-on-error

quarkus.hibernate-orm."persistence-unit-name".database.generation.halt-on-error

Whether we should stop on the first error when applying the schema.

Environment variable: QUARKUS_HIBERNATE_ORM_DATABASE_GENERATION_HALT_ON_ERROR

booleano

false

quarkus.hibernate-orm.database.default-catalog

quarkus.hibernate-orm."persistence-unit-name".database.default-catalog

The default catalog to use for the database objects.

Environment variable: QUARKUS_HIBERNATE_ORM_DATABASE_DEFAULT_CATALOG

string

quarkus.hibernate-orm.database.default-schema

quarkus.hibernate-orm."persistence-unit-name".database.default-schema

The default schema to use for the database objects.

Environment variable: QUARKUS_HIBERNATE_ORM_DATABASE_DEFAULT_SCHEMA

string

quarkus.hibernate-orm.database.version-check.enabled

quarkus.hibernate-orm."persistence-unit-name".database.version-check.enabled

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 quarkus.datasource.db-version).

This should be set to false if the database is not available on startup.

Environment variable: QUARKUS_HIBERNATE_ORM_DATABASE_VERSION_CHECK_ENABLED

booleano

`true if the dialect was set automatically by Quarkus, false if it was set explicitly`

Dialect related configuration

Tipo

Padrão

quarkus.hibernate-orm.dialect

quarkus.hibernate-orm."persistence-unit-name".dialect

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 Dialect suffix, for example Cockroach for CockroachDialect.

For third-party dialects, the expected value is the fully-qualified class name, for example com.acme.hibernate.AcmeDbDialect.

Environment variable: QUARKUS_HIBERNATE_ORM_DIALECT

string

selected automatically for most popular databases

quarkus.hibernate-orm.dialect.storage-engine

quarkus.hibernate-orm."persistence-unit-name".dialect.storage-engine

The storage engine to use when the dialect supports multiple storage engines.

E.g. MyISAM or InnoDB for MySQL.

Environment variable: QUARKUS_HIBERNATE_ORM_DIALECT_STORAGE_ENGINE

string

Mapping configuration

Tipo

Padrão

quarkus.hibernate-orm.mapping.timezone.default-storage

quarkus.hibernate-orm."persistence-unit-name".mapping.timezone.default-storage

How to store timezones in the database by default for properties of type OffsetDateTime and ZonedDateTime.

This default may be overridden on a per-property basis using @TimeZoneStorage.

Properties of type OffsetTime are not affected by this setting.

default: Equivalent to native if supported, normalize-utc otherwise.
auto: Equivalent to native if supported, column otherwise.
native: Stores the timestamp and timezone in a column of type timestamp with time zone.

Only available on some databases/dialects; if not supported, an exception will be thrown during static initialization.
column: Stores the timezone in a separate column next to the timestamp column.

Use @TimeZoneColumn on the relevant entity property to customize the timezone column.
normalize-utc: Does not store the timezone, and loses timezone information upon persisting.

Instead, normalizes the value to a timestamp in the UTC timezone.
normalize: Does not store the timezone, and loses timezone information upon persisting.

Instead, normalizes the value: * upon persisting to the database, to a timestamp in the JDBC timezone set through quarkus.hibernate-orm.jdbc.timezone, or the JVM default timezone if not set. * upon reading back from the database, to the JVM default timezone.

+ Use this to get the legacy behavior of Quarkus 2 / Hibernate ORM 5 or older.

Environment variable: QUARKUS_HIBERNATE_ORM_MAPPING_TIMEZONE_DEFAULT_STORAGE

native, normalize, normalize-utc, column, auto, default

default

quarkus.hibernate-orm.mapping.id.optimizer.default

quarkus.hibernate-orm."persistence-unit-name".mapping.id.optimizer.default

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: QUARKUS_HIBERNATE_ORM_MAPPING_ID_OPTIMIZER_DEFAULT

pooled-loAssumes the value retrieved from the table/sequence is the lower end of the pool. Upon retrieving value N, the new pool of identifiers will go from N to N + <allocation size> - 1, inclusive., pooledAssumes the value retrieved from the table/sequence is the higher end of the pool. Upon retrieving value N, the new pool of identifiers will go from N - <allocation size> to N + <allocation size> - 1, inclusive. The first value, 1, is handled differently to avoid negative identifiers. Use this to get the legacy behavior of Quarkus 2 / Hibernate ORM 5 or older., noneNo optimizer, resulting in a database call each and every time an identifier value is needed from the generator. Not recommended in production environments\: may result in degraded performance and/or frequent gaps in identifier values.

Query related configuration

Tipo

Padrão

quarkus.hibernate-orm.query.query-plan-cache-max-size

quarkus.hibernate-orm."persistence-unit-name".query.query-plan-cache-max-size

The maximum size of the query plan cache. see #org.hibernate.cfg.AvailableSettings#QUERY_PLAN_CACHE_MAX_SIZE

Environment variable: QUARKUS_HIBERNATE_ORM_QUERY_QUERY_PLAN_CACHE_MAX_SIZE

int

2048

quarkus.hibernate-orm.query.default-null-ordering

quarkus.hibernate-orm."persistence-unit-name".query.default-null-ordering

Default precedence of null values in ORDER BY clauses.

Valid values are: none, first, last.

Environment variable: QUARKUS_HIBERNATE_ORM_QUERY_DEFAULT_NULL_ORDERING

none, first, last

none

quarkus.hibernate-orm.query.in-clause-parameter-padding

quarkus.hibernate-orm."persistence-unit-name".query.in-clause-parameter-padding

Enables IN clause parameter padding which improves statement caching.

Environment variable: QUARKUS_HIBERNATE_ORM_QUERY_IN_CLAUSE_PARAMETER_PADDING

booleano

true

JDBC related configuration

Tipo

Padrão

quarkus.hibernate-orm.jdbc.timezone

quarkus.hibernate-orm."persistence-unit-name".jdbc.timezone

The time zone pushed to the JDBC driver. See quarkus.hibernate-orm.mapping.timezone.default-storage.

Environment variable: QUARKUS_HIBERNATE_ORM_JDBC_TIMEZONE

string

quarkus.hibernate-orm.jdbc.statement-fetch-size

quarkus.hibernate-orm."persistence-unit-name".jdbc.statement-fetch-size

How many rows are fetched at a time by the JDBC driver.

Environment variable: QUARKUS_HIBERNATE_ORM_JDBC_STATEMENT_FETCH_SIZE

int

quarkus.hibernate-orm.jdbc.statement-batch-size

quarkus.hibernate-orm."persistence-unit-name".jdbc.statement-batch-size

The number of updates (inserts, updates and deletes) that are sent by the JDBC driver at one time for execution.

Environment variable: QUARKUS_HIBERNATE_ORM_JDBC_STATEMENT_BATCH_SIZE

int

Fetching logic configuration

Tipo

Padrão

quarkus.hibernate-orm.fetch.batch-size

quarkus.hibernate-orm."persistence-unit-name".fetch.batch-size

The size of the batches used when loading entities and collections.

-1 means batch loading is disabled.

Environment variable: QUARKUS_HIBERNATE_ORM_FETCH_BATCH_SIZE

int

16

quarkus.hibernate-orm.fetch.max-depth

quarkus.hibernate-orm."persistence-unit-name".fetch.max-depth

The maximum depth of outer join fetch tree for single-ended associations (one-to-one, many-to-one).

A 0 disables default outer join fetching.

Environment variable: QUARKUS_HIBERNATE_ORM_FETCH_MAX_DEPTH

int

Caching configuration

Tipo

Padrão

quarkus.hibernate-orm.cache."cache".expiration.max-idle

quarkus.hibernate-orm."persistence-unit-name".cache."cache".expiration.max-idle

The maximum time before an object of the cache is considered expired.

Environment variable: QUARKUS_HIBERNATE_ORM_CACHE__CACHE__EXPIRATION_MAX_IDLE

Duration

quarkus.hibernate-orm.cache."cache".memory.object-count

quarkus.hibernate-orm."persistence-unit-name".cache."cache".memory.object-count

The maximum number of objects kept in memory in the cache.

Environment variable: QUARKUS_HIBERNATE_ORM_CACHE__CACHE__MEMORY_OBJECT_COUNT

long

Discriminator related configuration

Tipo

Padrão

quarkus.hibernate-orm.discriminator.ignore-explicit-for-joined

quarkus.hibernate-orm."persistence-unit-name".discriminator.ignore-explicit-for-joined

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: QUARKUS_HIBERNATE_ORM_DISCRIMINATOR_IGNORE_EXPLICIT_FOR_JOINED

booleano

false

Logging configuration

Tipo

Padrão

quarkus.hibernate-orm.log.bind-parameters

Logs SQL bind parameters.

Setting it to true is obviously not recommended in production.

Environment variable: QUARKUS_HIBERNATE_ORM_LOG_BIND_PARAMETERS

booleano

false

quarkus.hibernate-orm.log.sql

quarkus.hibernate-orm."persistence-unit-name".log.sql

Show SQL logs and format them nicely.

Setting it to true is obviously not recommended in production.

Environment variable: QUARKUS_HIBERNATE_ORM_LOG_SQL

booleano

false

quarkus.hibernate-orm.log.format-sql

quarkus.hibernate-orm."persistence-unit-name".log.format-sql

Format the SQL logs if SQL log is enabled

Environment variable: QUARKUS_HIBERNATE_ORM_LOG_FORMAT_SQL

booleano

true

quarkus.hibernate-orm.log.highlight-sql

quarkus.hibernate-orm."persistence-unit-name".log.highlight-sql

Highlight the SQL logs if SQL log is enabled

Environment variable: QUARKUS_HIBERNATE_ORM_LOG_HIGHLIGHT_SQL

booleano

true

quarkus.hibernate-orm.log.jdbc-warnings

quarkus.hibernate-orm."persistence-unit-name".log.jdbc-warnings

Whether JDBC warnings should be collected and logged.

Environment variable: QUARKUS_HIBERNATE_ORM_LOG_JDBC_WARNINGS

booleano

depends on dialect

quarkus.hibernate-orm.log.queries-slower-than-ms

quarkus.hibernate-orm."persistence-unit-name".log.queries-slower-than-ms

If set, Hibernate will log queries that took more than specified number of milliseconds to execute.

Environment variable: QUARKUS_HIBERNATE_ORM_LOG_QUERIES_SLOWER_THAN_MS

long

Database scripts related configuration

Tipo

Padrão

quarkus.hibernate-orm.scripts.generation

quarkus.hibernate-orm."persistence-unit-name".scripts.generation

Select whether the database schema DDL files are generated or not. Accepted values: none, create, drop-and-create, drop, update, validate.

Environment variable: QUARKUS_HIBERNATE_ORM_SCRIPTS_GENERATION

string

none

quarkus.hibernate-orm.scripts.generation.create-target

quarkus.hibernate-orm."persistence-unit-name".scripts.generation.create-target

Filename or URL where the database create DDL file should be generated.

Environment variable: QUARKUS_HIBERNATE_ORM_SCRIPTS_GENERATION_CREATE_TARGET

string

quarkus.hibernate-orm.scripts.generation.drop-target

quarkus.hibernate-orm."persistence-unit-name".scripts.generation.drop-target

Filename or URL where the database drop DDL file should be generated.

Environment variable: QUARKUS_HIBERNATE_ORM_SCRIPTS_GENERATION_DROP_TARGET

string

Flush configuration

Tipo

Padrão

quarkus.hibernate-orm.flush.mode

quarkus.hibernate-orm."persistence-unit-name".flush.mode

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 Session#setHibernateFlushMode() or on a per-query basis with the hint HibernateHints#HINT_FLUSH_MODE.

See the javadoc of org.hibernate.FlushMode for details.

Environment variable: QUARKUS_HIBERNATE_ORM_FLUSH_MODE

manual, commit, auto, always

auto

About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

Você também pode usar um formato simplificado, começando com um número:

Se o valor for apenas um número, ele representará o tempo em segundos.
Se o valor for um número seguido de 'ms', ele representa o tempo em milissegundos.

Em outros casos, o formato simplificado é traduzido para o formato 'java.time.Duration' para análise:

Se o valor for um número seguido de 'h', 'm' ou 's', ele é prefixado com 'PT'.
Se o valor for um número seguido de 'd', ele é prefixado com 'P'.

Não misture as propriedades persistence.xml e quarkus.hibernate-orm.* em application.properties. O Quarkus lançará uma exceção. Decida qual abordagem você deseja utilizar.

Se o classpath contiver um persistence.xml que o você deseja ignorar, defina a seguinte propriedade de configuração:

quarkus.hibernate-orm.persistence-xml.ignore=true

Want to start a PostgreSQL server on the side with Docker?

docker run --rm=true --name postgres-quarkus-hibernate -e POSTGRES_USER=hibernate \
           -e POSTGRES_PASSWORD=hibernate -e POSTGRES_DB=hibernate_db \
           -p 5432:5432 postgres:14.1

This will start a non-durable empty database: ideal for a quick experiment!

Múltiplas unidades de persistência

Configuração de várias unidades de persistência

É possível definir várias unidades de persistência usando as propriedades de configuração do Quarkus.

As propriedades na raiz do namespace quarkus.hibernate-orm. definem a unidade de persistência padrão. Por exemplo, o snippet a seguir define uma fonte de dados padrão e uma unidade de persistência padrão:

quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:mem:default;DB_CLOSE_DELAY=-1

quarkus.hibernate-orm.database.generation=drop-and-create

Usando uma abordagem baseada em mapa, é possível definir unidades de persistência nomeadas:

quarkus.datasource."users".db-kind=h2 (1)
quarkus.datasource."users".jdbc.url=jdbc:h2:mem:users;DB_CLOSE_DELAY=-1

quarkus.datasource."inventory".db-kind=h2 (2)
quarkus.datasource."inventory".jdbc.url=jdbc:h2:mem:inventory;DB_CLOSE_DELAY=-1

quarkus.hibernate-orm."users".database.generation=drop-and-create (3)
quarkus.hibernate-orm."users".datasource=users (4)
quarkus.hibernate-orm."users".packages=org.acme.model.user (5)

quarkus.hibernate-orm."inventory".database.generation=drop-and-create (6)
quarkus.hibernate-orm."inventory".datasource=inventory
quarkus.hibernate-orm."inventory".packages=org.acme.model.inventory

1	Defina uma fonte de dados chamada `users`.
2	Defina uma fonte de dados chamada `inventory`.
3	Defina uma unidade de persistência chamada `users`.
4	Definir a fonte de dados usada pela unidade de persistência.
5	Essa propriedade de configuração é importante, mas a discutiremos um pouco mais adiante.
6	Defina uma unidade de persistência chamada `inventory` apontando para a fonte de dados `inventory` .

Você pode misturar a fonte de dados padrão e as fontes de dados nomeadas ou ter apenas uma ou outra.

A unidade de persistência padrão aponta para a fonte de dados padrão por padrão. Para unidades de persistência nomeadas, a propriedade datasource é obrigatória. Você pode apontar sua unidade de persistência para a fonte de dados padrão, definindo-a como <default> (que é o nome interno da fonte de dados padrão).

É perfeitamente válido ter várias unidades de persistência apontando para a mesma fonte de dados.

Anexar classes de modelo a unidades de persistência

Há duas maneiras de anexar classes de modelo a unidades de persistência, e elas não devem ser misturadas:

Por meio da propriedade de configuração packages;
Por meio da anotação em nível de pacote @io.quarkus.hibernate.orm.PersistenceUnit.

Se ambos forem misturados, as anotações serão ignoradas e somente as propriedades de configuração do packages serão levadas em conta.

Usar a propriedade de configuração packages é simples:

quarkus.hibernate-orm.database.generation=drop-and-create
quarkus.hibernate-orm.packages=org.acme.model.defaultpu

quarkus.hibernate-orm."users".database.generation=drop-and-create
quarkus.hibernate-orm."users".datasource=users
quarkus.hibernate-orm."users".packages=org.acme.model.user

Esse snippet de configuração criará duas unidades de persistência:

O padrão que conterá todas as classes de modelo no pacote org.acme.model.defaultpu, incluindo os subpacotes.
Uma unidade de persistência nomeada users que conterá todas as classes de modelo do pacote org.acme.model.user, incluindo os subpacotes.

Você pode anexar vários pacotes a uma unidade de persistência:

quarkus.hibernate-orm."users".packages=org.acme.model.shared,org.acme.model.user

Todas as classes de modelo dos pacotes org.acme.model.shared e org.acme.model.user serão vinculadas à unidade de persistência users .

Também é suportado vincular uma determinada classe de modelo a várias unidades de persistência.

As classes de modelo precisam ser adicionadas de forma consistente a uma determinada unidade de persistência. Isso significa que todas as classes de modelo dependentes de uma determinada entidade (superclasses mapeadas, embeddables…) precisam estar vinculadas à unidade de persistência. Como estamos lidando com a unidade de persistência no nível do pacote, isso deve ser bastante simples.

Entidades Panache podem ser vinculadas a apenas uma unidade de persistência.

Para entidades vinculadas a várias unidades de persistência, não é possível utilizar o Panache. É possível, no entanto, combinar as duas abordagens e mesclar entidades Panache e entidades tradicionais quando múltiplas unidades de persistência forem necessárias.

Se você tiver um caso de uso para isso e ideias inteligentes sobre como implementá-lo sem poluir a abordagem simplificada do Panache, entre em contato pelo lista de discussão quarkus-dev.

A segunda abordagem para vincular classes de modelo a uma unidade de persistência é utilizar anotações @io.quarkus.hibernate.orm.PersistenceUnit no nível de pacote. Novamente, as duas abordagens não podem ser combinadas.

Para obter uma configuração semelhante à acima com a propriedade de configuração packages, crie um arquivo package-info.java com o seguinte conteúdo:

@PersistenceUnit("users") (1)
package org.acme.model.user;

import io.quarkus.hibernate.orm.PersistenceUnit;

1	Cuidado, use a anotação `@io.quarkus.hibernate.orm.PersistenceUnit`, não a do Jakarta Persistence.

Suportamos apenas a definição de @PersistenceUnit para classes de modelo no nível do pacote, o uso da anotação @PersistenceUnit no nível da classe não é compatível nesse caso.

Observe que, de forma semelhante ao que fazemos com a propriedade de configuração, levamos em consideração o pacote anotado e também todos os seus subpacotes.

Integração com CDI

Se você já está familiarizado com o uso do Hibernate ORM no Quarkus, provavelmente já injetou o EntityManager via CDI:

@Inject
EntityManager entityManager;

Isso injetará o EntityManager da unidade de persistência padrão.

Injetar o EntityManager de uma unidade de persistência nomeada (users em nosso exemplo) é tão simples quanto:

@Inject
@PersistenceUnit("users") (1)
EntityManager entityManager;

1	Aqui, novamente, usamos a mesma anotação `@io.quarkus.hibernate.orm.PersistenceUnit`.

Você pode injetar o EntityManagerFactory de uma unidade de persistência nomeada utilizando o mesmo mecanismo:

@Inject
@PersistenceUnit("users")
EntityManagerFactory entityManagerFactory;

Ativar/desativar unidades de persistência

If a persistence unit is configured at build time, by default it is active at runtime, that is Quarkus will start the corresponding Hibernate ORM SessionFactory on application startup.

To deactivate a persistence unit at runtime, set quarkus.hibernate-orm[.optional name].active to false. If a persistence unit is not active:

The SessionFactory will not start during application startup.
Accessing the EntityManagerFactory/EntityManager or SessionFactory/Session will cause an exception to be thrown.

Isso é particularmente útil quando você deseja que uma aplicação seja capaz de utilizar um dos datasources de um conjunto predeterminado em tempo de execução.

Por exemplo, com a seguinte configuração:

quarkus.hibernate-orm."pg".packages=org.acme.model.shared
quarkus.hibernate-orm."pg".datasource=pg
quarkus.hibernate-orm."pg".database.generation=drop-and-create
quarkus.hibernate-orm."pg".active=false
quarkus.datasource."pg".db-kind=h2
quarkus.datasource."pg".active=false
quarkus.datasource."pg".jdbc.url=jdbc:postgresql:///your_database

quarkus.hibernate-orm."oracle".packages=org.acme.model.shared
quarkus.hibernate-orm."oracle".datasource=oracle
quarkus.hibernate-orm."oracle".database.generation=drop-and-create
quarkus.hibernate-orm."oracle".active=false
quarkus.datasource."oracle".db-kind=oracle
quarkus.datasource."oracle".active=false
quarkus.datasource."oracle".jdbc.url=jdbc:oracle:///your_database

A configuração de quarkus.hibernate-orm."pg".active=true e quarkus.datasource."pg".active=true em tempo de execução disponibilizará apenas a unidade de persistência e a fonte de dados do PostgreSQL, e a configuração de quarkus.hibernate-orm."oracle".active=true e quarkus.datasource."oracle".active=true em tempo de execução disponibilizará apenas a unidade de persistência e a fonte de dados do Oracle.

Os perfis de configuração personalizados podem ajudar a simplificar essa configuração. Ao anexar a seguinte configuração específica de perfil à configuração acima, você pode selecionar uma unidade de persistência/fonte de dados em tempo de execução simplesmente definindo quarkus.profile: quarkus.profile=prod,pg ou quarkus.profile=prod,oracle.

%pg.quarkus.hibernate-orm."pg".active=true
%pg.quarkus.datasource."pg".active=true
# Add any pg-related runtime configuration here, prefixed with "%pg."

%oracle.quarkus.hibernate-orm."oracle".active=true
%oracle.quarkus.datasource."oracle".active=true
# Add any pg-related runtime configuration here, prefixed with "%pg."

With such a setup, you will need to take care to only ever access the active persistence unit. To do so, you may define a CDI bean producer for the default Session redirecting to the currently active named Session, so that it can be injected directly, like this:

public class MyProducer {
    @Inject
    @DataSource("pg")
    InjectableInstance<AgroalDataSource> pgDataSourceBean; (1)

    @Inject
    @DataSource("oracle")
    InjectableInstance<AgroalDataSource> oracleDataSourceBean;

    @Inject
    @PersistenceUnit("pg")
    Session pgSessionBean;

    @Inject
    @PersistenceUnit("oracle")
    Session oracleSessionBean;

    @Produces (2)
    @ApplicationScoped
    public Session session() {
        if (pgDataSourceBean.getHandle().getBean().isActive()) { (3)
            return pgSessionBean;
        } else if (oracleDataSourceBean.getHandle().getBean().isActive()) { (3)
            return oracleSessionBean;
        } else {
            throw new RuntimeException("No active datasource!");
        }
    }
}

@ApplicationScoped
public class MyConsumer {
    @Inject
    Session session; (4)

    public void doSomething() {
        // .. just use the injected session ...
    }
}

1	Don’t inject a `DataSource` or `AgroalDatasource` directly, because that would lead to a failure on startup (can’t inject inactive beans). Instead, inject `InjectableInstance<DataSource>` or `InjectableInstance<AgroalDataSource>`.
2	Declare a CDI producer method that will define the default session as either PostgreSQL or Oracle, depending on what is active.
3	Check whether datasource beans are active before retrieving the corresponding session.
4	This will get injected with the (only) active session.

Configurando o Hibernate ORM com um `persistence.xml`

Para definir e configurar o Hibernate ORM, recomenda-se using application.properties, mas você também pode usar um arquivo META-INF/persistence.xml. Isso é útil principalmente para migrar o código existente para o Quarkus.

O uso de um arquivo persistence.xml implica algumas restrições:

As unidades de persistência definidas em persistence.xml sempre usam a fonte de dados padrão .
As unidades de persistência definidas em persistence.xml devem ser configuradas explicitamente: O Quarkus manterá a injeção de configuração relacionada ao ambiente em um nível mínimo.

Em particular, o Quarkus não configurará automaticamente o dialeto ou a versão do banco de dados com base na fonte de dados, portanto, se a configuração padrão do Hibernate ORM não atender às suas necessidades, você precisará incluir em persistence.xml configurações como hibernate.dialect/jakarta.persistence.database-product-name e possivelmente jakarta.persistence.database-product-version.
O uso do persistence.xml é incompatível com o uso das propriedades do quarkus.hibernate-orm.* no application.properties: se você misturar os dois, o Quarkus abrirá uma exceção.
A experiência do desenvolvedor pode ser afetada negativamente ao usar o site persistence.xml em comparação com using application.properties, devido a recursos indisponíveis, orientação limitada na documentação do Quarkus e mensagens de erro que fornecem dicas de resolução que não podem ser aplicadas (por exemplo, usando as propriedades do site quarkus.hibernate-orm.*).

Se o classpath contiver um persistence.xml que o você deseja ignorar, defina a seguinte propriedade de configuração:

quarkus.hibernate-orm.persistence-xml.ignore=true

As dependências pom.xml, bem como o código Java, seriam idênticos ao exemplo anterior. A única diferença é que você especificaria a configuração do Hibernate ORM em META-INF/persistence.xml:

Exemplo de recurso persistence.xml

<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
             http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
             version="2.1">

    <persistence-unit name="CustomerPU" transaction-type="JTA">

        <description>My customer entities</description>

        <properties>
            <!-- Connection specific -->
            <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/>

            <property name="hibernate.show_sql" value="true"/>
            <property name="hibernate.format_sql" value="true"/>

            <!--
                Optimistically create the tables;
                will cause background errors being logged if they already exist,
                but is practical to retain existing data across runs (or create as needed) -->
            <property name="jakarta.persistence.schema-generation.database.action" value="drop-and-create"/>

            <property name="jakarta.persistence.validation.mode" value="NONE"/>
        </properties>

    </persistence-unit>
</persistence>

Ao usar a configuração persistence.xml, você está configurando o Hibernate ORM diretamente, portanto, nesse caso, a referência apropriada é a documentação em hibernate.org.

Lembre-se de que esses não são os mesmos nomes de propriedade usados no Quarkus application.properties, nem os mesmos padrões serão aplicados.

Mapeamento XML

O Hibernate ORM no Quarkus oferece suporte ao mapeamento XML. Você pode adicionar arquivos de mapeamento seguindo o orm.xml format (Jakarta Persistence) ou o hbm.xml format (specific to Hibernate ORM, deprecated):

em application.properties por meio da propriedade (build-time) quarkus.hibernate-orm.mapping-filespropriedade.
em persistence.xml por meio do elemento <mapping-file>.

Os arquivos de mapeamento XML são analisados no momento da compilação.

O arquivo META-INF/orm.xml sempre será incluído por padrão, se existir no classpath.

Se não for isso que você deseja, use quarkus.hibernate-orm.mapping-files = no-file ou <mapping-file>no-file</mapping-file>.

Definição de entidades em projetos externos ou jars

O Hibernate ORM no Quarkus depende de aprimoramentos de bytecode em tempo de compilação para suas entidades. Se você definir as entidades no mesmo projeto em que criou o aplicativo Quarkus, tudo funcionará bem.

Se as entidades vierem de projetos ou jars externos, você pode garantir que o seu jar seja tratado como uma biblioteca de aplicação Quarkus adicionando um arquivo META-INF/beans.xml vazio.

Isso permitirá que o Quarkus indexe e aprimore suas entidades como se elas estivessem dentro do projeto atual.

Hibernate ORM no modo de desenvolvimento

O modo de desenvolvimento do Quarkus é muito útil para aplicações que combinam frontend ou serviços com acesso a banco de dados.

Há algumas abordagens comuns para tirar o melhor proveito disso.

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

Dessa forma, a cada alteração na sua aplicação e, em particular, nas suas entidades, o schema do banco de dados será recriado corretamente e seus dados de fixture (armazenados em import.sql) serão usados para repopulá-lo do zero. Isso é ideal para ter controle total sobre seu ambiente e funciona perfeitamente com o modo de live reload do Quarkus: qualquer alteração nas suas entidades ou no import.sql é imediatamente detectada e o schema é atualizado sem reiniciar a aplicação!

By default, in dev and test modes, Hibernate ORM, upon boot, will read and execute the SQL statements in the /import.sql file (if present). You can change the file name by changing the property quarkus.hibernate-orm.sql-load-script in application.properties.

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.

Com essa abordagem, ao fazer alterações em uma entidade, certifique-se de adaptar o schema do banco de dados adequadamente, você também pode usar validate para que o Hibernate verifique se o schema corresponde às suas expectativas.

Do not use quarkus.hibernate-orm.database.generation drop-and-create and update in your production environment.

Essas abordagens se tornam muito poderosas quando combinadas com os perfis de configuração do Quarkus. Você pode definir diferentes perfis de configuração para selecionar comportamentos distintos dependendo do seu ambiente. Isso é excelente porque permite definir diferentes combinações de propriedades do Hibernate ORM que correspondam ao estilo de desenvolvimento que você precisa no momento.

application.properties

%dev.quarkus.hibernate-orm.database.generation = drop-and-create
%dev.quarkus.hibernate-orm.sql-load-script = import-dev.sql

%dev-with-data.quarkus.hibernate-orm.database.generation = update
%dev-with-data.quarkus.hibernate-orm.sql-load-script = no-file

%prod.quarkus.hibernate-orm.database.generation = none
%prod.quarkus.hibernate-orm.sql-load-script = no-file

Você pode iniciar o modo de desenvolvimento usando um perfil personalizado:

CLI

quarkus dev -Dquarkus.profile=dev-with-data

Maven

./mvnw quarkus:dev -Dquarkus.profile=dev-with-data

Gradle

./gradlew --console=plain quarkusDev -Dquarkus.profile=dev-with-data

Hibernate ORM em modo de produção

O Quarkus vem com perfis padrão ( dev , test e prod ). E você pode adicionar seus próprios perfis personalizados para descrever vários ambientes ( staging , prod-us , etc).

A extensão Hibernate ORM Quarkus define algumas configurações padrão de forma diferente nos modos de desenvolvimento e teste do que em outros ambientes.

quarkus.hibernate-orm.sql-load-script é definido como no-file para todos os perfis, exceto os perfis dev e test.

Você pode substituí-lo explicitamente no seu application.properties (por exemplo, %prod.quarkus.hibernate-orm.sql-load-script = import.sql ), mas queríamos que você evitasse substituir o banco de dados por acidente no prod :)

Por falar nisso, certifique-se de não descartar o esquema do banco de dados na produção! Adicione o seguinte em seu arquivo de propriedades.

application.properties

%prod.quarkus.hibernate-orm.database.generation = none
%prod.quarkus.hibernate-orm.sql-load-script = no-file

Transacionando automaticamente para o Flyway para gerenciar schemas

Se você tiver a extensão Flyway instalada ao executar no modo de desenvolvimento, o Quarkus oferece uma forma simples de inicializar sua configuração do Flyway utilizando o schema gerado automaticamente pelo Hibernate ORM. O objetivo é facilitar a transição da fase inicial de desenvolvimento, onde o Hibernate pode ser usado para configurar o schema rapidamente, para a fase de produção, onde o Flyway é utilizado para gerenciar as alterações do schema.

Para usar esse recurso, basta abrir a Dev UI quando a extensão quarkus-flyway estiver instalada e clicar no link Datasources no painel Flyway. Pressione o botão Create Initial Migration e ocorrerá o seguinte:

Um arquivo db/migration/V1.0.0__{appname}.sql será criado, contendo o SQL que o Hibernate está executando para gerar o esquema
quarkus.flyway.baseline-on-migrate será definido, informando ao Flyway para criar automaticamente suas tabelas de linha de base
quarkus.flyway.migrate-at-start será definido, informando ao Flyway para aplicar automaticamente as migrações na inicialização da aplicação
%dev.quarkus.flyway.clean-at-start e %test.quarkus.flyway.clean-at-start serão definidos para limpar o banco de dados após o recarregamento no modo dev/test

Esse botão é apenas uma conveniência para ajudá-lo a começar rapidamente com o Flyway, cabe a você determinar como deseja gerenciar os schemas do seu banco de dados em produção. Em particular, a configuração migrate-at-start pode não ser adequada para todos os ambientes.

Armazenamento em cache

Aplicações que leem as mesmas entidades com frequência podem ter seu desempenho melhorado quando o cache de segundo nível do Hibernate ORM está habilitado.

Armazenamento em cache de entidades

Para ativar o cache de segundo nível, marque as entidades que você deseja armazenar em cache com @jakarta.persistence.Cacheable:

@Entity
@Cacheable
public class Country {
    int dialInCode;
    // ...
}

Quando uma entidade é anotada com @Cacheable, todos os seus valores de campo são armazenados em cache, exceto para coleções e relações com outras entidades.

Isso significa que a entidade pode ser carregada sem consultar o banco de dados, mas é preciso ter cuidado, pois isso implica que a entidade carregada pode não refletir as alterações recentes no banco de dados.

Armazenamento em cache de coleções e relações

Coleções e relacionamentos precisam ser anotados individualmente para serem cacheados; nesse caso, deve-se utilizar a anotação específica do Hibernate @org.hibernate.annotations.Cache, que também requer a especificação da CacheConcurrencyStrategy:

package org.acme;

@Entity
@Cacheable
public class Country {
    // ...

    @OneToMany
    @Cache(usage = CacheConcurrencyStrategy.READ_ONLY)
    List<City> cities;

    // ...
}

Cache de queries

As queries também podem se beneficiar do cache de segundo nível. Os resultados de queries em cache podem ser retornados imediatamente ao chamador, evitando a execução da query no banco de dados.

Tenha cuidado, pois isso implica que os resultados podem não refletir alterações recentes.

Para cachear uma query, marque-a como cacheável na instância de Query:

Query query = ...
query.setHint("org.hibernate.cacheable", Boolean.TRUE);

Se você tiver uma NamedQuery, pode habilitar o cache diretamente em sua definição, que geralmente estará em uma entidade:

@Entity
@NamedQuery(name = "Fruits.findAll",
      query = "SELECT f FROM Fruit f ORDER BY f.name",
      hints = @QueryHint(name = "org.hibernate.cacheable", value = "true") )
public class Fruit {
   ...

É só isso! A tecnologia de cache já está integrada e habilitada por padrão no Quarkus, portanto basta definir quais podem ser cacheados com segurança.

Ajuste das regiões de cache

Os caches armazenam os dados em regiões separadas para isolar diferentes porções de dados, essas regiões recebem um nome, o que é útil para configurar cada região de forma independente ou para monitorar suas estatísticas.

Por padrão, as entidades são cacheadas em regiões nomeadas de acordo com seu nome completamente qualificado, por exemplo, org.acme.Country.

As coleções são armazenadas em cache em regiões nomeadas com o nome totalmente qualificado de sua entidade proprietária e o nome do campo da coleção, separados pelo caractere #, por exemplo, org.acme.Country#cities .

Por padrão, todas as consultas em cache são mantidas em uma única região dedicada a elas, chamada default-query-results-region.

Todas as regiões são limitadas por tamanho e tempo por padrão. Os padrões são 10000 max entries e 100 seconds como tempo máximo de inatividade.

O tamanho de cada região pode ser personalizado por meio da propriedade quarkus.hibernate-orm.cache."<region_name>".memory.object-count (Substitua <region_name> pelo nome real da região).

Para definir o tempo ocioso máximo, forneça a duração (consulte a nota sobre o formato da duração abaixo) por meio da propriedade quarkus.hibernate-orm.cache."<region_name>".expiration.max-idle (Substitua <region_name> pelo nome real da região).

As aspas duplas são obrigatórias se o nome da região contiver um ponto. Por exemplo:

quarkus.hibernate-orm.cache."org.acme.MyEntity".memory.object-count=1000

To write duration values, use the standard java.time.Duration format. See the Duration#parse() javadoc for more information.

Você também pode usar um formato simplificado, começando com um número:

Se o valor for apenas um número, ele representará o tempo em segundos.
Se o valor for um número seguido de 'ms', ele representa o tempo em milissegundos.

Em outros casos, o formato simplificado é traduzido para o formato 'java.time.Duration' para análise:

Se o valor for um número seguido de 'h', 'm' ou 's', ele é prefixado com 'PT'.
Se o valor for um número seguido de 'd', ele é prefixado com 'P'.

Limitações do cache

Atualmente, a tecnologia de cache fornecida pelo Quarkus é bastante rudimentar e limitada.

A equipe achou que era melhor ter algum recurso de cache para começar do que não ter nada, você pode esperar que uma solução de cache melhor seja integrada em versões futuras, e qualquer ajuda e feedback nessa área é muito bem-vinda.

Esses caches são mantidos localmente, portanto não são invalidados nem atualizados quando alterações são feitas no armazenamento persistente por outras aplicações.

Além disso, ao executar múltiplas instâncias da mesma aplicação (em um cluster, por exemplo no Kubernetes/OpenShift), os caches em instâncias separadas da aplicação não são sincronizados.

Por essas razões, habilitar o cache só é adequado quando certas premissas podem ser assumidas: recomendamos fortemente que apenas entidades, coleções e queries que nunca mudam sejam cacheadas. Ou, no máximo, que quando uma entidade for de fato modificada e permitida de ser lida de forma desatualizada (stale), isso não impacte as expectativas da aplicação.

Seguir esse conselho garante que as aplicações obtenham o melhor desempenho do cache de segundo nível e, ao mesmo tempo, evitem comportamentos inesperados.

Além dos dados imutáveis, em determinados contextos, pode ser aceitável habilitar o cache também em dados mutáveis, isso pode ser uma troca necessária em entidades selecionadas que são lidas com frequência e para as quais algum grau de obsoletismo é aceitável, esse "grau aceitável de obsoletismo" pode ser ajustado definindo-se as propriedades de despejo. No entanto, isso não é recomendado e deve ser feito com extremo cuidado, pois pode produzir efeitos inesperados e imprevistos nos dados.

Em vez de habilitar o cache em dados mutáveis, a solução ideal seria utilizar um cache clusterizado; no entanto, no momento o Quarkus não oferece nenhuma implementação desse tipo: sinta-se à vontade para entrar em contato e informar essa necessidade para que a equipe possa levá-la em consideração.

Por fim, o cache de segundo nível pode ser desativado globalmente ao definir hibernate.cache.use_second_level_cache como false, essa é uma configuração que precisa ser especificada no arquivo de configuração persistence.xml.

Quando o cache de segundo nível está desativado, todas as anotações de cache são ignoradas e todas as consultas são executadas ignorando os caches, isso geralmente é útil apenas para diagnosticar problemas.

Hibernate Envers

A extensão Envers do Hibernate ORM tem como objetivo fornecer uma solução fácil de auditoria/controle de versão para classes de entidades.

No Quarkus, o Envers tem uma extensão dedicada do Quarkus io.quarkus:quarkus-hibernate-envers, você só precisa adicioná-la ao seu projeto para começar a usá-la.

Dependência adicional para ativar o Hibernate Envers

    <!-- Add the Hibernate Envers extension -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-hibernate-envers</artifactId>
    </dependency>

Nesse momento, a extensão não expõe propriedades de configuração adicionais.

Para obter mais informações sobre o Hibernate Envers, consulte hibernate.org/orm/envers/ .

Métricas

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.

Limitações e outras informações importantes

O Quarkus não modifica as bibliotecas que utiliza, essa regra também se aplica ao Hibernate ORM: ao usar esta extensão, você terá basicamente a mesma experiência de usar a biblioteca original.

Porém, embora compartilhem o mesmo código, o Quarkus configura alguns componentes automaticamente e injeta implementações customizadas para alguns pontos de extensão, isso deve ser transparente e útil, mas se você for um especialista em Hibernate pode querer saber o que está sendo feito.

Enhancement automático em tempo de build

O Hibernate ORM pode utilizar entidades com enhancement em tempo de build, normalmente isso não é obrigatório, mas é útil e fará com que suas aplicações tenham melhor desempenho.

Normalmente, seria necessário adaptar seus scripts de build para incluir os plugins de Enhancement do Hibernate, no Quarkus isso não é necessário, pois a etapa de enhancement está integrada ao build e à análise da aplicação Quarkus.

Devido ao uso de aprimoramento, o uso do método clone() em entidades não é suportado no momento, pois ele também clonará alguns campos específicos de aprimoramento que são específicos da entidade.

Essa limitação pode ser removida no futuro.

Integração automática

Integração com o Transaction Manager: Você não precisa configurar isso, o Quarkus injeta automaticamente a referência ao Narayana Transaction Manager. A dependência é incluída automaticamente como uma dependência transitiva da extensão do Hibernate ORM. Toda a configuração é opcional, para mais detalhes, consulte Usando Transações no Quarkus.
Pool de conexões: Também não é necessário escolher um. O Quarkus inclui automaticamente o pool de conexões Agroal, configure seu datasource como nos exemplos acima e ele configurará o Hibernate ORM para usar o Agroal. Mais detalhes sobre esse pool de conexões podem ser encontrados em Quarkus - Datasources.
Cache de segundo nível: Conforme explicado anteriormente na seção de Cache, você não precisa escolher uma implementação. Uma implementação adequada baseada nas tecnologias do Infinispan e do Caffeine é incluída como uma dependência transitiva da extensão do Hibernate ORM e integrada automaticamente durante a compilação.

Limitações

Mapeamento XML com arquivos duplicados no classpath: Espera-se que os arquivos de mapeamento XML tenham um caminho exclusivo.

Na prática, só é possível ter arquivos de mapeamento XML duplicados no classpath em cenários muito específicos. Por exemplo, se dois JARs incluírem um arquivo META-INF/orm.xml (com exatamente o mesmo caminho, mas em JARs diferentes), o caminho do arquivo de mapeamento META-INF/orm.xml só poderá ser referenciado a partir de um persistence.xml no mesmo JAR que o arquivo META-INF/orm.xml .
JMX: Os beans de gerenciamento não estão funcionando nas imagens nativas do GraalVM, portanto, a capacidade do Hibernate de registrar estatísticas e operações de gerenciamento com o bean JMX é desativada ao compilar em uma imagem nativa. Essa limitação provavelmente é permanente, pois não é um objetivo das imagens nativas implementar o suporte ao JMX. Todas essas métricas podem ser acessadas de outras formas.
Integração da JACC: A capacidade do Hibernate ORM de se integrar ao JACC é desativada ao criar imagens nativas do GraalVM pois o JACC não está disponível - nem é útil - no modo nativo.
Vinculação da sessão ao contexto ThreadLocal: É impossível usar o auxiliar ThreadLocalSessionContext do Hibernate ORM, pois o suporte a ele não está implementado. Como o Quarkus oferece suporte a CDI pronto para uso, a injeção ou a pesquisa programática de CDI é uma abordagem melhor. Esse recurso também não se integrou bem aos componentes reativos e às técnicas mais modernas de propagação de contexto, o que nos faz acreditar que esse recurso legado não tem futuro. Você precisar muito associá-lo a um ThreadLocal, deve ser trivial implementá-lo em seu próprio código.
JNDI: A tecnologia JNDI é comumente usada em outros tempos de execução para integrar diferentes componentes. Um caso de uso comum são os servidores Java Enterprise para vincular os componentes TransactionManager e Datasource a um nome e, em seguida, ter o Hibernate ORM configurado para procurar esses componentes pelo nome. Mas no Quarkus, esse caso de uso não se aplica, pois os componentes são injetados diretamente, tornando o suporte a JNDI um legado desnecessário. Para evitar o uso inesperado do JNDI, o suporte total ao JNDI foi desativado na extensão do Hibernate ORM para o Quarkus. Isso é tanto uma precaução de segurança quanto uma otimização.

Outras diferenças notáveis

Formato de import.sql: Ao importar um import.sql para configurar o banco de dados, lembre-se de que o Quarkus reconfigura o Hibernate ORM de modo a exigir um ponto e vírgula ( ; ) para encerrar cada instrução. O padrão no Hibernate é ter uma instrução por linha, sem exigir um terminador diferente de nova linha: lembre-se de converter seus scripts para usar o caractere de terminação ; se estiver reutilizando scripts existentes. Isso é útil para permitir declarações de várias linhas e formatação amigável.

Simplificando o Hibernate ORM com o Panache

A extensão Hibernate ORM with Panache facilita o uso do Hibernate ORM fornecendo entidades (e repositórios) no estilo de Active Record e concentra-se em tornar as entidades triviais e divertidas de escrever no Quarkus.

Configure sua fonte de dados

A configuração do Datasource é extremamente simples, mas é abordada em outro guia, pois tecnicamente é implementada pela extensão do pool de conexões do Agroal para o Quarkus.

Acesse Quarkus - Datasources para obter todos os detalhes.

Multitenancy

"O termo multitenancy, em geral, é aplicado ao desenvolvimento de software para indicar uma arquitetura na qual uma única instância em execução de um aplicativo atende simultaneamente a vários clientes (locatários). Isso é muito comum em soluções de SaaS. O isolamento de informações (dados, personalizações etc.) pertencentes aos vários locatários é um desafio especial nesses sistemas. Isso inclui os dados de propriedade de cada locatário armazenados no banco de dados" (Guia do Usuário do Hibernate).

Atualmente, o Quarkus suporta a abordagem de banco de dados separado, a abordagem de esquema separado e a abordagem de discriminador.

Para ver o multitenancy em ação, você pode conferir o hibernate-orm-multi-tenancy-schema-quickstart ou o hibernate-orm-multi-tenancy-database-quickstart .

Escrevendo o aplicativo

Vamos começar implementando o endpoint /{tenant}. Como você pode ver no código-fonte abaixo, ele é apenas um recurso Jakarta REST comum:

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.persistence.EntityManager;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@ApplicationScoped
@Path("/{tenant}")
public class FruitResource {

    @Inject
    EntityManager entityManager;

    @GET
    @Path("fruits")
    public Fruit[] getFruits() {
        return entityManager.createNamedQuery("Fruits.findAll", Fruit.class)
                .getResultList().toArray(new Fruit[0]);
    }

}

Para resolver o tenant a partir das requisições recebidas e mapeá-lo para uma configuração específica de tenant, você precisa criar uma implementação para a interface io.quarkus.hibernate.orm.runtime.tenant.TenantResolver

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkus.hibernate.orm.runtime.tenant.TenantResolver;
import io.vertx.ext.web.RoutingContext;

@PersistenceUnitExtension (1)
@RequestScoped (2)
public class CustomTenantResolver implements TenantResolver {

    @Inject
    RoutingContext context;

    @Override
    public String getDefaultTenantId() {
        return "base";
    }

    @Override
    public String resolveTenantId() {
        String path = context.request().path();
        String[] parts = path.split("/");

        if (parts.length == 0) {
            // resolve to default tenant config
            return getDefaultTenantId();
        }

        return parts[1];
    }

}

1	Anote a implementação do TenantResolver com o qualificador `@PersistenceUnitExtension` para informar ao Quarkus que ele deve ser usado na unidade de persistência padrão. Para unidades de persistência nomeadas, use `@PersistenceUnitExtension("nameOfYourPU")` .
2	O bean é feito `@RequestScoped`, pois a resolução do tenant depende da requisição recebida.

Na implementação acima, os tenants são resolvidos a partir do caminho da requisição, de forma que, caso nenhum tenant possa ser inferido, o identificador de tenant padrão é retornado.

Você também usar o OIDC multitenancy e os IDs de locatário do OIDC e do Hibernate ORM forem os mesmos, poderá obter o ID de locatário do OIDC em um atributo RoutingContext, como no exemplo abaixo:

import io.quarkus.hibernate.orm.runtime.tenant.TenantResolver;
import io.quarkus.oidc.runtime.OidcUtils;
import io.vertx.ext.web.RoutingContext;

@PersistenceUnitExtension
@RequestScoped
public class CustomTenantResolver implements TenantResolver {

    @Inject
    RoutingContext context; (1)
    ...
    @Override
    public String resolveTenantId() {
        // OIDC has saved the tenant id as the RoutingContext attribute:
        return context.get(OidcUtils.TENANT_ID_ATTRIBUTE);
    }
}

1 Se o TenantResolver do Hibernate também resolver tenants quando não há uma requisição HTTP ativa, por exemplo ao consultar o banco de dados a partir de um scheduler, o bean CDI RoutingContext não estará disponível. Nesse caso, injete o bean CDI io.quarkus.vertx.http.runtime.CurrentVertxRequest e obtenha o RoutingContext a partir dele.

Configurando a aplicação

Em geral, não é possível utilizar o recurso de geração de banco de dados do Hibernate ORM em conjunto com uma configuração de multitenancy. Portanto, você deve desabilitá-lo e garantir que as tabelas sejam criadas por schema. A configuração a seguir utilizará a extensão Flyway para atingir esse objetivo.

Abordagem SCHEMA

A mesma fonte de dados será usada para todos os locatários e um esquema deve ser criado para cada locatário dentro dessa fonte de dados.

Some databases like MariaDB/MySQL do not support database schemas. In these cases you have to use the database approach.

quarkus.hibernate-orm.database.generation=none (1)

quarkus.hibernate-orm.multitenant=SCHEMA (2)

quarkus.datasource.db-kind=postgresql (3)
quarkus.datasource.username=quarkus_test
quarkus.datasource.password=quarkus_test
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/quarkus_test

quarkus.flyway.schemas=base,mycompany (4)
quarkus.flyway.locations=classpath:schema
quarkus.flyway.migrate-at-start=true

1	Desative a geração de esquemas, pois ela não é compatível com o Hibernate ORM para multitenancy de esquemas. Em vez disso, usaremos o Flyway, veja mais abaixo.
2	Habilitar o multitenancy do esquema. Usamos a fonte de dados padrão aqui, mas poderíamos usar uma fonte de dados nomeada, se quiséssemos, seguindo aqui instruções.
3	Configure a fonte de dados.
4	Configure o Flyway para a inicialização do banco de dados, pois a geração de esquemas pelo Hibernate ORM não é suportada nesse caso.

Aqui está um exemplo do Flyway SQL ( V1.0.0__create_fruits.sql ) a ser criado na pasta configurada src/main/resources/schema.

CREATE SEQUENCE base.known_fruits_id_seq;
SELECT setval('base."known_fruits_id_seq"', 3);
CREATE TABLE base.known_fruits
(
  id   INT,
  name VARCHAR(40)
);
INSERT INTO base.known_fruits(id, name) VALUES (1, 'Cherry');
INSERT INTO base.known_fruits(id, name) VALUES (2, 'Apple');
INSERT INTO base.known_fruits(id, name) VALUES (3, 'Banana');

CREATE SEQUENCE mycompany.known_fruits_id_seq;
SELECT setval('mycompany."known_fruits_id_seq"', 3);
CREATE TABLE mycompany.known_fruits
(
  id   INT,
  name VARCHAR(40)
);
INSERT INTO mycompany.known_fruits(id, name) VALUES (1, 'Avocado');
INSERT INTO mycompany.known_fruits(id, name) VALUES (2, 'Apricots');
INSERT INTO mycompany.known_fruits(id, name) VALUES (3, 'Blackberries');

Abordagem de banco de dados

Para cada tenant, você precisa criar uma fonte de dados nomeada com o mesmo identificador que é retornado pelo TenantResolver.

Com essa abordagem, todos os datasources utilizados pela mesma unidade de persistência são assumidos como apontando para um banco de dados do mesmo fornecedor (mesmo db-kind) e versão.

As incompatibilidades não serão detectadas e podem resultar em um comportamento imprevisível.

quarkus.hibernate-orm.database.generation=none (1)

quarkus.hibernate-orm.multitenant=DATABASE (2)
quarkus.hibernate-orm.datasource=base (3)

# Default tenant 'base'
quarkus.datasource.base.db-kind=postgresql (4)
quarkus.datasource.base.username=quarkus_test
quarkus.datasource.base.password=quarkus_test
%prod.quarkus.datasource.base.jdbc.url=jdbc:postgresql://localhost:5432/quarkus_test
quarkus.flyway.base.locations=classpath:database/base (5)
quarkus.flyway.base.migrate-at-start=true

# Tenant 'mycompany'
quarkus.datasource.mycompany.db-kind=postgresql (6)
quarkus.datasource.mycompany.username=mycompany
quarkus.datasource.mycompany.password=mycompany
%prod.quarkus.datasource.mycompany.jdbc.url=jdbc:postgresql://localhost:5433/mycompany
quarkus.flyway.mycompany.locations=classpath:database/mycompany (7)
quarkus.flyway.mycompany.migrate-at-start=true

1	Desative a geração de esquemas, pois ela não é compatível com o Hibernate ORM para multitenancy de banco de dados. Em vez disso, usaremos o Flyway, veja mais abaixo.
2	Habilite o multitenancy do banco de dados.
3	Selecione uma fonte de dados para a unidade de persistência. Isso serve apenas para permitir que o Quarkus determine o dialeto ORM do Hibernate a ser usado, consulte essa seção para obter detalhes.
4	Configure a fonte de dados para um tenant, `base` .
5	Configure o Flyway para a inicialização do banco de dados para o locatário `base`, porque a geração de esquema pelo Hibernate ORM não é suportada nesse caso.
6	Configure o datasource para outro tenant. Poderia haver mais tenants, mas aqui vamos nos limitar a dois.
7	Configure o Flyway para a inicialização do banco de dados para o locatário `mycompany`, porque a geração de esquema pelo Hibernate ORM não é suportada nesse caso.

A seguir, exemplos dos arquivos SQL do Flyway a serem criados na pasta configurada src/main/resources/database.

Esquema para o tenant base ( src/main/resources/database/base/V1.0.0__create_fruits.sql ):

CREATE SEQUENCE known_fruits_id_seq;
SELECT setval('known_fruits_id_seq', 3);
CREATE TABLE known_fruits
(
  id   INT,
  name VARCHAR(40)
);
INSERT INTO known_fruits(id, name) VALUES (1, 'Cherry');
INSERT INTO known_fruits(id, name) VALUES (2, 'Apple');
INSERT INTO known_fruits(id, name) VALUES (3, 'Banana');

Esquema para o tenant mycompany ( src/main/resources/database/mycompany/V1.0.0__create_fruits.sql ):

CREATE SEQUENCE known_fruits_id_seq;
SELECT setval('known_fruits_id_seq', 3);
CREATE TABLE known_fruits
(
  id   INT,
  name VARCHAR(40)
);
INSERT INTO known_fruits(id, name) VALUES (1, 'Avocado');
INSERT INTO known_fruits(id, name) VALUES (2, 'Apricots');
INSERT INTO known_fruits(id, name) VALUES (3, 'Blackberries');

Abordagem DISCRIMINADORA

A fonte de dados padrão será usada para todos os tenants. Todas as entidades que definirem um campo anotado com @TenantId terão esse campo preenchido automaticamente e serão filtradas automaticamente nas consultas.

quarkus.hibernate-orm.multitenant=DISCRIMINATOR (1)

quarkus.datasource.db-kind=postgresql (2)
quarkus.datasource.username=quarkus_test
quarkus.datasource.password=quarkus_test
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/quarkus_test

1	Ativar o multi-tenancy do discriminador.
2	Configure a fonte de dados.

Resolução programática de conexões de tenants

Se precisar de uma configuração mais dinâmica para os diferentes locatários que deseja suportar e não quiser ter várias entradas no arquivo de configuração, poderá usar a interface io.quarkus.hibernate.orm.runtime.tenant.TenantConnectionResolver para implementar sua própria lógica para recuperar uma conexão. Criar um bean com escopo de aplicativo que implemente essa interface e anotá-lo com @PersistenceUnitExtension (ou @PersistenceUnitExtension("nameOfYourPU") para uma unidade de persistência nomeada) substituirá a implementação padrão atual do Quarkus, io.quarkus.hibernate.orm.runtime.tenant.DataSourceTenantConnectionResolver. Seu resolvedor de conexão personalizado permitiria, por exemplo, ler as informações do locatário de um banco de dados e criar uma conexão por locatário em tempo de execução com base nelas.

Interceptadores

Você pode atribuir um org.hibernate.Interceptor ao seu SessionFactory simplesmente definindo um bean CDI com o qualificador apropriado:

@PersistenceUnitExtension (1)
public static class MyInterceptor extends EmptyInterceptor { (2)
    @Override
    public boolean onLoad(Object entity, Serializable id, Object[] state, (3)
            String[] propertyNames, Type[] types) {
        // ...
        return false;
    }
}

1	Anote a implementação do interceptador com o qualificador `@PersistenceUnitExtension` para informar ao Quarkus que ele deve ser usado na unidade de persistência padrão. Para unidades de persistência nomeadas, use `@PersistenceUnitExtension("nameOfYourPU")`
2	Either extend `org.hibernate.EmptyInterceptor` or implement `org.hibernate.Interceptor` directly.
3	Implement methods as necessary.

Por padrão, os beans de interceptador anotados com @PersistenceUnitExtension são escopo da aplicação, o que significa que somente uma instância de interceptador será criada por aplicação e reutilizada em todos os gerenciadores de entidades. Por esse motivo, a implementação do interceptador deve ser thread-safe.

Para criar uma instância de interceptador por gerente de entidade, anote seu bean com @Dependent. Nesse caso, a implementação do interceptador não precisa ser thread-safe.

Devido a uma limitação do próprio Hibernate ORM, os métodos @PreDestroy em interceptores com escopo @Dependent nunca serão chamados.

Inspetores de declaração

Você pode atribuir um org.hibernate.engine.jdbc.spi.StatementInspector ao seu SessionFactory simplesmente definindo um bean CDI com o qualificador apropriado:

@PersistenceUnitExtension (1)
public class MyStatementInspector implements StatementInspector { (2)
    @Override
    public String inspect(String sql) {
        // ...
        return sql;
    }
}

1	Anote a implementação do inspetor de instruções com o qualificador `@PersistenceUnitExtension` para informar ao Quarkus que ele deve ser usado na unidade de persistência padrão. Para unidades de persistência nomeadas, use `@PersistenceUnitExtension("nameOfYourPU")`
2	Implementar `org.hibernate.engine.jdbc.spi.StatementInspector` .

Personalização da serialização/deserialização JSON/XML

Por padrão, o Quarkus tentará configurar automaticamente os mapeadores de formato, dependendo das extensões disponíveis. O ObjectMapper (ou Jsonb ) configurado globalmente será usado para operações de serialização/desserialização quando o Jackson (ou JSON-B) estiver disponível. Jackson terá precedência se Jackson e JSON-B estiverem disponíveis ao mesmo tempo.

A serialização/desserialização de JSON e XML no Hibernate ORM pode ser personalizada com a implementação de um org.hibernate.type.format.FormatMapper e a anotação da implementação com os qualificadores apropriados:

import io.quarkus.hibernate.orm.JsonFormat;
import org.hibernate.type.format.FormatMapper;

@JsonFormat (1)
@PersistenceUnitExtension (2)
public class MyJsonFormatMapper implements FormatMapper { (3)
    @Override
    public <T> T fromString(CharSequence charSequence, JavaType<T> javaType, WrapperOptions wrapperOptions) {
        // ...
    }

    @Override
    public <T> String toString(T value, JavaType<T> javaType, WrapperOptions wrapperOptions) {
       // ...
    }
}

Anote a implementação do mapeador de formato com o qualificador @JsonFormat para informar ao Quarkus que esse mapeador é específico para serialização/desserialização de JSON.

Certifique-se de que a anotação @io.quarkus.hibernate.orm.JsonFormat específica do Quarkus seja usada e não a da Jackson.

Anote a implementação do mapeador de formato com o qualificador @PersistenceUnitExtension para informar ao Quarkus que ele deve ser usado na unidade de persistência padrão.

Para unidades de persistência nomeadas, use @PersistenceUnitExtension("nameOfYourPU")

3 Implementar org.hibernate.type.format.FormatMapper .

No caso de um mapeador de formato XML personalizado, um qualificador CDI diferente deve ser aplicado:

import io.quarkus.hibernate.orm.XmlFormat;
import org.hibernate.type.format.FormatMapper;

@XmlFormat (1)
@PersistenceUnitExtension (2)
public class MyJsonFormatMapper implements FormatMapper { (3)
    @Override
    public <T> T fromString(CharSequence charSequence, JavaType<T> javaType, WrapperOptions wrapperOptions) {
        // ...
    }

    @Override
    public <T> String toString(T value, JavaType<T> javaType, WrapperOptions wrapperOptions) {
       // ...
    }
}

1	Anote a implementação do mapeador de formato com o qualificador `@XmlFormat` para informar ao Quarkus que esse mapeador é específico para serialização/desserialização de XML.
2	Anote a implementação do mapeador de formato com o qualificador `@PersistenceUnitExtension` para informar ao Quarkus que ele deve ser usado na unidade de persistência padrão. Para unidades de persistência nomeadas, use `@PersistenceUnitExtension("nameOfYourPU")`
3	Implementar `org.hibernate.type.format.FormatMapper` .

Os mapeadores de formato devem ter os qualificadores de CDI @PersistenceUnitExtension e @JsonFormat ou @XmlFormat aplicados.

Ter vários mapeadores de formato JSON (ou XML) registrados para a mesma unidade de persistência resultará em uma exceção, devido à ambiguidade.

Solução
Configurando e definido o Hibernate ORM
Configurando o Hibernate ORM com um persistence.xml
Mapeamento XML
Definição de entidades em projetos externos ou jars
Hibernate ORM no modo de desenvolvimento
Hibernate ORM em modo de produção
Transacionando automaticamente para o Flyway para gerenciar schemas
Armazenamento em cache
Hibernate Envers
Métricas
Limitações e outras informações importantes
Simplificando o Hibernate ORM com o Panache
Configure sua fonte de dados
Multitenancy
Interceptadores
Inspetores de declaração
Personalização da serialização/deserialização JSON/XML

Usando Hibernate ORM e Jakarta Persistence

Solução

Configurando e definido o Hibernate ORM

Dialeto

Bancos de dados suportados

Outros bancos de dados

Banco de dados variável

Propriedades de configuração do Hibernate ORM

Múltiplas unidades de persistência

Configuração de várias unidades de persistência

Anexar classes de modelo a unidades de persistência

Integração com CDI

Ativar/desativar unidades de persistência

Configurando o Hibernate ORM com um persistence.xml

Mapeamento XML

Definição de entidades em projetos externos ou jars

Hibernate ORM no modo de desenvolvimento

Hibernate ORM em modo de produção

Transacionando automaticamente para o Flyway para gerenciar schemas

Armazenamento em cache

Armazenamento em cache de entidades

Armazenamento em cache de coleções e relações

Cache de queries

Ajuste das regiões de cache

Limitações do cache

Hibernate Envers

Métricas

Limitações e outras informações importantes

Enhancement automático em tempo de build

Integração automática

Limitações

Outras diferenças notáveis

Simplificando o Hibernate ORM com o Panache

Configure sua fonte de dados

Multitenancy

Escrevendo o aplicativo

Configurando a aplicação

Abordagem SCHEMA

Abordagem de banco de dados

Abordagem DISCRIMINADORA

Resolução programática de conexões de tenants

Interceptadores

Inspetores de declaração

Personalização da serialização/deserialização JSON/XML

Related content

On the same extensions

On the same topics

Configurando o Hibernate ORM com um `persistence.xml`