24. Configurations

24.1. Strategy configurations

Many configuration settings define pluggable strategies that Hibernate uses for various purposes. The configurations of many of these strategy type settings accept definition in various forms. The documentation of such configuration settings refers here. The types of forms available in such cases include:

short name (if defined)

Certain built-in strategy implementations have a corresponding short name

strategy instance

An instance of the strategy implementation to use can be specified

strategy Class reference

A java.lang.Class reference of the strategy implementation to use

strategy Class name

The class name (java.lang.String) of the strategy implementation to use

24.2. General configuration

**hibernate.dialect** (e.g. org.hibernate.dialect.PostgreSQL94Dialect)

The class name of a Hibernate Dialect from which Hibernate can generate SQL optimized for a particular relational database.

In most cases, Hibernate can choose the correct Dialect implementation based on the JDBC metadata returned by the JDBC driver.

**hibernate.current_session_context_class** (e.g. jta, thread, managed, or a custom class implementing org.hibernate.context.spi.CurrentSessionContext)

Supplies a custom strategy for the scoping of the current Session.

The definition of what exactly current means is controlled by the CurrentSessionContext implementation in use.

Note that for backward compatibility, if a CurrentSessionContext is not configured but JTA is configured this will default to the JTASessionContext.

24.3. JPA compliance

**hibernate.jpa.compliance.transaction** (e.g. true or false (default value))

This setting controls if Hibernate Transaction should behave as defined by the spec for JPA’s javax.persistence.EntityTransaction since it extends the JPA one.

**hibernate.jpa.compliance.query** (e.g. true or false (default value))

Controls whether Hibernate’s handling of javax.persistence.Query (JPQL, Criteria and native query) should strictly follow the JPA spec.

This includes both in terms of parsing or translating a query as well as calls to the javax.persistence.Query methods throwing spec defined exceptions whereas Hibernate might not.

**hibernate.jpa.compliance.list** (e.g. true or false (default value))

Controls whether Hibernate should recognize what it considers a “bag” (org.hibernate.collection.internal.PersistentBag) as a List (org.hibernate.collection.internal.PersistentList) or as a bag.

If enabled, we will recognize it as a List where javax.persistence.OrderColumn is just missing (and its defaults will apply).

**hibernate.jpa.compliance.closed** (e.g. true or false (default value))

JPA defines specific exceptions upon calling specific methods on javax.persistence.EntityManager and javax.persistence.EntityManagerFactory objects which have been closed previously.

This setting controls whether the JPA spec-defined behavior or the Hibernate behavior will be used.

If enabled, Hibernate will operate in the JPA specified way, throwing exceptions when the spec says it should.

**hibernate.jpa.compliance.proxy** (e.g. true or false (default value))

The JPA spec says that a javax.persistence.EntityNotFoundException should be thrown when accessing an entity proxy which does not have an associated table row in the database.

Traditionally, Hibernate does not initialize an entity proxy when accessing its identifier since we already know the identifier value, hence we can save a database roundtrip.

If enabled Hibernate will initialize the entity proxy even when accessing its identifier.

**hibernate.jpa.compliance.global_id_generators** (e.g. true or false (default value) )

The JPA spec says that the scope of TableGenerator and SequenceGenerator names is global to the persistence unit (across all generator types).

Traditionally, Hibernate has considered the names locally scoped.

If enabled, the names used by @TableGenerator and @SequenceGenerator will be considered global so configuring two different generators with the same name will cause a java.lang.IllegalArgumentException to be thrown at boot time.

24.4. Database connection properties

**hibernate.connection.driver_class** or **javax.persistence.jdbc.driver** (e.g. org.postgresql.Driver)

Names the JDBC Driver class name.

**hibernate.connection.url** or **javax.persistence.jdbc.url** (e.g. jdbc:postgresql:hibernate_orm_test)

Names the JDBC connection URL.

**hibernate.connection.username** or **javax.persistence.jdbc.user**

Names the JDBC connection user name.

**hibernate.connection.password** or **javax.persistence.jdbc.password**

Names the JDBC connection password.

**hibernate.connection.isolation** (e.g. REPEATABLE_READ or Connection.TRANSACTION_REPEATABLE_READ)

Names the JDBC connection transaction isolation level.

**hibernate.connection.autocommit** (e.g. true or false (default value))

Names the initial autocommit mode for JDBC Connections returned from a connection pool created in certain ConnectionProvider impl.

See discussion of hibernate.connection.provider_disables_autocommit as well.

**hibernate.connection.provider_disables_autocommit** (e.g. true or false (default value))

Indicates a promise by the user that Connections that Hibernate obtains from the configured ConnectionProvider have auto-commit disabled when they are obtained from that provider, whether that provider is backed by a DataSource or some other Connection pooling mechanism. Generally, this occurs when:

• Hibernate is configured to get Connections from an underlying DataSource, and that DataSource is already configured to disable auto-commit on its managed Connections.

• Hibernate is configured to get Connections from a non-DataSource connection pool and that connection pool is already configured to disable auto-commit. For the Hibernate provided implementation this will depend on the value of hibernate.connection.autocommit setting.

  Hibernate uses this assurance as an opportunity to opt out of certain operations that may have a performance impact (although this impact is generally negligible). Specifically, when a transaction is started via the Hibernate or JPA transaction APIs Hibernate will generally immediately acquire a Connection from the provider and:

• check whether the Connection is initially in auto-commit mode via a call to Connection#getAutocommit to know how to clean up the Connection when released.

• start a JDBC transaction by calling Connection#setAutocommit(false).

  We can skip both of those steps if we know that the ConnectionProvider will always return Connections with auto-commit disabled. That is the purpose of this setting. By setting it to true, the Connection acquisition can be delayed until the first SQL statement is needed to be executed. The connection acquisition delay allows you to reduce the database connection lease time, therefore allowing you to increase the transaction throughput.

  It is inappropriate to set this value to true when the Connections Hibernate gets from the provider do not, in fact, have auto-commit disabled.

  Doing so will lead to Hibernate executing SQL operations outside of any JDBC/SQL transaction.

**hibernate.connection.handling_mode**

Specifies how Hibernate should manage JDBC connections in terms of acquiring and releasing. This configuration property supersedes **hibernate.connection.acquisition_mode** and **hibernate.connection.release_mode**.

The connection handling mode strategies are defined by the PhysicalConnectionHandlingMode enumeration.

