There are a number of other properties that control the behaviour of Hibernate at runtime. All are optional and have reasonable default values.
Warning: some of these properties are "system-level" only. System-level properties can
be set only via java -Dproperty=value or hibernate.properties. They
may not be set by the other techniques described above.
Table 3.3. Hibernate Configuration Properties
| Property name | Purpose |
|---|---|
| hibernate.dialect |
The classname of a Hibernate org.hibernate.dialect.Dialect which
allows Hibernate to generate SQL optimized for a particular relational database.
eg.
In most cases Hibernate will actually be able to chose the correct
|
| hibernate.show_sql |
Write all SQL statements to console. This is an alternative
to setting the log category org.hibernate.SQL
to debug.
eg.
|
| hibernate.format_sql |
Pretty print the SQL in the log and console.
eg.
|
| hibernate.default_schema |
Qualify unqualified table names with the given schema/tablespace
in generated SQL.
eg.
|
| hibernate.default_catalog |
Qualify unqualified table names with the given catalog
in generated SQL.
eg.
|
| hibernate.session_factory_name |
The org.hibernate.SessionFactory will be automatically
bound to this name in JNDI after it has been created.
eg.
|
| hibernate.max_fetch_depth |
Set a maximum "depth" for the outer join fetch tree
for single-ended associations (one-to-one, many-to-one).
A 0 disables default outer join fetching.
eg.
recommended values between |
| hibernate.default_batch_fetch_size |
Set a default size for Hibernate batch fetching of associations.
eg.
recommended values |
| hibernate.default_entity_mode |
Set a default mode for entity representation for all sessions
opened from this SessionFactory
|
| hibernate.order_updates |
Force Hibernate to order SQL updates by the primary key value
of the items being updated. This will result in fewer transaction
deadlocks in highly concurrent systems.
eg.
|
| hibernate.generate_statistics |
If enabled, Hibernate will collect statistics useful for
performance tuning.
eg.
|
| hibernate.use_identifier_rollback |
If enabled, generated identifier properties will be
reset to default values when objects are deleted.
eg.
|
| hibernate.use_sql_comments |
If turned on, Hibernate will generate comments inside the SQL, for
easier debugging, defaults to false.
eg.
|
Table 3.4. Hibernate JDBC and Connection Properties
| Property name | Purpose |
|---|---|
| hibernate.jdbc.fetch_size |
A non-zero value determines the JDBC fetch size (calls
Statement.setFetchSize()).
|
| hibernate.jdbc.batch_size |
A non-zero value enables use of JDBC2 batch updates by Hibernate.
eg.
recommended values between |
| hibernate.jdbc.batch_versioned_data |
Set this property to true if your JDBC driver returns
correct row counts from executeBatch() (it is usually
safe to turn this option on). Hibernate will then use batched DML for
automatically versioned data. Defaults to false.
eg.
|
| hibernate.jdbc.factory_class |
Select a custom org.hibernate.jdbc.Batcher. Most applications
will not need this configuration property.
eg.
|
| hibernate.jdbc.use_scrollable_resultset |
Enables use of JDBC2 scrollable resultsets by Hibernate.
This property is only necessary when using user supplied
JDBC connections, Hibernate uses connection metadata otherwise.
eg.
|
| hibernate.jdbc.use_streams_for_binary |
Use streams when writing/reading binary or serializable
types to/from JDBC. *system-level property*
eg.
|
| hibernate.jdbc.use_get_generated_keys |
Enable use of JDBC3 PreparedStatement.getGeneratedKeys()
to retrieve natively generated keys after insert. Requires JDBC3+ driver
and JRE1.4+, set to false if your driver has problems with the Hibernate
identifier generators. By default, tries to determine the driver capabilities
using connection metadata.
eg.
|
| hibernate.connection.provider_class |
The classname of a custom org.hibernate.connection.ConnectionProvider
which provides JDBC connections to Hibernate.
eg.
|
| hibernate.connection.isolation |
Set the JDBC transaction isolation level. Check java.sql.Connection
for meaningful values but note that most databases do not support all isolation levels and some
define additional, non-standard isolations.
eg.
|
| hibernate.connection.autocommit |
Enables autocommit for JDBC pooled connections (not recommended).
eg.
|
| hibernate.connection.release_mode |
Specify when Hibernate should release JDBC connections. By default,
a JDBC connection is held until the session is explicitly closed or
disconnected. For an application server JTA datasource, you should use
after_statement to aggressively release connections
after every JDBC call. For a non-JTA connection, it often makes sense to
release the connection at the end of each transaction, by using
after_transaction. auto will
choose after_statement for the JTA and CMT transaction
strategies and after_transaction for the JDBC
transaction strategy.
eg.
Note that this setting only affects |
| hibernate.connection.<propertyName> |
Pass the JDBC property <propertyName>
to DriverManager.getConnection().
|
| hibernate.jndi.<propertyName> |
Pass the property <propertyName> to
the JNDI InitialContextFactory.
|
Table 3.5. Hibernate Cache Properties
| Property name | Purpose |
|---|---|
hibernate.cache.provider_class
|
The classname of a custom CacheProvider.
eg.
|
hibernate.cache.use_minimal_puts
|
Optimize second-level cache operation to minimize writes, at the
cost of more frequent reads. This setting is most useful for
clustered caches and, in Hibernate3, is enabled by default for
clustered cache implementations.
eg.
|
hibernate.cache.use_query_cache
|
Enable the query cache, individual queries still have to be set cachable.
eg.
|
hibernate.cache.use_second_level_cache
|
May be used to completely disable the second level cache, which is enabled
by default for classes which specify a <cache>
mapping.
eg.
|
hibernate.cache.query_cache_factory
|
The classname of a custom QueryCache interface,
defaults to the built-in StandardQueryCache.
eg.
|
hibernate.cache.region_prefix
|
A prefix to use for second-level cache region names.
eg.
|
hibernate.cache.use_structured_entries
|
Forces Hibernate to store data in the second-level cache
in a more human-friendly format.
eg.
|
Table 3.6. Hibernate Transaction Properties
| Property name | Purpose |
|---|---|
hibernate.transaction.factory_class
|
The classname of a TransactionFactory
to use with Hibernate Transaction API
(defaults to JDBCTransactionFactory).
eg.
|
jta.UserTransaction
|
A JNDI name used by JTATransactionFactory to
obtain the JTA UserTransaction from the
application server.
eg.
|
hibernate.transaction.manager_lookup_class
|
The classname of a TransactionManagerLookup
- required when JVM-level caching is enabled or when using hilo
generator in a JTA environment.
eg.
|
hibernate.transaction.flush_before_completion
|
If enabled, the session will be automatically flushed during the
before completion phase of the transaction. Built-in and
automatic session context management is preferred, see
Section 2.5, “Contextual Sessions”.
eg.
|
hibernate.transaction.auto_close_session
|
If enabled, the session will be automatically closed during the
after completion phase of the transaction. Built-in and
utomatic session context management is preferred, see
Section 2.5, “Contextual Sessions”.
eg.
|
Table 3.7. Miscellaneous Properties
| Property name | Purpose |
|---|---|
hibernate.current_session_context_class
|
Supply a (custom) strategy for the scoping of the "current"
Session. See
Section 2.5, “Contextual Sessions” for more
information about the built-in strategies.
eg.
|
hibernate.query.factory_class
|
Chooses the HQL parser implementation.
eg.
|
hibernate.query.substitutions
|
Mapping from tokens in Hibernate queries to SQL tokens
(tokens might be function or literal names, for example).
eg.
|
hibernate.hbm2ddl.auto
|
Automatically validate or export schema DDL to the database
when the SessionFactory is created. With
create-drop, the database schema will be
dropped when the SessionFactory is closed
explicitly.
eg.
|
hibernate.cglib.use_reflection_optimizer
|
Enables use of CGLIB instead of runtime reflection (System-level
property). Reflection can sometimes be useful when troubleshooting,
note that Hibernate always requires CGLIB even if you turn off the
optimizer. You can not set this property in hibernate.cfg.xml.
eg.
|
You should always set the hibernate.dialect property to the correct
org.hibernate.dialect.Dialect subclass for your database. If you
specify a dialect, Hibernate will use sensible defaults for some of the
other properties listed above, saving you the effort of specifying them manually.
Table 3.8. Hibernate SQL Dialects (hibernate.dialect)
| RDBMS | Dialect |
|---|---|
| DB2 | org.hibernate.dialect.DB2Dialect |
| DB2 AS/400 | org.hibernate.dialect.DB2400Dialect |
| DB2 OS390 | org.hibernate.dialect.DB2390Dialect |
| PostgreSQL | org.hibernate.dialect.PostgreSQLDialect |
| MySQL | org.hibernate.dialect.MySQLDialect |
| MySQL with InnoDB | org.hibernate.dialect.MySQLInnoDBDialect |
| MySQL with MyISAM | org.hibernate.dialect.MySQLMyISAMDialect |
| Oracle (any version) | org.hibernate.dialect.OracleDialect |
| Oracle 9i/10g | org.hibernate.dialect.Oracle9Dialect |
| Sybase | org.hibernate.dialect.SybaseDialect |
| Sybase Anywhere | org.hibernate.dialect.SybaseAnywhereDialect |
| Microsoft SQL Server | org.hibernate.dialect.SQLServerDialect |
| SAP DB | org.hibernate.dialect.SAPDBDialect |
| Informix | org.hibernate.dialect.InformixDialect |
| HypersonicSQL | org.hibernate.dialect.HSQLDialect |
| Ingres | org.hibernate.dialect.IngresDialect |
| Progress | org.hibernate.dialect.ProgressDialect |
| Mckoi SQL | org.hibernate.dialect.MckoiDialect |
| Interbase | org.hibernate.dialect.InterbaseDialect |
| Pointbase | org.hibernate.dialect.PointbaseDialect |
| FrontBase | org.hibernate.dialect.FrontbaseDialect |
| Firebird | org.hibernate.dialect.FirebirdDialect |
If your database supports ANSI, Oracle or Sybase style outer joins, outer join
fetching will often increase performance by limiting the number of round
trips to and from the database (at the cost of possibly more work performed by
the database itself). Outer join fetching allows a whole graph of objects connected
by many-to-one, one-to-many, many-to-many and one-to-one associations to be retrieved
in a single SQL SELECT.
Outer join fetching may be disabled globally by setting
the property hibernate.max_fetch_depth to 0.
A setting of 1 or higher enables outer join fetching for
one-to-one and many-to-one associations which have been mapped with
fetch="join".
See Section 19.1, “Fetching strategies” for more information.
Oracle limits the size of byte arrays that may
be passed to/from its JDBC driver. If you wish to use large instances of
binary or serializable type, you should
enable hibernate.jdbc.use_streams_for_binary.
This is a system-level setting only.
The properties prefixed by hibernate.cache
allow you to use a process or cluster scoped second-level cache system
with Hibernate. See the Section 19.2, “The Second Level Cache” for
more details.
You may define new Hibernate query tokens using hibernate.query.substitutions.
For example:
hibernate.query.substitutions true=1, false=0
would cause the tokens true and false to be translated to
integer literals in the generated SQL.
hibernate.query.substitutions toLowercase=LOWER
would allow you to rename the SQL LOWER function.
If you enable hibernate.generate_statistics, Hibernate will
expose a number of metrics that are useful when tuning a running system via
SessionFactory.getStatistics(). Hibernate can even be configured
to expose these statistics via JMX. Read the Javadoc of the interfaces in
org.hibernate.stats for more information.