Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-11206 - Document all configurations that are not present in AvailableSettings

This commit is contained in:
Vlad Mihalcea 2016-11-04 12:25:46 +02:00
parent b828db2261
commit 66e1ee3851
1 changed files with 176 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

249
documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc
View File

@ -26,18 +26,18 @@ strategy Class name::
|Property |Example |Purpose
|`hibernate.dialect` | `org.hibernate.dialect.
PostgreSQL94Dialect` |
The classname of a Hibernate `org.hibernate.dialect.Dialect` from which Hibernate can generate SQL optimized for a particular relational database.
The classname of a Hibernate https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/dialect/Dialect.html[`Dialect`] from which Hibernate can generate SQL optimized for a particular relational database.
In most cases Hibernate can choose the correct `org.hibernate.dialect.Dialect` implementation based on the JDBC metadata returned by the JDBC driver.
In most cases Hibernate can choose the correct https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/dialect/Dialect.html[`Dialect`] implementation based on the JDBC metadata returned by the JDBC driver.
|`hibernate.current_session_context_class` |`jta`, `thread`, `managed`, or a custom class implementing `org.hibernate.context.spi.
CurrentSessionContext` |
Supply a custom strategy for the scoping of the _current_ `Session`.
The definition of what exactly _current_ means is controlled by the `org.hibernate.context.spi.CurrentSessionContext` implementation in use.
The definition of what exactly _current_ means is controlled by the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/context/spi/CurrentSessionContext.html[`CurrentSessionContext`] implementation in use.
Note that for backwards compatibility, if a `org.hibernate.context.spi.CurrentSessionContext` is not configured but JTA is configured this will default to the `org.hibernate.context.internal.JTASessionContext`.
Note that for backwards compatibility, if a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/context/spi/CurrentSessionContext.html[`CurrentSessionContext`] is not configured but JTA is configured this will default to the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/context/internal/JTASessionContext.html[`JTASessionContext`].
|===================================================================================================================================================================================================================================================================
@ -54,7 +54,6 @@ Note that for backwards compatibility, if a `org.hibernate.context.spi.CurrentSe
|`hibernate.connection.isolation` | `REPEATABLE_READ` or
`Connection.TRANSACTION_REPEATABLE_READ` | Names the JDBC connection transaction isolation level.
|`hibernate.connection.autocommit` | `true` or `false` (default value) | Names the JDBC connection autocommit mode.
|`hibernate.connection.pool_size` | 20 | Maximum number of connections for the built-in Hibernate connection pool.
|`hibernate.connection.datasource` | |
Either a `javax.sql.DataSource` instance or a JNDI name under which to locate the `DataSource`.
@ -65,7 +64,7 @@ For JNDI names, ses also `hibernate.jndi.class`, `hibernate.jndi.url`, `hibernat
|`hibernate.connection.provider_class` | `org.hibernate.hikaricp.internal.
HikariCPConnectionProvider` a|
Names the `org.hibernate.engine.jdbc.connections.spi.ConnectionProvider` to use for obtaining JDBC connections.
Names the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.html[`ConnectionProvider`] to use for obtaining JDBC connections.
Can reference:
@ -95,6 +94,11 @@ Specifies how Hibernate should release JDBC connections. The possible values are
Should generally only configure this or `hibernate.connection.acquisition_mode`, not both.
3+|Hibernate internal connection pool options
|`hibernate.connection.initial_pool_size` | 1 (default value) | Minimum number of connections for the built-in Hibernate connection pool.
|`hibernate.connection.pool_size` | 20 (default value) | Maximum number of connections for the built-in Hibernate connection pool.
|`hibernate.connection.pool_validation_interval` | 30 (default value) | The number of seconds between two consecutive pool validations. During validation, the pool size can increase or decreases based on the connection acquisition request count.
|===================================================================================================================================================================================================================================
[[configurations-c3p0]]
@ -119,21 +123,20 @@ Should generally only configure this or `hibernate.connection.acquisition_mode`,
|===================================================================================================================================================================================================================================
|Property |Example |Purpose
3+|Table qualifying options
|`hibernate.default_schema` |A schema name |Qualify unqualified table names with the given schema or tablespace in generated SQL.
|`hibernate.default_catalog` |A catalog name |Qualifies unqualified table names with the given catalog in generated SQL.
A setting to control whether to `org.hibernate.engine.internal.StatisticalLoggingSessionEventListener` is enabled on all `Sessions` (unless explicitly disabled for a given `Session`).
The default value of this setting is determined by the value for `hibernate.generate_statistics`, meaning that if collection of statistics is enabled logging of Session metrics is enabled by default too.
|`hibernate.default_schema` |A schema name |Qualify unqualified table names with the given schema or tablespace in generated SQL.
|`hibernate.schema_name_resolver` |The fully qualified name of an https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/jdbc/env/spi/SchemaNameResolver.html[`org.hibernate.engine.jdbc.env.spi.SchemaNameResolver`] implementation class |
By default, Hibernate uses the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/dialect/Dialect.html#getSchemaNameResolver--[`org.hibernate.dialect.Dialect#getSchemaNameResolver`] You can customize how the schema name is resolved by providing a custom implementation of the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/jdbc/env/spi/SchemaNameResolver.html[`SchemaNameResolver`] interface.
3+|Identifier options
|`hibernate.id.new_generator_mappings` |`true` (default value) or `false` |
Setting which indicates whether or not the new `org.hibernate.id.IdentifierGenerator` are used for `AUTO`, `TABLE` and `SEQUENCE`.
Setting which indicates whether or not the new https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/id/IdentifierGenerator.html[`IdentifierGenerator`] are used for `AUTO`, `TABLE` and `SEQUENCE`.
Existing applications may want to disable this (set it `false`) for upgrade compatibility from 3.x and 4.x to 5.x.
|`hibernate.use_identifier_rollback` |`true` or `false` (default value) |If true, generated identifier properties are reset to default values when objects are deleted.
|`hibernate.id.optimizer.pooled.preferred` |`none`, `hilo`, `legacy-hilo`, `pooled` (default value), `pooled-lo`, `pooled-lotl` or a fully-qualified name of the `org.hibernate.id.enhanced.Optimizer` implementation |
|`hibernate.id.optimizer.pooled.preferred` |`none`, `hilo`, `legacy-hilo`, `pooled` (default value), `pooled-lo`, `pooled-lotl` or a fully-qualified name of the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/id/enhanced/Optimizer.html[`Optimizer`] implementation |
When a generator specified an increment-size and an optimizer was not explicitly specified, which of the _pooled_ optimizers should be preferred?
@ -172,24 +175,24 @@ See Hibernate Jira issue https://hibernate.atlassian.net/browse/HHH-6911[HHH-691
3+|Naming strategies
|`hibernate.implicit_naming_strategy` |`default` (default value), `jpa`, `legacy-jpa`, `legacy-hbm`, `component-path` a|
Used to specify the `org.hibernate.boot.model.naming.ImplicitNamingStrategy` class to use.
Used to specify the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/model/naming/ImplicitNamingStrategy.html[`ImplicitNamingStrategy`] class to use.
The following short names are defined for this setting:
`default`:: Uses the `org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl`
`jpa`:: Uses the `org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl`
`legacy-jpa`:: Uses the `org.hibernate.boot.model.naming.ImplicitNamingStrategyLegacyJpaImpl`
`legacy-hbm`:: Uses the `org.hibernate.boot.model.naming.ImplicitNamingStrategyLegacyHbmImpl`
`component-path`:: Uses the `org.hibernate.boot.model.naming.ImplicitNamingStrategyComponentPathImpl`
`default`:: Uses the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/model/naming/ImplicitNamingStrategyJpaCompliantImpl.html[`ImplicitNamingStrategyJpaCompliantImpl`]
`jpa`:: Uses the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/model/naming/ImplicitNamingStrategyJpaCompliantImpl.html[`ImplicitNamingStrategyJpaCompliantImpl`]
`legacy-jpa`:: Uses the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/model/naming/ImplicitNamingStrategyLegacyJpaImpl.html[`ImplicitNamingStrategyLegacyJpaImpl`]
`legacy-hbm`:: Uses the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/model/naming/ImplicitNamingStrategyLegacyHbmImpl.html[`ImplicitNamingStrategyLegacyHbmImpl`]
`component-path`:: Uses the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/model/naming/ImplicitNamingStrategyComponentPathImpl.html[`ImplicitNamingStrategyComponentPathImpl`]
If this property happens to be empty, the fallback is to use `default` strategy.
|`hibernate.physical_naming_strategy` | `org.hibernate.boot.model.naming.
PhysicalNamingStrategyStandardImpl` (default value) | Used to specify the `org.hibernate.boot.model.naming.PhysicalNamingStrategy` class to use.
PhysicalNamingStrategyStandardImpl` (default value) | Used to specify the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/model/naming/PhysicalNamingStrategy.html[`PhysicalNamingStrategy`] class to use.
3+|Metadata scanning options
|`hibernate.archive.scanner` | a|
Pass an implementation of `org.hibernate.boot.archive.scan.spi.Scanner`.
By default, `org.hibernate.boot.archive.scan.internal.StandardScanner` is used.
Pass an implementation of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/archive/scan/spi/Scanner.html[`Scanner`].
By default, https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/archive/scan/internal/StandardScanner.html[`StandardScanner`] is used.
Accepts either:
@ -199,7 +202,7 @@ Accepts either:
|`hibernate.archive.interpreter` | a|
Pass `org.hibernate.boot.archive.spi.ArchiveDescriptorFactory` to use in the scanning process.
Pass https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/archive/spi/ArchiveDescriptorFactory.html[`ArchiveDescriptorFactory`] to use in the scanning process.
Accepts either:
@ -207,7 +210,7 @@ Accepts either:
* a reference to a Class that implements `ArchiveDescriptorFactory`
* a fully qualified name of a Class that implements `ArchiveDescriptorFactory`
See information on `org.hibernate.boot.archive.scan.spi.Scanner` about expected constructor forms.
See information on https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/archive/scan/spi/Scanner.html[`Scanner`] about expected constructor forms.
|`hibernate.archive.autodetection` | `hbm,class` (default value) a|
@ -226,7 +229,7 @@ Therefore, when setting `exclude-unlisted-classes` to true, only the classes tha
|`hibernate.mapping.precedence` | `hbm,class` (default value) |
Used to specify the order in which metadata sources should be processed.
Value is a delimited-list whose elements are defined by `org.hibernate.cfg.MetadataSourceType`.
Value is a delimited-list whose elements are defined by https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/cfg/MetadataSourceType.html[`MetadataSourceType`].
Default is `hbm,class"`, therefore `hbm.xml` files are processed first, followed by annotations (combined with `orm.xml` mappings).
@ -236,6 +239,7 @@ When using JPA, the XML mapping overrides a conflicting annotation mapping that
|`hibernate.use_nationalized_character_data` |`true` or `false` (default value) |Enable nationalized character support on all string / clob based attribute ( string, char, clob, text etc ).
|`hibernate.jdbc.lob.non_contextual_creation` |`true` or `false` (default value) |Should we not use contextual LOB creation (aka based on `java.sql.Connection#createBlob()` et al)? The default value for HANA, H2, and PostgreSQL is `true`.
|`hibernate.jdbc.time_zone` | A `java.util.TimeZone`, a `java.time.ZoneId` or a `String` representation of a `ZoneId` |Unless specified, the JDBC Driver uses the default JVM time zone. If a different time zone is configured via this setting, the JDBC https://docs.oracle.com/javase/8/docs/api/java/sql/PreparedStatement.html#setTimestamp-int-java.sql.Timestamp-java.util.Calendar-[PreparedStatement#setTimestamp] is going to use a `Calendar` instance according to the specified time zone.
|`hibernate.dialect.oracle.prefer_long_raw` | `true` or `false` (default value) |This setting applies to Oracle Dialect only, and it specifies whether `byte[]` or `Byte[]` arrays should be mapped to the deprecated `LONG RAW` (when this configuration property value is `true`) or to a `BLOB` column type (when this configuration property value is `false`).
3+|Bean Validation options
|`javax.persistence.validation.factory` |`javax.validation.ValidationFactory` implementation | Specify the `javax.validation.ValidationFactory` implementation to use for Bean Validation.
@ -244,6 +248,13 @@ When using JPA, the XML mapping overrides a conflicting annotation mapping that
Enable nullability checking. Raises an exception if a property marked as not-null is null.
Default to `false` if Bean Validation is present in the classpath and Hibernate Annotations is used, `true` otherwise.
|`hibernate.validator.apply_to_ddl` |`true` (default value) or `false` |
Bean Validation constraints will be applied in DDL if the automatic schema generation is enabled.
In other words, the database schema will reflect the Bean Validation constraints.
To disable constraint propagation to DDL, set up `hibernate.validator.apply_to_ddl` to `false` in the configuration file.
Such a need is very uncommon and not recommended.
3+|Misc options
|`hibernate.create_empty_composites.enabled` |`true` or `false` (default value) | Enable instantiation of composite/embeddable objects when all of its attribute values are `null`. The default (and historical) behavior is that a `null` reference will be used to represent the composite when all of its attributes are `null`.
@ -260,8 +271,8 @@ Default to `false` if Bean Validation is present in the classpath and Hibernate
|`hibernate.enhancer.enableDirtyTracking`| `true` or `false` (default value) | Enable dirty tracking feature in runtime bytecode enhancement.
|`hibernate.enhancer.enableLazyInitialization`| `true` or `false` (default value) | Enable lazy loading feature in runtime bytecode enhancement. This way, even basic types (e.g. `@Basic(fetch = FetchType.LAZY`)) can be fetched lazily.
|`hibernate.enhancer.enableAssociationManagement`| `true` or `false` (default value) | Enable association management feature in runtime bytecode enhancement which automatically synchronizes a bidirectional association when only one side is changed.
|`hibernate.bytecode.provider` |`javassist` (default value) | The `org.hibernate.bytecode.spi.BytecodeProvider` built-in implementation flavor. Currently, only `javassist` is supported.
|`hibernate.bytecode.use_reflection_optimizer`| `true` or `false` (default value) | Should we use reflection optimization? The reflection optimizer implements the `org.hibernate.bytecode.spi.ReflectionOptimizer` interface and improves entity instantiation and property getter/setter calls.
|`hibernate.bytecode.provider` |`javassist` (default value) | The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/bytecode/spi/BytecodeProvider.html[`BytecodeProvider`] built-in implementation flavor. Currently, only `javassist` is supported.
|`hibernate.bytecode.use_reflection_optimizer`| `true` or `false` (default value) | Should we use reflection optimization? The reflection optimizer implements the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/bytecode/spi/ReflectionOptimizer.html[`ReflectionOptimizer`] interface and improves entity instantiation and property getter/setter calls.
|===================================================================================================================================================================================================================================
[[configurations-query]]
@ -274,13 +285,13 @@ Default to `false` if Bean Validation is present in the classpath and Hibernate
The maximum number of entries including:
* `org.hibernate.engine.query.spi.HQLQueryPlan`
* `org.hibernate.engine.query.spi.FilterQueryPlan`
* `org.hibernate.engine.query.spi.NativeSQLQueryPlan`
* https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/query/spi/HQLQueryPlan.html[`HQLQueryPlan`]
* https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/query/spi/FilterQueryPlan.html[`FilterQueryPlan`]
* https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/query/spi/NativeSQLQueryPlan.html[`NativeSQLQueryPlan`]
maintained by `org.hibernate.engine.query.spi.QueryPlanCache`.
maintained by https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/query/spi/QueryPlanCache.html[`QueryPlanCache`].
|`hibernate.query.plan_parameter_metadata_max_size` | `128` (default value) | The maximum number of strong references associated with `ParameterMetadata` maintained by `org.hibernate.engine.query.spi.QueryPlanCache`.
|`hibernate.query.plan_parameter_metadata_max_size` | `128` (default value) | The maximum number of strong references associated with `ParameterMetadata` maintained by https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/query/spi/QueryPlanCache.html[`QueryPlanCache`].
|`hibernate.order_by.default_null_ordering` |`none`, `first` or `last` |Defines precedence of null values in `ORDER BY` clause. Defaults to `none` which varies between RDBMS implementation.
|`hibernate.discriminator.force_in_select` |`true` or `false` (default value) | For entities which do not explicitly say, should we force discriminators into SQL selects?
|`hibernate.query.substitutions` | `true=1,false=0` |A comma-separated list of token substitutions to use when translating a Hibernate query to SQL.
@ -293,12 +304,10 @@ ClassicQueryTranslatorFactory` |Chooses the HQL parser implementation.
Should we strictly adhere to JPA Query Language (JPQL) syntax, or more broadly support all of Hibernate's superset (HQL)?
Setting this to `true` may cause valid HQL to throw an exception because it violates the JPQL subset.
|`hibernate.query.startup_check` | `true` (default value) or `false` |Should named queries be checked during startup?
|`hibernate.hql.bulk_id_strategy` | A fully-qualified class name, an instance, or a `Class` object reference |Provide a custom `org.hibernate.hql.spi.id.MultiTableBulkIdStrategy` implementation for handling multi-table bulk HQL operations.
|`hibernate.proc.param_null_passing` | `true` or `false` (default value) |
Global setting for whether `null` parameter bindings should be passed to database procedure/function calls as part of `org.hibernate.procedure.ProcedureCall` handling.
Global setting for whether `null` parameter bindings should be passed to database procedure/function calls as part of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/procedure/ProcedureCall.html[`ProcedureCall`] handling.
Implicitly Hibernate will not pass the `null`, the intention being to allow any default argument values to be applied.
This defines a global setting, which can then be controlled per parameter via `org.hibernate.procedure.ParameterRegistration#enablePassingNulls(boolean)`
@ -308,7 +317,7 @@ Values are `true` (pass the NULLs) or `false` (do not pass the NULLs).
|`hibernate.jdbc.log.warnings` | `true` or `false` |Enable fetching JDBC statement warning for logging. Default value is given by `org.hibernate.dialect.Dialect#isJdbcLogWarningsEnabledByDefault()`.
|`hibernate.session_factory.statement_inspector` | A fully-qualified class name, an instance, or a `Class` object reference a|
Names a `org.hibernate.resource.jdbc.spi.StatementInspector` implementation to be applied to every `Session` created by the current `SessionFactory`.
Names a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/resource/jdbc/spi/StatementInspector.html[`StatementInspector`] implementation to be applied to every `Session` created by the current `SessionFactory`.
Can reference
@ -316,6 +325,24 @@ Can reference
* `StatementInspector` implementation {@link Class} reference
* `StatementInspector` implementation class name (fully-qualified class name)
3+|Multi-table bulk HQL operations
|`hibernate.hql.bulk_id_strategy` | A fully-qualified class name, an instance, or a `Class` object reference |Provide a custom https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/hql/spi/id/MultiTableBulkIdStrategy.html[`org.hibernate.hql.spi.id.MultiTableBulkIdStrategy`] implementation for handling multi-table bulk HQL operations.
|`hibernate.hql.bulk_id_strategy.global_temporary.drop_tables` | `true` or `false` (default value) | For databases that don't support local tables, but just global ones, this configuration property allows you to DROP the global tables used for multi-table bulk HQL operations when the `SessionFactory` or the `EntityManagerFactory` is closed.
|`hibernate.hql.bulk_id_strategy.persistent.drop_tables` | `true` or `false` (default value) |
This configuration property is used by the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/hql/spi/id/persistent/PersistentTableBulkIdStrategy.html[`PersistentTableBulkIdStrategy`], that mimics temporary tables for databases which do not support temporary tables.
It follows a pattern similar to the ANSI SQL definition of global temporary table using a "session id" column to segment rows from the various sessions.
This configuration property allows you to DROP the tables used for multi-table bulk HQL operations when the `SessionFactory` or the `EntityManagerFactory` is closed.
|`hibernate.hql.bulk_id_strategy.persistent.schema` | Database schema name. By default, the `hibernate.default_schema` is used. |
This configuration property is used by the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/hql/spi/id/persistent/PersistentTableBulkIdStrategy.html[`PersistentTableBulkIdStrategy`], that mimics temporary tables for databases which do not support temporary tables.
It follows a pattern similar to the ANSI SQL definition of global temporary table using a "session id" column to segment rows from the various sessions.
This configuration property defines the database schema used for storing the temporary tables used for bulk HQL operations.
|`hibernate.hql.bulk_id_strategy.persistent.catalog` | Database catalog name. By default, the `hibernate.default_catalog` is used. |
This configuration property is used by the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/hql/spi/id/persistent/PersistentTableBulkIdStrategy.html[`PersistentTableBulkIdStrategy`], that mimics temporary tables for databases which do not support temporary tables.
It follows a pattern similar to the ANSI SQL definition of global temporary table using a "session id" column to segment rows from the various sessions.
This configuration property defines the database catalog used for storing the temporary tables used for bulk HQL operations.
|===================================================================================================================================================================================================================================
[[configurations-batch]]
@ -334,11 +361,11 @@ Set this property to `true` if your JDBC driver returns correct row counts from
|`hibernate.batch_fetch_style` |`LEGACY`(default value) |
Names the `org.hibernate.loader.BatchFetchStyle` to use.
Names the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/loader/BatchFetchStyle.html[`BatchFetchStyle`] to use.
Can specify either the `org.hibernate.loader.BatchFetchStyle` name (insensitively), or a `org.hibernate.loader.BatchFetchStyle` instance. `LEGACY}` is the default value.
Can specify either the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/loader/BatchFetchStyle.html[`BatchFetchStyle`] name (insensitively), or a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/loader/BatchFetchStyle.html[`BatchFetchStyle`] instance. `LEGACY}` is the default value.
|`hibernate.jdbc.batch.builder` | The fully qualified name of an `org.hibernate.engine.jdbc.batch.spi.BatchBuilder` implementation class type or an actual object instance | Names the `org.hibernate.engine.jdbc.batch.spi.BatchBuilder` implementation to use.
|`hibernate.jdbc.batch.builder` | The fully qualified name of an https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/jdbc/batch/spi/BatchBuilder.html[`BatchBuilder`] implementation class type or an actual object instance | Names the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/jdbc/batch/spi/BatchBuilder.html[`BatchBuilder`] implementation to use.
|=====================================================================================================================================================================================================================================================================================================================================================================================================
[[configurations-database-fetch]]
@ -375,9 +402,11 @@ In reality, you shouldn't probably enable this setting anyway.
|`hibernate.use_sql_comments` |`true` or `false` (default value) |If true, Hibernate generates comments inside the SQL, for easier debugging.
3+|Statistics settings
|`hibernate.generate_statistics` |`true` or `false` |Causes Hibernate to collect statistics for performance tuning.
|`hibernate.stats.factory` |The fully qualified name of an https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/stat/spi/StatisticsFactory.html[`StatisticsFactory`] implementation or an actual instance
The `StatisticsFactory` allow you to customize how the Hibernate Statistics are being collected.
|`hibernate.session.events.log` |`true` or `false` |
A setting to control whether to `org.hibernate.engine.internal
A setting to control whether the `org.hibernate.engine.internal
.StatisticalLoggingSessionEventListener` is enabled on all `Sessions` (unless explicitly disabled for a given `Session`).
The default value of this setting is determined by the value for `hibernate.generate_statistics`, meaning that if statistics are enabled, then logging of Session metrics is enabled by default too.
@ -393,13 +422,13 @@ The default value of this setting is determined by the value for `hibernate.gene
InfinispanRegionFactory` |The fully-qualified name of the `RegionFactory` implementation class.
|`hibernate.cache.default_cache_concurrency_strategy` | |
Setting used to give the name of the default `org.hibernate.annotations.CacheConcurrencyStrategy` to use when either `@javax.persistence.Cacheable` or
Setting used to give the name of the default https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/CacheConcurrencyStrategy.html[`CacheConcurrencyStrategy`] to use when either `@javax.persistence.Cacheable` or
`@org.hibernate.annotations.Cache`. `@org.hibernate.annotations.Cache` is used to override the global setting.
|`hibernate.cache.use_minimal_puts` |`true` (default value) or `false` |Optimizes second-level cache operation to minimize writes, at the cost of more frequent reads. This is most useful for clustered caches and is enabled by default for clustered cache implementations.
|`hibernate.cache.use_query_cache` |`true` or `false` (default value) |Enables the query cache. You still need to set individual queries to be cachable.
|`hibernate.cache.use_second_level_cache` |`true` (default value) or `false` |Enable/disable the second level cache, which is enabled by default, although the default `RegionFactor` is `NoCachingRegionFactory` (meaning there is no actual caching implementation).
|`hibernate.cache.query_cache_factory` |Fully-qualified classname |A custom `org.hibernate.cache.spi.QueryCacheFactory` interface. The default is the built-in `StandardQueryCacheFactory`.
|`hibernate.cache.query_cache_factory` |Fully-qualified classname |A custom https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/cache/spi/QueryCacheFactory.html[`QueryCacheFactory`] interface. The default is the built-in `StandardQueryCacheFactory`.
|`hibernate.cache.region_prefix` |A string |A prefix for second-level cache region names.
|`hibernate.cache.use_structured_entries` |`true` or `false` (default value) |Forces Hibernate to store data in the second-level cache in a more human-readable format.
|`hibernate.cache.auto_evict_collection_cache` |`true` or `false` (default: false) |Enables the automatic eviction of a bi-directional association's collection cache when an element in the `ManyToOne` collection is added/updated/removed without properly managing the change on the `OneToMany` side.
@ -410,6 +439,19 @@ Setting used to give the name of the default `org.hibernate.annotations.CacheCon
.org.hibernate.ejb.test.Item.distributors` = `read-write, RegionName`/> | Sets the associated collection cache concurrency strategy for the designated region. Caching configuration should follow the following pattern `hibernate.ejb.collectioncache.<fully.qualified.Classname>.<role>` usage[, region] where usage is the cache strategy used and region the cache region name
|==================================================================================================================================================================================================================================================================================================================
[[configurations-infinispan]]
=== Infinispan properties
[width="100%",cols="20%,20%,60%",]
|=====================================================================================================================================================================================================================================================
|Property |Example |Purpose
|`hibernate.cache.infinispan.cfg` | `org/hibernate/cache/infinispan/
builder/infinispan-configs.xml` | Classpath or filesystem resource containing the Infinispan configuration settings.
|`hibernate.cache.infinispan.statistics` | | Property name that controls whether Infinispan statistics are enabled. The property value is expected to be a boolean true or false, and it overrides statistic configuration in base Infinispan configuration, if provided.
|`hibernate.cache.infinispan.use_synchronization` | | Deprecated setting because Infinispan is designed to always register a `Synchronization` for `TRANSACTIONAL` caches.
|`hibernate.cache.infinispan.cachemanager` | There is no default value, the user must specify the property. | Specifies the JNDI name under which the `EmbeddedCacheManager` is bound.
|=====================================================================================================================================================================================================================================================
[[configurations-transactions]]
=== Transactions properties
@ -418,22 +460,21 @@ Setting used to give the name of the default `org.hibernate.annotations.CacheCon
|Property |Example |Purpose
|`hibernate.transaction.jta.platform` |`JBossAS`, `BitronixJtaPlatform` |
Names the `org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform` implementation to use for integrating with JTA systems.
Can reference either a `org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform` instance or the name of the `org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform` implementation class
Names the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/transaction/jta/platform/spi/JtaPlatform.html[`JtaPlatform`] implementation to use for integrating with JTA systems.
Can reference either a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/transaction/jta/platform/spi/JtaPlatform.html[`JtaPlatform`] instance or the name of the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/transaction/jta/platform/spi/JtaPlatform.html[`JtaPlatform`] implementation class
|`hibernate.jta.prefer_user_transaction` |`true` or `false` (default value) |
Should we prefer using the `org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform#retrieveUserTransaction` over using `org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform#retrieveTransactionManager`
|`hibernate.transaction.jta.platform_resolver` | | Names the `org.hibernate.engine.transaction.jta.platform.spi.JtaPlatformResolver` implementation to use.
|`hibernate.transaction.jta.platform_resolver` | | Names the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/transaction/jta/platform/spi/JtaPlatformResolver.html[`JtaPlatformResolver`] implementation to use.
|`hibernate.jta.cacheTransactionManager` | `true` (default value) or `false` | A configuration value key used to indicate that it is safe to cache.
|`hibernate.jta.cacheUserTransaction` | `true` or `false` (default value) | A configuration value key used to indicate that it is safe to cache.
|`hibernate.transaction.flush_before_completion` |`true` or `false` (default value) | Causes the session be flushed during the before completion phase of the transaction. If possible, use built-in and automatic session context management instead.
|`hibernate.transaction.auto_close_session` |`true` or `false` (default value) |Causes the session to be closed during the after completion phase of the transaction. If possible, use built-in and automatic session context management instead.
|`hibernate.transaction.coordinator_class` | a|
Names the implementation of `org.hibernate.resource.transaction.spi.TransactionCoordinatorBuilder` to use for creating
`org.hibernate.resource.transaction.spi.TransactionCoordinator` instances.
Names the implementation of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/resource/transaction/spi/TransactionCoordinatorBuilder.html[`TransactionCoordinatorBuilder`] to use for creating https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/resource/transaction/spi/TransactionCoordinator.html[`TransactionCoordinator`] instances.
Can be
@ -446,14 +487,13 @@ The following short names are defined for this setting:
`jdbc`:: Manages transactions via calls to `java.sql.Connection` (default for non-JPA applications)
`jta`:: Manages transactions via JTA. See <<chapters/bootstrap/Bootstrap.adoc#bootstrap-jpa-compliant,Java EE bootstrapping>>
If a JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate will
If a JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate will
automatically build the proper transaction coordinator based on the transaction type for the persistence unit.
If a non-JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate
If a non-JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate
will use `jdbc` as the default. This default will cause problems if the application actually uses JTA-based transactions.
A non-JPA application that uses JTA-based transactions should explicitly set `hibernate.transaction.coordinator_class=jta`
or provide a custom `org.hibernate.resource.transaction.TransactionCoordinatorBuilder` that builds a
`org.hibernate.resource.transaction.TransactionCoordinator` that properly coordinates with JTA-based transactions.
A non-JPA application that uses JTA-based transactions should explicitly set `hibernate.transaction.coordinator_class=jta`
or provide a custom https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/resource/transaction/TransactionCoordinatorBuilder.html[`TransactionCoordinatorBuilder`] that builds a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/resource/transaction/TransactionCoordinator.html[`TransactionCoordinator`] that properly coordinates with JTA-based transactions.
|`hibernate.jta.track_by_thread` | `true` (default value) or `false` |
@ -461,6 +501,9 @@ A transaction can be rolled back by another thread ("tracking by thread") and no
Examples of this include a JTA transaction timeout handled by a background reaper thread.
The ability to handle this situation requires checking the Thread ID every time Session is called, so enabling this can certainly have a performance impact.
|`hibernate.transaction.factory_class` | | This is a legacy setting that's been deprecated and you should use the `hibernate.transaction.jta.platform` instead.
|===================================================================================================================================================================================================================================
[[configurations-multi-tenancy]]
@ -470,10 +513,10 @@ The ability to handle this situation requires checking the Thread ID every time
|===================================================================================================================================================================================================================================
|Property |Example |Purpose
|`hibernate.multiTenancy` | `NONE` (default value), `SCHEMA`, `DATABASE`, and `DISCRIMINATOR` (not implemented yet) | The multi-tenancy strategy in use.
|`hibernate.multi_tenant_connection_provider` | `true` or `false` (default value) | Names a `org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider` implementation to use. As `MultiTenantConnectionProvider` is also a service, can be configured directly through the `org.hibernate.boot.registry.StandardServiceRegistryBuilder`.
|`hibernate.multi_tenant_connection_provider` | `true` or `false` (default value) | Names a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/jdbc/connections/spi/MultiTenantConnectionProvider.html[`MultiTenantConnectionProvider`] implementation to use. As `MultiTenantConnectionProvider` is also a service, can be configured directly through the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/registry/StandardServiceRegistryBuilder.html[`StandardServiceRegistryBuilder`].
|`hibernate.tenant_identifier_resolver` | a|
Names a `org.hibernate.context.spi.CurrentTenantIdentifierResolver` implementation to resolve the resolve the current tenant identifier so that calling `SessionFactory#openSession()` would get a `Session` that's connected to the right tenant.
Names a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/context/spi/CurrentTenantIdentifierResolver.html[`CurrentTenantIdentifierResolver`] implementation to resolve the resolve the current tenant identifier so that calling `SessionFactory#openSession()` would get a `Session` that's connected to the right tenant.
Can be:
@ -481,6 +524,8 @@ Can be:
* `CurrentTenantIdentifierResolver` implementation `Class` object reference
* `CurrentTenantIdentifierResolver` implementation class name
|`hibernate.multi_tenant.datasource.identifier_for_any` | `true` or `false` (default value) | When the `hibernate.connection.datasource` property value is resolved to a `javax.naming.Context` object, this configuration property defines the JNDI name used to locate the `DataSource` used for fetching the initial `Connection` which is used to access to the database metadata of the underlying database(s) (in situations where we do not have a tenant id, like startup processing).
|===================================================================================================================================================================================================================================
[[configurations-hbmddl]]
@ -492,7 +537,7 @@ Can be:
|`hibernate.hbm2ddl.auto` |`none` (default value), `create-only`, `drop`, `create`, `create-drop`, `validate`, and `update` a|
Setting to perform `SchemaManagementTool` actions automatically as part of the `SessionFactory` lifecycle.
Valid options are defined by the `externalHbm2ddlName` value of the `org.hibernate.tool.schema.Action` enum:
Valid options are defined by the `externalHbm2ddlName` value of the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/Action.html[`Action`] enum:
`none`:: No action will be performed.
`create-only`:: Database creation will be generated.
@ -505,7 +550,7 @@ Valid options are defined by the `externalHbm2ddlName` value of the `org.hiberna
|`javax.persistence.schema-generation.database.action` |`none` (default value), `create-only`, `drop`, `create`, `create-drop`, `validate`, and `update` a|
Setting to perform `SchemaManagementTool` actions automatically as part of the `SessionFactory` lifecycle.
Valid options are defined by the `externalJpaName` value of the `org.hibernate.tool.schema.Action` enum:
Valid options are defined by the `externalJpaName` value of the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/Action.html[`Action`] enum:
`none`:: No action will be performed.
`create`:: Database creation will be generated.
@ -515,7 +560,7 @@ Valid options are defined by the `externalJpaName` value of the `org.hibernate.t
|`javax.persistence.schema-generation.scripts.action` |`none` (default value), `create-only`, `drop`, `create`, `create-drop`, `validate`, and `update` a|
Setting to perform `SchemaManagementTool` actions writing the commands into a DDL script file.
Valid options are defined by the `externalJpaName` value of the `org.hibernate.tool.schema.Action` enum:
Valid options are defined by the `externalJpaName` value of the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/Action.html[`Action`] enum:
`none`:: No action will be performed.
`create`:: Database creation will be generated.
@ -547,7 +592,7 @@ This value is used to help more precisely determine how to perform schema genera
|`javax.persistence.schema-generation.create-source` | a|
Specifies whether schema generation commands for schema creation are to be determine based on object/relational mapping metadata, DDL scripts, or a combination of the two.
See `org.hibernate.tool.schema.SourceType` for valid set of values.
See https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/SourceType.html[`SourceType`] for valid set of values.
If no value is specified, a default is assumed as follows:
@ -557,7 +602,7 @@ If no value is specified, a default is assumed as follows:
|`javax.persistence.schema-generation.drop-source` | a|
Specifies whether schema generation commands for schema dropping are to be determine based on object/relational mapping metadata, DDL scripts, or a combination of the two.
See `org.hibernate.tool.schema.SourceType` for valid set of values.
See https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/SourceType.html[`SourceType`] for valid set of values.
If no value is specified, a default is assumed as follows:
@ -588,13 +633,13 @@ A "SQL load script" is a script that performs some database initialization (INSE
|`hibernate.hbm2ddl.import_files_sql_extractor` | |
Reference to the `org.hibernate.tool.hbm2ddl.ImportSqlCommandExtractor` implementation class to use for parsing source/import files as defined by `javax.persistence.schema-generation.create-script-source`,
Reference to the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/hbm2ddl/ImportSqlCommandExtractor.html[`ImportSqlCommandExtractor`] implementation class to use for parsing source/import files as defined by `javax.persistence.schema-generation.create-script-source`,
`javax.persistence.schema-generation.drop-script-source` or `hibernate.hbm2ddl.import_files`.
Reference may refer to an instance, a Class implementing `ImportSqlCommandExtractor` of the fully-qualified name of the `ImportSqlCommandExtractor` implementation.
If the fully-qualified name is given, the implementation must provide a no-arg constructor.
The default value is `org.hibernate.tool.hbm2ddl.SingleLineSqlCommandExtractor`.
The default value is https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/hbm2ddl/SingleLineSqlCommandExtractor.html[`SingleLineSqlCommandExtractor`].
|`hibernate.hbm2dll.create_namespaces` | `true` or `false` (default value) |Specifies whether to automatically create also the database schema/catalog.
|`javax.persistence.create-database-schemas` | `true` or `false` (default value) |
@ -605,20 +650,20 @@ If this property is not supplied (or is explicitly `false`), the provider should
|`hibernate.hbm2ddl.schema_filter_provider` | |
Used to specify the `org.hibernate.tool.schema.spi.SchemaFilterProvider` to be used by `create`, `drop`, `migrate`, and `validate` operations on the database schema.
Used to specify the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaFilterProvider.html[`SchemaFilterProvider`] to be used by `create`, `drop`, `migrate`, and `validate` operations on the database schema.
`SchemaFilterProvider` provides filters that can be used to limit the scope of these operations to specific namespaces, tables and sequences. All objects are included by default.
|`hibernate.hbm2ddl.jdbc_metadata_extraction_strategy` |`grouped` (default value) or `individually` a|
Setting to choose the strategy used to access the JDBC Metadata.
Valid options are defined by the `strategy` value of the `org.hibernate.tool.schema.JdbcMetadaAccessStrategy` enum:
Valid options are defined by the `strategy` value of the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/JdbcMetadaAccessStrategy.html[`JdbcMetadaAccessStrategy`] enum:
`grouped`:: `org.hibernate.tool.schema.spi.SchemaMigrator` and `org.hibernate.tool.schema.spi.SchemaValidator` execute a single `java.sql.DatabaseMetaData#getTables(String, String, String, String[])` call to retrieve all the database table in order to determine if all the `javax.persistence.Entity` have a corresponding mapped database tables.
`individually`:: `org.hibernate.tool.schema.spi.SchemaMigrator` and `org.hibernate.tool.schema.spi.SchemaValidator` execute one `java.sql.DatabaseMetaData#getTables(String, String, String, String[])` call for each `javax.persistence.Entity` in order to determine if a corresponding database table exists.
`grouped`:: https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaMigrator.html[`SchemaMigrator`] and https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaValidator.html[`SchemaValidator`] execute a single `java.sql.DatabaseMetaData#getTables(String, String, String, String[])` call to retrieve all the database table in order to determine if all the `javax.persistence.Entity` have a corresponding mapped database tables.
`individually`:: https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaMigrator.html[`SchemaMigrator`] and https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaValidator.html[`SchemaValidator`] execute one `java.sql.DatabaseMetaData#getTables(String, String, String, String[])` call for each `javax.persistence.Entity` in order to determine if a corresponding database table exists.
|`hibernate.hbm2ddl.delimiter` | `;` |Identifies the delimiter to use to separate schema management statements in script outputs.
|`hibernate.schema_management_tool` |A schema name |Used to specify the `org.hibernate.tool.schema.spi.SchemaManagementTool` to use for performing schema management. The default is to use `org.hibernate.tool.schema.internal.HibernateSchemaManagementTool`
|`hibernate.schema_management_tool` |A schema name |Used to specify the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/spi/SchemaManagementTool.html[`SchemaManagementTool`] to use for performing schema management. The default is to use https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/schema/internal/HibernateSchemaManagementTool.html[`HibernateSchemaManagementTool`]
|`hibernate.synonyms` |`true` or `false` (default value) |If enabled, allows schema update and validation to support synonyms. Due to the possibility that this would return duplicate tables (especially in Oracle), this is disabled by default.
|`hibernate.hbm2dll.extra_physical_table_types` |`BASE TABLE` |Identifies a comma-separated list of values to specify extra table types, other than the default `TABLE` value, to recognize as defining a physical table by schema update, creation and validation.
|`hibernate.schema_update.unique_constraint_strategy` |`DROP_RECREATE_QUIETLY`, `RECREATE_QUIETLY`, `SKIP` a|
@ -627,7 +672,7 @@ Unique columns and unique keys both use unique constraints in most dialects.
`SchemaUpdate` needs to create these constraints, but DBs support for finding existing constraints is extremely inconsistent.
Further, non-explicitly-named unique constraints use randomly generated characters.
Therefore, the `org.hibernate.tool.hbm2ddl.UniqueConstraintSchemaUpdateStrategy` offers the following options:
Therefore, the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tool/hbm2ddl/UniqueConstraintSchemaUpdateStrategy.html[`UniqueConstraintSchemaUpdateStrategy`] offers the following options:
`DROP_RECREATE_QUIETLY`:: Default option.
Attempt to drop, then (re-)create each unique constraint. Ignore any exceptions being thrown.
@ -646,7 +691,7 @@ Therefore, the `org.hibernate.tool.hbm2ddl.UniqueConstraintSchemaUpdateStrategy`
[width="100%",cols="20%,20%,60%",]
|===================================================================================================================================================================================================================================
|Property |Example |Purpose
|`hibernate.jdbc.sql_exception_converter` | Fully-qualified name of class implementing `SQLExceptionConverter` |The `org.hibernate.exception.spi.SQLExceptionConverter` to use for converting `SQLExceptions` to Hibernate's `JDBCException` hierarchy. The default is to use the configured `org.hibernate.dialect.Dialect`'s preferred `SQLExceptionConverter`.
|`hibernate.jdbc.sql_exception_converter` | Fully-qualified name of class implementing `SQLExceptionConverter` |The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/exception/spi/SQLExceptionConverter.html[`SQLExceptionConverter`] to use for converting `SQLExceptions` to Hibernate's `JDBCException` hierarchy. The default is to use the configured https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/dialect/Dialect.html[`Dialect`]'s preferred `SQLExceptionConverter`.
|===================================================================================================================================================================================================================================
[[configurations-session-events]]
@ -658,7 +703,7 @@ Therefore, the `org.hibernate.tool.hbm2ddl.UniqueConstraintSchemaUpdateStrategy`
|`hibernate.session.events.auto` | | Fully qualified class name implementing the `SessionEventListener` interface.
|`hibernate.session_factory.interceptor` or `hibernate.ejb.interceptor` | `org.hibernate.EmptyInterceptor` (default value) a|
Names a `org.hibernate.Interceptor` implementation to be applied to every `Session` created by the current `org.hibernate.SessionFactory`
Names a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/Interceptor` implementation to be applied to every `Session` created by the current `org.hibernate.SessionFactory`
Can reference:
@ -711,6 +756,29 @@ This property can not be combined with `hibernate.ejb.interceptor`.
|`hibernate.classLoader.resources` | |Names the `ClassLoader` Hibernate should use to perform resource loading.
|`hibernate.classLoader.hibernate` | |Names the `ClassLoader` responsible for loading Hibernate classes. By default this is the `ClassLoader` that loaded this class.
|`hibernate.classLoader.environment` | |Names the `ClassLoader` used when Hibernate is unable to locates classes on the `hibernate.classLoader.application` or `hibernate.classLoader.hibernate`.
|=====================================================================================================================================================================================================================================================
[[configurations-bootstrap]]
=== Bootstrap properties
[width="100%",cols="20%,20%,60%",]
|=====================================================================================================================================================================================================================================================
|Property |Example |Purpose
|`hibernate.integrator_provider` | The fully qualified name of an https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/jpa/boot/spi/IntegratorProvider.html[`IntegratorProvider`] |
Used to define a list of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/integrator/spi/Integrator.html[`Integrator`] which are used during bootstrap process to integrate various services.
|`hibernate.strategy_registration_provider` | The fully qualified name of an https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/jpa/boot/spi/StrategyRegistrationProviderList.html[`StrategyRegistrationProviderList`] |
Used to define a list of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/registry/selector/StrategyRegistrationProvider.html[`StrategyRegistrationProvider`] which are used during bootstrap process to provide registrations of strategy selector(s).
|`hibernate.type_contributors` | The fully qualified name of an https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/jpa/boot/spi/TypeContributorList.html[`TypeContributorList`] |
Used to define a list of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/model/TypeContributor.html[`TypeContributor`] which are used during bootstrap process to contribute types.
|`hibernate.persister.resolver` | The fully qualified name of a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/persister/spi/PersisterClassResolver.html[`PersisterClassResolver`] or a `PersisterClassResolver` instance |
Used to define an implementation of the `PersisterClassResolver` interface which can be used to customize how an entity or a collection is being persisted.
|`hibernate.persister.factory` | The fully qualified name of a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/persister/spi/PersisterFactory.html[`PersisterFactory`] or a `PersisterFactory` instance |
Like a `PersisterClassResolver`, the `PersisterFactory` can be used to customize how an entity or a collection are being persisted.
|`hibernate.service.allow_crawling` | `true` (default value) or `false` |
Crawl all available service bindings for an alternate registration of a given Hibernate `Service`.
|=====================================================================================================================================================================================================================================================
[[configurations-misc]]
@ -719,7 +787,7 @@ This property can not be combined with `hibernate.ejb.interceptor`.
[width="100%",cols="20%,20%,60%",]
|=====================================================================================================================================================================================================================================================
|Property |Example |Purpose
|`hibernate.dialect_resolvers` | | Names any additional `org.hibernate.engine.jdbc.dialect.spi.DialectResolver` implementations to register with the standard `org.hibernate.engine.jdbc.dialect.spi.DialectFactory`
|`hibernate.dialect_resolvers` | | Names any additional https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/jdbc/dialect/spi/DialectResolver.html[`DialectResolver`] implementations to register with the standard https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/engine/jdbc/dialect/spi/DialectFactory.html[`DialectFactory`]
|`hibernate.session_factory_name` |A JNDI name |
Setting used to name the Hibernate `SessionFactory`.
@ -761,7 +829,7 @@ disabled:: Do not do the population
skipUnsupported:: Do the population, but ignore any non-JPA features that would otherwise result in the population failing (e.g. `@Any` annotation).
|`hibernate.delay_cdi_access`| `true` or `false` (default value) | Defines delayed access to CDI `BeanManager`. Starting in 5.1 the preferred means for CDI bootstrapping is through `org.hibernate.jpa.event.spi.jpa.ExtendedBeanManager`.
|`hibernate.delay_cdi_access`| `true` or `false` (default value) | Defines delayed access to CDI `BeanManager`. Starting in 5.1 the preferred means for CDI bootstrapping is through https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/jpa/event/spi/jpa/ExtendedBeanManager.html[`ExtendedBeanManager`].
|`hibernate.allow_update_outside_transaction` | `true` or `false` (default value) a|
@ -774,7 +842,7 @@ false:: does not allow
|`hibernate.collection_join_subquery`| `true` (default value) or `false` | Setting which indicates whether or not the new JOINS over collection tables should be rewritten to subqueries.
|`hibernate.allow_refresh_detached_entity`| `true` (default value when using Hibernate native bootstrapping) or `false` (default value when using JPA bootstrapping) | Setting that allows to call `javax.persistence.EntityManager#refresh()` or `org.hibernate.Session#refresh()` on a detached instance even when the `org.hibernate.Session` is obtained from a JPA `javax.persistence.EntityManager`.
|`hibernate.allow_refresh_detached_entity`| `true` (default value when using Hibernate native bootstrapping) or `false` (default value when using JPA bootstrapping) | Setting that allows to call `javax.persistence.EntityManager#refresh(entity)` or `Session#refresh(entity)` on a detached instance even when the `org.hibernate.Session` is obtained from a JPA `javax.persistence.EntityManager`.
|`hibernate.event.merge.entity_copy_observer`| `disallow` (default value), `allow`, `log` (testing purpose only) or fully-qualified class name a|
Setting that specifies how Hibernate will respond when multiple representations of the same persistent entity ("entity copy") is detected while merging.
@ -784,9 +852,9 @@ The possible values are:
disallow (the default):: throws `IllegalStateException` if an entity copy is detected
allow:: performs the merge operation on each entity copy that is detected
log:: (provided for testing only) performs the merge operation on each entity copy that is detected and logs information about the entity copies.
This setting requires DEBUG logging be enabled for `org.hibernate.event.internal.EntityCopyAllowedLoggedObserver`.
This setting requires DEBUG logging be enabled for https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/event/internal/EntityCopyAllowedLoggedObserver.html[`EntityCopyAllowedLoggedObserver`].
In addition, the application may customize the behavior by providing an implementation of `org.hibernate.event.spi.EntityCopyObserver` and setting `hibernate.event.merge.entity_copy_observer` to the class name.
In addition, the application may customize the behavior by providing an implementation of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/event/spi/EntityCopyObserver.html[`EntityCopyObserver`] and setting `hibernate.event.merge.entity_copy_observer` to the class name.
When this property is set to `allow` or `log`, Hibernate will merge each entity copy detected while cascading the merge operation.
In the process of merging each entity copy, Hibernate will cascade the merge operation from each entity copy to its associations with `cascade=CascadeType.MERGE` or `CascadeType.ALL`.
The entity state resulting from merging an entity copy will be overwritten when another entity copy is merged.
@ -795,3 +863,38 @@ For more details, check out the <<chapters/pc/PersistenceContext.adoc#pc-merge-g
|=====================================================================================================================================================================================================================================================
[[configurations-envers]]
=== Envers properties
[width="100%",cols="20%,20%,60%",]
|=====================================================================================================================================================================================================================================================
|Property |Example |Purpose
|`hibernate.envers.autoRegisterListeners` | `true` (default value) or `false` |When set to `false`, the Envers entity listeners are no longer auto-registered, so you need to register them manually during the bootstrap process.
|`hibernate.integration.envers.enabled` | `true` (default value) or `false` |Enable or disable the Hibernate Envers `Service` integration.
|`hibernate.listeners.envers.autoRegister` | |Legacy setting. Use `hibernate.envers.autoRegisterListeners` or `hibernate.integration.envers.enabled` instead.
|=====================================================================================================================================================================================================================================================
[[configurations-spatial]]
=== Spatial properties
[width="100%",cols="20%,20%,60%",]
|=====================================================================================================================================================================================================================================================
|Property |Example |Purpose
|`hibernate.integration.spatial.enabled` | `true` (default value) or `false` | Enable or disable the Hibernate Spatial `Service` integration.
|`hibernate.spatial.connection_finder` | `org.geolatte.geom.codec.db.oracle.DefaultConnectionFinder` | Define the fully-qualified name of class implementing the `org.geolatte.geom.codec.db.oracle.ConnectionFinder` interface.
|=====================================================================================================================================================================================================================================================
[[configurations-internal]]
=== Internal properties
The following configuration properties are used internally, and you shouldn't probably have to configured them in your application.
[width="100%",cols="20%,20%,60%",]
|=====================================================================================================================================================================================================================================================
|Property |Example |Purpose
|`hibernate.enable_specj_proprietary_syntax` | `true` or `false` (default value) | Enable or disable the SpecJ proprietary mapping syntax which differs from JPA specification. Used during performance testing only.
|`hibernate.temp.use_jdbc_metadata_defaults` | `true` (default value) or `false` |
This setting is used to control whether we should consult the JDBC metadata to determine certain Settings default values when the database may not be available (mainly in tools usage).
|`hibernate.connection_provider.injection_data` | `java.util.Map` | Connection provider settings to be injected in the currently configured connection provider.
|`hibernate.jandex_index` | `org.jboss.jandex.Index` | Names a Jandex `org.jboss.jandex.Index` instance to use.
|=====================================================================================================================================================================================================================================================