The configuration can be either a PhysicalConnectionHandlingMode reference or its case-insensitive String representation.

For more details about the PhysicalConnectionHandlingMode and Hibernate connection handling, check out the Connection handling section.

**hibernate.connection.acquisition_mode** (e.g. immediate)

Specifies how Hibernate should acquire JDBC connections. The possible values are given by org.hibernate.ConnectionAcquisitionMode.

Should generally only configure this or hibernate.connection.release_mode, not both.

**hibernate.connection.release_mode** (e.g. auto (default value))

Specifies how Hibernate should release JDBC connections. The possible values are given by the current transaction mode (after_transaction for JDBC transactions and after_statement for JTA transactions).

Should generally only configure this or hibernate.connection.acquisition_mode, not both.

**hibernate.connection.datasource**

Either a javax.sql.DataSource instance or a JNDI name under which to locate the DataSource.

For JNDI names, ses also hibernate.jndi.class, hibernate.jndi.url, hibernate.jndi.

**hibernate.connection**

Names a prefix used to define arbitrary JDBC connection properties. These properties are passed along to the JDBC provider when creating a connection.

**hibernate.connection.provider_class** (e.g. org.hibernate.hikaricp.internal. HikariCPConnectionProvider)

Names the ConnectionProvider to use for obtaining JDBC connections.

Can reference:

• an instance of ConnectionProvider

• a Class<? extends ConnectionProvider> object reference

• a fully qualified name of a class implementing ConnectionProvider

  The term class appears in the setting name due to legacy reasons. However, it can accept instances.

**hibernate.jndi.class**

Names the JNDI javax.naming.InitialContext class.

**hibernate.jndi.url** (e.g. java:global/jdbc/default)

Names the JNDI provider/connection url.

**hibernate.jndi**

Names a prefix used to define arbitrary JNDI javax.naming.InitialContext properties.

These properties are passed along to javax.naming.InitialContext#InitialContext(java.util.Hashtable) method.

24.4.1. Hibernate internal connection pool options

**hibernate.connection.initial_pool_size** (e.g. 1 (default value))

Minimum number of connections for the built-in Hibernate connection pool.

**hibernate.connection.pool_size** (e.g. 20 (default value))

Maximum number of connections for the built-in Hibernate connection pool.

**hibernate.connection.pool_validation_interval** (e.g. 30 (default value))

The number of seconds between two consecutive pool validations. During validation, the pool size can increase or decrease based on the connection acquisition request count.

24.5. c3p0 properties

**hibernate.c3p0.min_size** (e.g. 1)

Minimum size of C3P0 connection pool. Refers to c3p0 minPoolSize setting.

**hibernate.c3p0.max_size** (e.g. 5)

Maximum size of C3P0 connection pool. Refers to c3p0 maxPoolSize setting.

**hibernate.c3p0.timeout** (e.g. 30)

Maximum idle time for C3P0 connection pool. Refers to c3p0 maxIdleTime setting.

**hibernate.c3p0.max_statements** (e.g. 5)

Maximum size of C3P0 statement cache. Refers to c3p0 maxStatements setting.

**hibernate.c3p0.acquire_increment** (e.g. 2)

The number of connections acquired at a time when there’s no connection available in the pool. Refers to c3p0 acquireIncrement setting.

**hibernate.c3p0.idle_test_period** (e.g. 5)

Idle time before a C3P0 pooled connection is validated. Refers to c3p0 idleConnectionTestPeriod setting.

**hibernate.c3p0**

A setting prefix used to indicate additional c3p0 properties that need to be passed to the underlying c3p0 connection pool.

24.6. Mapping Properties

24.6.1. Table qualifying options

**hibernate.default_catalog** (e.g. A catalog name)

Qualifies unqualified table names with the given catalog in generated SQL.

**hibernate.default_schema** (e.g. A schema name)

Qualify unqualified table names with the given schema or tablespace in generated SQL.

**hibernate.schema_name_resolver** (e.g. The fully qualified name of an org.hibernate.engine.jdbc.env.spi.SchemaNameResolver implementation class)

By default, Hibernate uses the org.hibernate.dialect.Dialect#getSchemaNameResolver. You can customize how the schema name is resolved by providing a custom implementation of the SchemaNameResolver interface.

24.6.2. Identifier options

**hibernate.id.new_generator_mappings** (e.g. true (default value) or false)

Setting which indicates whether or not the new 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** (e.g. true or false (default value))

If true, generated identifier properties are reset to default values when objects are deleted.

**hibernate.id.optimizer.pooled.preferred** (e.g. none, hilo, legacy-hilo, pooled (default value), pooled-lo, pooled-lotl or a fully-qualified name of the Optimizer implementation)

When a generator specified an increment-size and an optimizer was not explicitly specified, which of the pooled optimizers should be preferred?

**hibernate.id.generator.stored_last_used** (e.g. true (default value) or false)

If true, the value stored in the table used by the @TableGenerator is the last value used, if false the value is the next value to be used.

**hibernate.model.generator_name_as_sequence_name** (e.g. true (default value) or false)

If true, the value specified by the generator attribute of the @GeneratedValue annotation should be used as the sequence/table name when no matching @SequenceGenerator or TableGenerator is found.

The default value is true meaning that @GeneratedValue.generator() will be used as the sequence/table name by default. Users migrating from earlier versions using the legacy hibernate_sequence name should disable this setting.

**hibernate.ejb.identifier_generator_strategy_provider** (e.g. fully-qualified class name or an actual IdentifierGeneratorStrategyProvider instance)

This setting allows you to provide an instance or the class implementing the org.hibernate.jpa.spi.IdentifierGeneratorStrategyProvider interface, so you can provide a set of IdentifierGenerator strategies allowing to override the Hibernate Core default ones.

**hibernate.id.disable_delayed_identity_inserts** (e.g. true or false (default value))

If true, inserts that use generated-identifiers (identity/sequences) will never be delayed and will always be inserted immediately. This should be used if you run into any errors with DelayedPostInsertIdentifier and should be considered a temporary fix. Please report your mapping that causes the problem to us so we can examine the default algorithm to see if your use case should be included.

The default value is false which means Hibernate will use an algorithm to determine if the insert can be delayed or if the insert should be performed immediately.

24.6.3. Quoting options

**hibernate.globally_quoted_identifiers** (e.g. true or false (default value))

Should all database identifiers be quoted.

**hibernate.globally_quoted_identifiers_skip_column_definitions** (e.g. true or false (default value))

Assuming hibernate.globally_quoted_identifiers is true, this allows the global quoting to skip column-definitions as defined by javax.persistence.Column, javax.persistence.JoinColumn, etc., and while it avoids column-definitions being quoted due to global quoting, they can still be explicitly quoted in the annotation/xml mappings.

**hibernate.auto_quote_keyword** (e.g. true or false (default value))

Specifies whether to automatically quote any names that are deemed keywords.

24.6.4. Discriminator options

**hibernate.discriminator.implicit_for_joined** (e.g. true or false (default value))

The legacy behavior of Hibernate is to not use discriminators for joined inheritance (Hibernate does not need the discriminator). However, some JPA providers do need the discriminator for handling joined inheritance so, in the interest of portability, this capability has been added to Hibernate too.

Because want to make sure that legacy applications continue to work as well, that puts us in a bind in terms of how to handle implicit discriminator mappings. The solution is to assume that the absence of discriminator metadata means to follow the legacy behavior unless this setting is enabled.

With this setting enabled, Hibernate will interpret the absence of discriminator metadata as an indication to use the JPA-defined defaults for these absent annotations.

See Hibernate Jira issue HHH-6911 for additional background info.

**hibernate.discriminator.ignore_explicit_for_joined** (e.g. true or false (default value))

The legacy behavior of Hibernate is to not use discriminators for joined inheritance (Hibernate does not need the discriminator). However, some JPA providers do need the discriminator for handling joined inheritance so, in the interest of portability, this capability has been added to Hibernate too.

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.

See Hibernate Jira issue HHH-6911 for additional background info.

24.6.5. Naming strategies

**hibernate.implicit_naming_strategy** (e.g. default (default value), jpa, legacy-jpa, legacy-hbm, component-path)

Used to specify the ImplicitNamingStrategy class to use. The following short names are defined for this setting:

• default

  Uses the ImplicitNamingStrategyJpaCompliantImpl

  jpa

  Uses the ImplicitNamingStrategyJpaCompliantImpl

  legacy-jpa

  Uses the ImplicitNamingStrategyLegacyJpaImpl

  legacy-hbm

  Uses the ImplicitNamingStrategyLegacyHbmImpl

  component-path

  Uses the ImplicitNamingStrategyComponentPathImpl

  If this property happens to be empty, the fallback is to use the default strategy.

**hibernate.physical_naming_strategy** (e.g. org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl (default value))

Used to specify the PhysicalNamingStrategy class to use.

24.6.6. Metadata scanning options

**hibernate.archive.scanner**

Pass an implementation of Scanner. By default, StandardScanner is used.

Accepts:

• an actual Scanner instance

• a reference to a Class that implements Scanner

• a fully qualified name of a Class that implements Scanner

**hibernate.archive.interpreter**

Pass ArchiveDescriptorFactory to use in the scanning process.

Accepts:

• an actual ArchiveDescriptorFactory instance

• a reference to a Class that implements ArchiveDescriptorFactory

• a fully qualified name of a Class that implements ArchiveDescriptorFactory

  See information on Scanner about expected constructor forms.

**hibernate.archive.autodetection** (e.g. hbm,class (default value))

Identifies a comma-separated list of values indicating the mapping types we should auto-detect during scanning.

Allowable values include:

• class

  scan classes (e.g. .class) to extract entity mapping metadata

  hbm

  scan hbm mapping files (e.g. hbm.xml) to extract entity mapping metadata

  By default HBM, annotations, and JPA XML mappings are scanned.

  When using JPA, to disable the automatic scanning of all entity classes, the exclude-unlisted-classes persistence.xml element must be set to true. Therefore, when setting exclude-unlisted-classes to true, only the classes that are explicitly declared in the persistence.xml configuration files are going to be taken into consideration.

**hibernate.mapping.precedence** (e.g. 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 MetadataSourceType.

The default is hbm,class, therefore hbm.xml files are processed first, followed by annotations (combined with orm.xml mappings).

When using JPA, the XML mapping overrides a conflicting annotation mapping that targets the same entity attribute.

24.6.7. JDBC-related options

**hibernate.use_nationalized_character_data** (e.g. 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** (e.g. 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** (e.g. 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 PreparedStatement#setTimestamp is going to use a Calendar instance according to the specified time zone.

**hibernate.dialect.oracle.prefer_long_raw** (e.g. 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).

24.6.8. Bean Validation options

**javax.persistence.validation.factory** (e.g. javax.validation.ValidationFactory implementation)

Specify the javax.validation.ValidationFactory implementation to use for Bean Validation.

**hibernate.check_nullability** (e.g. true or false)

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** (e.g. 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.

24.6.9. Misc options

**hibernate.create_empty_composites.enabled** (e.g. 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 nulls.

This is an experimental feature that has known issues. It should not be used in production until it is stabilized. See Hibernate Jira issue HHH-11936 for details.

**hibernate.entity_dirtiness_strategy** (e.g. fully-qualified class name or an actual CustomEntityDirtinessStrategy instance)

Setting to identify an org.hibernate.CustomEntityDirtinessStrategy to use.

**hibernate.default_entity_mode** (e.g. pojo (default value) or dynamic-map)

Default EntityMode for entity representation for all sessions opened from this SessionFactory, defaults to pojo.

24.7. Bytecode Enhancement Properties

**hibernate.enhancer.enableDirtyTracking** (e.g. true or false (default value))

Enable dirty tracking feature in runtime bytecode enhancement.

**hibernate.enhancer.enableLazyInitialization** (e.g. 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** (e.g. 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** (e.g. bytebuddy (default value))

The BytecodeProvider built-in implementation flavor. Currently, only bytebuddy and javassist are valid values.

**hibernate.bytecode.use_reflection_optimizer** (e.g. true or false (default value))

Should we use reflection optimization? The reflection optimizer implements the ReflectionOptimizer interface and improves entity instantiation and property getter/setter calls.

**hibernate.bytecode.enforce_legacy_proxy_classnames** (e.g. true or false (default value))

Some other libraries, such as Spring, used to depend on a specific naming pattern used for proxy classes generated at runtime. Set this to true to have proxy class names conform to the old pattern.

24.8. Query settings

**hibernate.query.plan_cache_max_size** (e.g. 2048 (default value))

The maximum number of entries including: HQLQueryPlan, FilterQueryPlan, NativeSQLQueryPlan.

Maintained by QueryPlanCache.

**hibernate.query.plan_parameter_metadata_max_size** (e.g. 128 (default value))

The maximum number of strong references associated with ParameterMetadata maintained by QueryPlanCache.

**hibernate.order_by.default_null_ordering** (e.g. 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** (e.g. true or false (default value))

For entities which do not explicitly say, should we force discriminators into SQL selects?

**hibernate.query.substitutions** (e.g. true=1,false=0)

A comma-separated list of token substitutions to use when translating a Hibernate query to SQL.

**hibernate.query.factory_class** (e.g. org.hibernate.hql.internal.ast.ASTQueryTranslatorFactory (default value) or org.hibernate.hql.internal.classic.ClassicQueryTranslatorFactory)

Chooses the HQL parser implementation.

**hibernate.query.jpaql_strict_compliance** (e.g. true or false (default value))

Map from tokens in Hibernate queries to SQL tokens, such as function or literal names.

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** (e.g. true (default value) or false)

Should named queries be checked during startup?

**hibernate.proc.param_null_passing** (e.g. true or false (default value))

Global setting for whether null parameter bindings should be passed to database procedure/function calls as part of 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).

Values are true (pass the NULLs) or false (do not pass the NULLs).

**hibernate.jdbc.log.warnings** (e.g. 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** (e.g. A fully-qualified class name, an instance, or a Class object reference)

Names a StatementInspector implementation to be applied to every Session created by the current SessionFactory.

Can reference a StatementInspector instance, StatementInspector implementation Class reference or StatementInspector implementation class name (fully-qualified class name).

**hibernate.query.validate_parameters** (e.g. true (default value) or false)

This configuration property can be used to disable parameters validation performed by org.hibernate.query.Query#setParameter when the Session is bootstrapped via JPA javax.persistence.EntityManagerFactory.

**hibernate.criteria.literal_handling_mode** (e.g. AUTO (default value), BIND or INLINE)

By default, Criteria queries use bind parameters for any literal that is not a numeric value. However, to increase the likelihood of JDBC statement caching, you might want to use bind parameters for numeric values too.

The org.hibernate.query.criteria.LiteralHandlingMode#BIND mode will use bind variables for any literal value. The org.hibernate.query.criteria.LiteralHandlingMode#INLINE mode will inline literal values as is.

To prevent SQL injection, never use org.hibernate.query.criteria.LiteralHandlingMode#INLINE with String variables. Always use constants with the org.hibernate.query.criteria.LiteralHandlingMode#INLINE mode.

Valid options are defined by the org.hibernate.query.criteria.LiteralHandlingMode enum. The default value is org.hibernate.query.criteria.LiteralHandlingMode#AUTO.

**hibernate.query.fail_on_pagination_over_collection_fetch** (e.g. true or false (default value))

Raises an exception when in-memory pagination over collection fetch is about to be performed.

Disabled by default. Set to true to enable.

24.8.1. Multi-table bulk HQL operations

**hibernate.hql.bulk_id_strategy** (e.g. 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.hql.bulk_id_strategy.global_temporary.drop_tables** (e.g. 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** (e.g. true or false (default value))

This configuration property is used by the PersistentTableBulkIdStrategy, that mimics temporary tables for databases which do not support temporary tables. It follows a pattern similar to the ANSI SQL definition of the 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** (e.g. Database schema name. By default, the hibernate.default_schema is used.)

This configuration property is used by the PersistentTableBulkIdStrategy, that mimics temporary tables for databases which do not support temporary tables. It follows a pattern similar to the ANSI SQL definition of the 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** (e.g. Database catalog name. By default, the hibernate.default_catalog is used.)

This configuration property is used by the PersistentTableBulkIdStrategy, that mimics temporary tables for databases which do not support temporary tables. It follows a pattern similar to the ANSI SQL definition of the 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.

**hibernate.legacy_limit_handler** (e.g. true or false (default value))

Setting which indicates whether or not to use org.hibernate.dialect.pagination.LimitHandler implementations that sacrifices performance optimizations to allow legacy 4.x limit behavior.

Legacy 4.x behavior favored performing pagination in-memory by avoiding the use of the offset value, which is overall poor performance. In 5.x, the limit handler behavior favors performance, thus, if the dialect doesn’t support offsets, an exception is thrown instead.

**hibernate.query.conventional_java_constants** (e.g. true (default value) or false)

Setting which indicates whether or not Java constants follow the Java Naming conventions.

The default is true. Existing applications may want to disable this (set it false) if non-conventional Java constants are used. However, there is a significant performance overhead for using non-conventional Java constants since Hibernate cannot determine if aliases should be treated as Java constants or not.

Check out HHH-4959 for more details.

24.9. Batching properties

**hibernate.jdbc.batch_size** (e.g. 5)

Maximum JDBC batch size. A nonzero value enables batch updates.

**hibernate.order_inserts** (e.g. true or false (default value))

Forces Hibernate to order SQL inserts by the primary key value of the items being inserted. This preserves batching when using cascading.

**hibernate.order_updates** (e.g. true or false (default value))

Forces Hibernate to order SQL updates by the primary key value of the items being updated. This preserves batching when using cascading and reduces the likelihood of transaction deadlocks in highly-concurrent systems.

**hibernate.jdbc.batch_versioned_data** (e.g. true(default value) or false)

Should versioned entities be included in batching?

Set this property to true if your JDBC driver returns correct row counts from executeBatch(). This option is usually safe, but is disabled by default. If enabled, Hibernate uses batched DML for automatically versioned data.

**hibernate.batch_fetch_style** (e.g. LEGACY(default value))

Names the BatchFetchStyle to use.

Can specify either the BatchFetchStyle name (case insensitively), or a BatchFetchStyle instance. LEGACY is the default value.

**hibernate.jdbc.batch.builder** (e.g. the fully qualified name of a BatchBuilder implementation class type or an actual object instance)

Names the BatchBuilder implementation to use.

24.9.1. Fetching properties

**hibernate.max_fetch_depth** (e.g. a value between 0 and 3)

Sets a maximum depth for the outer join fetch tree for single-ended associations. A single-ended association is a one-to-one or many-to-one association. A value of 0 disables default outer join fetching.

**hibernate.default_batch_fetch_size** (e.g. 4,8, or 16)

The default size for Hibernate Batch fetching of associations (lazily fetched associations can be fetched in batches to prevent N+1 query problems).

**hibernate.jdbc.fetch_size** (e.g. 0 or an integer)

A non-zero value determines the JDBC fetch size, by calling Statement.setFetchSize().

**hibernate.jdbc.use_scrollable_resultset** (e.g. true or false)

Enables Hibernate to use JDBC2 scrollable resultsets. This property is only relevant for user-supplied JDBC connections. Otherwise, Hibernate uses connection metadata.

**hibernate.jdbc.use_streams_for_binary** (e.g. true or false (default value))

Use streams when writing or reading binary or serializable types to or from JDBC. This is a system-level property.

**hibernate.jdbc.use_get_generated_keys** (e.g. true or false)

Allows Hibernate to use JDBC3 PreparedStatement.getGeneratedKeys() to retrieve natively-generated keys after insert. You need the JDBC3+ driver and JRE1.4+. Disable this property if your driver has problems with the Hibernate identifier generators. By default, it tries to detect the driver capabilities from connection metadata.

**hibernate.jdbc.wrap_result_sets** (e.g. true or false (default value))

Enable wrapping of JDBC result sets in order to speed up column name lookups for broken JDBC drivers.

**hibernate.enable_lazy_load_no_trans** (e.g. true or false (default value))

Initialize Lazy Proxies or Collections outside a given Transactional Persistence Context.

Although enabling this configuration can make LazyInitializationException go away, it’s better to use a fetch plan that guarantees that all properties are properly initialized before the Session is closed.

In reality, you shouldn’t probably enable this setting anyway.

24.10. Statement logging and statistics

24.10.1. SQL statement logging

**hibernate.show_sql** (e.g. true or false (default value))

Write all SQL statements to the console. This is an alternative to setting the log category org.hibernate.SQL to debug.

**hibernate.format_sql** (e.g. true or false (default value))

Pretty-print the SQL in the log and console.

**hibernate.use_sql_comments** (e.g. true or false (default value))

If true, Hibernate generates comments inside the SQL, for easier debugging.

24.10.2. Statistics settings

**hibernate.generate_statistics** (e.g. true or false)

Causes Hibernate to collect statistics for performance tuning.

**hibernate.stats.factory** (e.g. the fully qualified name of a StatisticsFactory implementation or an actual instance)

The StatisticsFactory allow you to customize how the Hibernate Statistics are being collected.

**hibernate.session.events.log** (e.g. true or false)

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.

24.11. Cache Properties

**hibernate.cache.region.factory_class** (e.g. jcache)

Either a shortcut name (e.g. jcache, ehcache) or the fully-qualified name of the RegionFactory implementation class.

**hibernate.cache.default_cache_concurrency_strategy**

Setting used to give the name of the default CacheConcurrencyStrategy to use when @javax.persistence.Cacheable, @org.hibernate.annotations.Cache or @org.hibernate.annotations.Cache is used to override the global setting.

**hibernate.cache.use_minimal_puts** (e.g. 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** (e.g. 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** (e.g. 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** (e.g. fully-qualified class name)

A custom QueryCacheFactory interface. The default is the built-in StandardQueryCacheFactory.

**hibernate.cache.region_prefix** (e.g. A string)

A prefix for second-level cache region names.

**hibernate.cache.use_structured_entries** (e.g. 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** (e.g. 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.

**hibernate.cache.use_reference_entries** (e.g. true or false)

Optimizes second-level cache operation to store immutable entities (aka “reference”) which do not have associations into cache directly. In this case, disassembling and deep copy operations can be avoided. The default value of this property is false.

**hibernate.ejb.classcache** (e.g. hibernate.ejb.classcache.org.hibernate.ejb.test.Item = read-write)

Sets the associated entity class cache concurrency strategy for the designated region. Caching configuration should follow the following pattern hibernate.ejb.classcache.<fully.qualified.Classname> = usage[, region] where usage is the cache strategy used and region the cache region name.

**hibernate.ejb.collectioncache** (e.g. hibernate.ejb.collectioncache.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.

24.12. Infinispan properties

For more details about how to customize the Infinispan second-level cache provider, check out the Infinispan User Guide.

24.13. Transactions properties

**hibernate.transaction.jta.platform** (e.g. JBossAS, BitronixJtaPlatform)

Names the JtaPlatform implementation to use for integrating with JTA systems. Can reference either a JtaPlatform instance or the name of the JtaPlatform implementation class.

**hibernate.jta.prefer_user_transaction** (e.g. 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 JtaPlatformResolver implementation to use.

**hibernate.jta.cacheTransactionManager** (e.g. true (default value) or false)

A configuration value key used to indicate that it is safe to cache.

**hibernate.jta.cacheUserTransaction** (e.g. true or false (default value))

A configuration value key used to indicate that it is safe to cache.

**hibernate.transaction.flush_before_completion** (e.g. 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** (e.g. 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**

Names the implementation of TransactionCoordinatorBuilder to use for creating TransactionCoordinator instances.

Can be a TransactionCoordinatorBuilder instance, TransactionCoordinatorBuilder implementation Class reference, a TransactionCoordinatorBuilder implementation class name (fully-qualified name) or a short name.

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 Java EE bootstrapping.

  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 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 TransactionCoordinatorBuilder that builds a TransactionCoordinator that properly coordinates with JTA-based transactions.

**hibernate.jta.track_by_thread** (e.g. true (default value) or false)

A transaction can be rolled back by another thread (“tracking by thread”) and not the original application. 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**

**hibernate.jta.allowTransactionAccess**(e.g. true (default value) or false)

It allows access to the underlying org.hibernate.Transaction even when using JTA since the JPA specification prohibits this behavior.

If this configuration property is set to true, access is granted to the underlying org.hibernate.Transaction. If it’s set to false, you won’t be able to access the org.hibernate.Transaction.

The default behavior is to allow access unless the Session is bootstrapped via JPA.

24.14. Multi-tenancy settings

**hibernate.multiTenancy** (e.g. NONE (default value), SCHEMA, DATABASE, and DISCRIMINATOR (not implemented yet))

The multi-tenancy strategy in use.

**hibernate.multi_tenant_connection_provider** (e.g. true or false (default value))

Names a MultiTenantConnectionProvider implementation to use. As MultiTenantConnectionProvider is also a service, can be configured directly through the StandardServiceRegistryBuilder.

**hibernate.tenant_identifier_resolver**

Names a CurrentTenantIdentifierResolver implementation to resolve the current tenant identifier so that calling SessionFactory#openSession() would get a Session that’s connected to the right tenant.

Can be a CurrentTenantIdentifierResolver instance, CurrentTenantIdentifierResolver implementation Class object reference or a CurrentTenantIdentifierResolver implementation class name.

**hibernate.multi_tenant.datasource.identifier_for_any** (e.g. 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 the database metadata of the underlying database(s) (in situations where we do not have a tenant id, like startup processing).

24.15. Automatic schema generation

**hibernate.hbm2ddl.auto** (e.g. none (default value), create-only, drop, create, create-drop, validate, and update)

Setting to perform SchemaManagementTool actions automatically as part of the SessionFactory lifecycle. Valid options are defined by the externalHbm2ddlName value of the Action enum:

• none

  No action will be performed.

  create-only

  Database creation will be generated.

  drop

  Database dropping will be generated.

  create

  Database dropping will be generated followed by database creation.

  create-drop

  Drop the schema and recreate it on SessionFactory startup. Additionally, drop the schema on SessionFactory shutdown.

  validate

  Validate the database schema.

  update

  Update the database schema.

**javax.persistence.schema-generation.database.action** (e.g. none (default value), create-only, drop, create, create-drop, validate, and update)

Setting to perform SchemaManagementTool actions automatically as part of the SessionFactory lifecycle. Valid options are defined by the externalJpaName value of the Action enum:

• none

  No action will be performed.

  create

  Database creation will be generated.

  drop

  Database dropping will be generated.

  drop-and-create

  Database dropping will be generated followed by database creation.

**javax.persistence.schema-generation.scripts.action** (e.g. none (default value), create-only, drop, create, create-drop, validate, and update)

Setting to perform SchemaManagementTool actions writing the commands into a DDL script file. Valid options are defined by the externalJpaName value of the Action enum:

• none

  No action will be performed.

  create

  Database creation will be generated.

  drop

  Database dropping will be generated.

  drop-and-create

  Database dropping will be generated followed by database creation.

**javax.persistence.schema-generation-connection**

Allows passing a specific java.sql.Connection instance to be used by SchemaManagementTool.

**javax.persistence.database-product-name**

Specifies the name of the database provider in cases where a Connection to the underlying database is not available (aka, mainly in generating scripts). In such cases, a value for this setting must be specified.

The value of this setting is expected to match the value returned by java.sql.DatabaseMetaData#getDatabaseProductName() for the target database.

Additionally, specifying javax.persistence.database-major-version and/or javax.persistence.database-minor-version may be required to understand exactly how to generate the required schema commands.

**javax.persistence.database-major-version**

Specifies the major version of the underlying database, as would be returned by java.sql.DatabaseMetaData#getDatabaseMajorVersion for the target database.

This value is used to help more precisely determine how to perform schema generation tasks for the underlying database in cases where javax.persistence.database-product-name does not provide enough distinction.

**javax.persistence.database-minor-version**

Specifies the minor version of the underlying database, as would be returned by java.sql.DatabaseMetaData#getDatabaseMinorVersion for the target database.

This value is used to help more precisely determine how to perform schema generation tasks for the underlying database in cases where javax.persistence.database-product-name and javax.persistence.database-major-version does not provide enough distinction.

**javax.persistence.schema-generation.create-source**

Specifies whether schema generation commands for schema creation are to be determined based on object/relational mapping metadata, DDL scripts, or a combination of the two. See SourceType for valid set of values.

If no value is specified, a default is assumed as follows:

• if source scripts are specified (per javax.persistence.schema-generation.create-script-source), then script is assumed

• otherwise, metadata is assumed

**javax.persistence.schema-generation.drop-source**

Specifies whether schema generation commands for schema dropping are to be determined based on object/relational mapping metadata, DDL scripts, or a combination of the two. See SourceType for valid set of values.

If no value is specified, a default is assumed as follows:

• if source scripts are specified (per javax.persistence.schema-generation.create-script-source), then the script option is assumed

• otherwise, metadata is assumed

**javax.persistence.schema-generation.create-script-source**

Specifies the create script file as either a java.io.Reader configured for reading of the DDL script file or a string designating a file java.net.URL for the DDL script.

Hibernate historically also accepted hibernate.hbm2ddl.import_files for a similar purpose, but javax.persistence.schema-generation.create-script-source should be preferred over hibernate.hbm2ddl.import_files.

**javax.persistence.schema-generation.drop-script-source**

Specifies the drop script file as either a java.io.Reader configured for reading of the DDL script file or a string designating a file java.net.URL for the DDL script.

**javax.persistence.schema-generation.scripts.create-target**

For cases where the javax.persistence.schema-generation.scripts.action value indicates that schema creation commands should be written to DDL script file, javax.persistence.schema-generation.scripts.create-target specifies either a java.io.Writer configured for output of the DDL script or a string specifying the file URL for the DDL script.

**javax.persistence.schema-generation.scripts.drop-target**

For cases where the javax.persistence.schema-generation.scripts.action value indicates that schema dropping commands should be written to DDL script file, javax.persistence.schema-generation.scripts.drop-target specifies either a java.io.Writer configured for output of the DDL script or a string specifying the file URL for the DDL script.

**javax.persistence.hibernate.hbm2ddl.import_files** (e.g. import.sql (default value))

Comma-separated names of the optional files containing SQL DML statements executed during the SessionFactory creation. File order matters, the statements of a given file are executed before the statements of the following one.

These statements are only executed if the schema is created, meaning that hibernate.hbm2ddl.auto is set to create, create-drop, or update. javax.persistence.schema-generation.create-script-source / javax.persistence.schema-generation.drop-script-source should be preferred.

**javax.persistence.sql-load-script-source**

JPA variant of hibernate.hbm2ddl.import_files. Specifies a java.io.Reader configured for reading of the SQL load script or a string designating the file java.net.URL for the SQL load script. A “SQL load script” is a script that performs some database initialization (INSERT, etc).

**hibernate.hbm2ddl.import_files_sql_extractor**

Reference to the 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 or 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 SingleLineSqlCommandExtractor.

**hibernate.hbm2ddl.create_namespaces** (e.g. true or false (default value))

Specifies whether to automatically create the database schema/catalog also.

**javax.persistence.create-database-schemas** (e.g. true or false (default value))

The JPA variant of hibernate.hbm2ddl.create_namespaces. Specifies whether the persistence provider is to create the database schema(s) in addition to creating database objects (tables, sequences, constraints, etc). The value of this boolean property should be set to true if the persistence provider is to create schemas in the database or to generate DDL that contains “CREATE SCHEMA” commands.

If this property is not supplied (or is explicitly false), the provider should not attempt to create database schemas.

**hibernate.hbm2ddl.schema_filter_provider**

Used to specify the 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** (e.g. grouped (default value) or individually)

Setting to choose the strategy used to access the JDBC Metadata. Valid options are defined by the strategy value of the JdbcMetadaAccessStrategy enum:

• grouped

  SchemaMigrator and 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.Entitys have a corresponding mapped database tables. This strategy may require hibernate.default_schema and/or hibernate.default_catalog to be provided.

  individually

  SchemaMigrator and 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** (e.g. ;)

Identifies the delimiter to use to separate schema management statements in script outputs.

**hibernate.schema_management_tool** (e.g. A schema name)

Used to specify the SchemaManagementTool to use for performing schema management. The default is to use HibernateSchemaManagementTool.

**hibernate.synonyms** (e.g. 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.hbm2ddl.extra_physical_table_types** (e.g. 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** (e.g. DROP_RECREATE_QUIETLY, RECREATE_QUIETLY, SKIP)

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 UniqueConstraintSchemaUpdateStrategy offers the following options:

• DROP_RECREATE_QUIETLY

  Default option. Attempt to drop, then (re-)create each unique constraint. Ignore any exceptions being thrown.

  RECREATE_QUIETLY

  Attempts to (re-)create unique constraints, ignoring exceptions thrown if the constraint already existed.

  SKIP

  Does not attempt to create unique constraints on a schema update.

**hibernate.hbm2ddl.charset_name** (e.g. Charset.defaultCharset())

Defines the charset (encoding) used for all input/output schema generation resources. By default, Hibernate uses the default charset given by Charset.defaultCharset(). This configuration property allows you to override the default JVM setting so that you can specify which encoding is used when reading and writing schema generation resources (e.g. File, URL).

**hibernate.hbm2ddl.halt_on_error** (e.g. true or false (default value))

Whether the schema migration tool should halt on error, therefore terminating the bootstrap process. By default, the EntityManagerFactory or SessionFactory are created even if the schema migration throws exceptions. To prevent this default behavior, set this property value to true.

24.16. Exception handling

**hibernate.jdbc.sql_exception_converter** (e.g. fully-qualified name of class implementing SQLExceptionConverter)

The SQLExceptionConverter to use for converting SQLExceptions to Hibernate’s JDBCException hierarchy. The default is to use the configured Dialect‘s preferred SQLExceptionConverter.

**hibernate.native_exception_handling_51_compliance** (e.g. true or false (default value))

Indicates if exception handling for a SessionFactory built via Hibernate’s native bootstrapping should behave the same as native exception handling in Hibernate ORM 5.1. When set to true, HibernateException will not be wrapped or converted according to the JPA specification. This setting will be ignored for a SessionFactory built via JPA bootstrapping.

24.17. Session events

**hibernate.session.events.auto**

Fully qualified class name implementing the SessionEventListener interface.

**hibernate.session_factory.interceptor** (e.g. org.hibernate.EmptyInterceptor (default value))

Names an Interceptor implementation to be applied to every Session created by the current org.hibernate.SessionFactory.

Can reference:

• Interceptor instance

• Interceptor implementation Class object reference

• Interceptor implementation class name

**hibernate.ejb.interceptor** (e.g. hibernate.session_factory.interceptor (default value))

**hibernate.session_factory.session_scoped_interceptor** (e.g. fully-qualified class name or class reference)

Names an org.hibernate.Interceptor implementation to be applied to the org.hibernate.SessionFactory and propagated to each Session created from the SessionFactory.

This setting identifies an Interceptor implementation that is to be applied to every Session opened from the SessionFactory, but unlike hibernate.session_factory.interceptor, a unique instance of the Interceptor is used for each Session.

Can reference:

• Interceptor instance

• Interceptor implementation Class object reference

• java.util.function.Supplier instance which is used to retrieve the Interceptor instance

  Specifically, this setting cannot name an Interceptor instance.

**hibernate.ejb.interceptor.session_scoped** (e.g. fully-qualified class name or class reference)

An optional Hibernate interceptor.

The interceptor instance is specific to a given Session instance (and hence is not thread-safe) has to implement org.hibernate.Interceptor and have a no-arg constructor.

This property cannot be combined with hibernate.ejb.interceptor.

**hibernate.ejb.session_factory_observer** (e.g. fully-qualified class name or class reference)

Specifies a SessionFactoryObserver to be applied to the SessionFactory. The class must have a no-arg constructor.

**hibernate.ejb.event** (e.g. hibernate.ejb.event.pre-load = com.acme.SecurityListener,com.acme.AuditListener)

Event listener list for a given event type. The list of event listeners is a comma separated fully qualified class name list.

24.18. JMX settings

**hibernate.jmx.enabled** (e.g. true or false (default value))

Enable JMX.

**hibernate.jmx.usePlatformServer** (e.g. true or false (default value))

Uses the platform MBeanServer as returned by ManagementFactory#getPlatformMBeanServer().

**hibernate.jmx.agentId**

The agent identifier of the associated MBeanServer.

**hibernate.jmx.defaultDomain**

The domain name of the associated MBeanServer.

**hibernate.jmx.sessionFactoryName**

The SessionFactory name appended to the object name the Manageable Bean is registered with. If null, the hibernate.session_factory_name configuration value is used.

**org.hibernate.core**

The default object domain appended to the object name the Manageable Bean is registered with.

24.19. JACC settings

**hibernate.jacc.enabled** (e.g. true or false (default value))

Is JACC enabled?

**hibernate.jacc** (e.g. hibernate.jacc.allowed.org.jboss.ejb3.test.jacc.AllEntity)

The property name defines the role (e.g. allowed) and the entity class name (e.g. org.jboss.ejb3.test.jacc.AllEntity), while the property value defines the authorized actions (e.g. insert,update,read).

**hibernate.jacc_context_id**

A String identifying the policy context whose PolicyConfiguration interface is to be returned. The value passed to this parameter must not be null.

24.20. ClassLoaders properties

**hibernate.classLoaders**

Used to define a java.util.Collection<ClassLoader> or the ClassLoader instance Hibernate should use for class-loading and resource-lookups.

**hibernate.classLoader.application**

Names the ClassLoader used to load user application classes.

**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.

24.21. Bootstrap properties

**hibernate.integrator_provider** (e.g. The fully qualified name of an IntegratorProvider)

Used to define a list of Integrator which is used during the bootstrap process to integrate various services.

**hibernate.strategy_registration_provider** (e.g. The fully qualified name of an StrategyRegistrationProviderList)

Used to define a list of StrategyRegistrationProvider which is used during the bootstrap process to provide registrations of strategy selector(s).

**hibernate.type_contributors** (e.g. The fully qualified name of an TypeContributorList)

Used to define a list of TypeContributor which is used during the bootstrap process to contribute types.

**hibernate.persister.resolver** (e.g. The fully qualified name of a 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** (e.g. The fully qualified name of a 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** (e.g. true (default value) or false)

Crawl all available service bindings for an alternate registration of a given Hibernate Service.

**hibernate.metadata_builder_contributor** (e.g. The instance, the class or the fully qualified class name of a MetadataBuilderContributor)

Used to define an instance, the class or the fully qualified class name of a MetadataBuilderContributor which can be used to configure the MetadataBuilder when bootstrapping via the JPA EntityManagerFactory.

24.22. Miscellaneous properties

**hibernate.dialect_resolvers**

Names any additional DialectResolver implementations to register with the standard DialectFactory.

**hibernate.session_factory_name** (e.g. A JNDI name)

Setting used to name the Hibernate SessionFactory. Naming the SessionFactory allows for it to be properly serialized across JVMs as long as the same name is used on each JVM.

If hibernate.session_factory_name_is_jndi is set to true, this is also the name under which the SessionFactory is bound into JNDI on startup and from which it can be obtained from JNDI.

**hibernate.session_factory_name_is_jndi** (e.g. true (default value) or false)

Does the value defined by hibernate.session_factory_name represent a JNDI namespace into which the org.hibernate.SessionFactory should be bound and made accessible?

Defaults to true for backward compatibility. Set this to false if naming a SessionFactory is needed for serialization purposes, but no writable JNDI context exists in the runtime environment or if the user simply does not want JNDI to be used.

**hibernate.ejb.entitymanager_factory_name** (e.g. By default, the persistence unit name is used, otherwise a randomly generated UUID)

Internally, Hibernate keeps track of all EntityManagerFactory instances using the EntityManagerFactoryRegistry. The name is used as a key to identify a given EntityManagerFactory reference.

**hibernate.ejb.cfgfile** (e.g. hibernate.cfg.xml (default value))

XML configuration file to use to configure Hibernate.

**hibernate.ejb.discard_pc_on_close** (e.g. true or false (default value))

If true, the persistence context will be discarded (think clear() when the method is called). Otherwise, the persistence context will stay alive till the transaction completion: all objects will remain managed, and any change will be synchronized with the database (default to false, ie wait for transaction completion).

**hibernate.ejb.metamodel.population** (e.g. enabled or disabled, or ignoreUnsupported (default value))

Setting that indicates whether to build the JPA types.

Accepts three values:

• enabled

  Do the build.

  disabled

  Do not do the build.

  ignoreUnsupported

  Do the build, but ignore any non-JPA features that would otherwise result in a failure (e.g. @Any annotation).

**hibernate.jpa.static_metamodel.population** (e.g. enabled or disabled, or skipUnsupported (default value))

Setting that controls whether we seek out JPA static metamodel classes and populate them.

Accepts three values:

• enabled

  Do the population.

  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** (e.g. true or false (default value))

Defines delayed access to CDI BeanManager. Starting in 5.1 the preferred means for CDI bootstrapping is through ExtendedBeanManager.

**hibernate.resource.beans.container** (e.g. fully-qualified class name)

Identifies an explicit org.hibernate.resource.beans.container.spi.BeanContainer to be used.

Note that, for CDI-based containers, setting this is not necessary. Simply pass the BeanManager to use via javax.persistence.bean.manager and optionally specify hibernate.delay_cdi_access.

This setting is more meant to integrate non-CDI bean containers such as Spring.

**hibernate.allow_update_outside_transaction** (e.g. true or false (default value))

Setting that allows to perform update operations outside of a transaction boundary.

Accepts two values:

• true

  allows to flush an update out of a transaction

  false

  does not allow

**hibernate.collection_join_subquery** (e.g. 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** (e.g. 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.use_entity_where_clause_for_collections** (e.g., true (default) or false)

Setting controls whether an entity’s “where” clause, mapped using @Where(clause = "…​") or <entity …​ where="…​"> is taken into account when loading one-to-many or many-to-many collections of that type of entity.

**hibernate.event.merge.entity_copy_observer** (e.g. disallow (default value), allow, log (testing purpose only) or fully-qualified class name)

Setting that specifies how Hibernate will respond when multiple representations of the same persistent entity (“entity copy”) is detected while merging.

The possible values are:

• disallow

  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 EntityCopyAllowedLoggedObserver.

In addition, the application may customize the behavior by providing an implementation of 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 cascade = CascadeType.ALL. The entity state resulting from merging an entity copy will be overwritten when another entity copy is merged.

For more details, check out the Merge gotchas section.

24.23. Envers properties

**hibernate.envers.autoRegisterListeners** (e.g. 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** (e.g. 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.

24.24. Spatial properties

**hibernate.integration.spatial.enabled** (e.g. true (default value) or false)

Enable or disable the Hibernate Spatial Service integration.

**hibernate.spatial.connection_finder** (e.g. org.geolatte.geom.codec.db.oracle.DefaultConnectionFinder)

Define the fully-qualified name of class implementing the org.geolatte.geom.codec.db.oracle.ConnectionFinder interface.

24.25. Internal properties

The following configuration properties are used internally, and you shouldn’t probably have to configured them in your application.

**hibernate.enable_specj_proprietary_syntax** (e.g. 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** (e.g. 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**

Connection provider settings to be injected (a Map instance) in the currently configured connection provider.

**hibernate.jandex_index**

Names a Jandex org.jboss.jandex.Index instance to use.