Skip to content

Latest commit

 

History

History
209 lines (154 loc) · 15 KB

Database_Access.adoc

File metadata and controls

209 lines (154 loc) · 15 KB

Database Access

ConnectionProvider

As an ORM tool, probably the single most important thing you need to tell Hibernate is how to connect to your database so that it may connect on behalf of your application. This is ultimately the function of the org.hibernate.engine.jdbc.connections.spi.ConnectionProvider interface. Hibernate provides some out of the box implementations of this interface. ConnectionProvider is also an extension point so you can also use custom implementations from third parties or written yourself. The ConnectionProvider to use is defined by the hibernate.connection.provider_class setting. See the org.hibernate.cfg.AvailableSettings#CONNECTION_PROVIDER

Generally speaking, applications should not have to configure a ConnectionProvider explicitly if using one of the Hibernate-provided implementations. Hibernate will internally determine which ConnectionProvider to use based on the following algorithm:

  1. If hibernate.connection.provider_class is set, it takes precedence

  2. else if hibernate.connection.datasource is set → Using DataSources

  3. else if any setting prefixed by hibernate.c3p0. is set → Using c3p0

  4. else if any setting prefixed by hibernate.hikari. is set → Using HikariCP

  5. else if any setting prefixed by hibernate.agroal. is set → Using Agroal

  6. else if hibernate.connection.url is set → Using Hibernate’s built-in (and unsupported) pooling

  7. else → User-provided Connections

Using DataSources

Hibernate can integrate with a javax.sql.DataSource for obtaining JDBC Connections. Applications would tell Hibernate about the DataSource via the (required) hibernate.connection.datasource setting which can either specify a JNDI name or would reference the actual DataSource instance. For cases where a JNDI name is given, be sure to read JNDI.

Note

For Jakarta Persistence applications, note that hibernate.connection.datasource corresponds to jakarta.persistence.jtaDataSource or jakarta.persistence.nonJtaDataSource.

The DataSource ConnectionProvider also (optionally) accepts the hibernate.connection.username and hibernate.connection.password. If specified, the DataSource#getConnection(String username, String password) will be used. Otherwise, the no-arg form is used.

Driver Configuration

hibernate.connection.driver_class

The name of the JDBC Driver class to use

hibernate.connection.url

The JDBC connection url

hibernate.connection.*

All such setting names (except the predefined ones) will have the hibernate.connection. prefix stripped. The remaining name and the original value will be passed to the driver as a JDBC connection property

Note
 Not all properties apply to all situations. For example, if you are providing a data source, hibernate.connection.driver_class setting will not be used.

Using c3p0

Important

To use the c3p0 integration, the application must include the hibernate-c3p0 module jar (as well as its dependencies) on the classpath.

Hibernate also provides support for applications to use c3p0 connection pooling. When c3p0 support is enabled, a number of c3p0-specific configuration settings are recognized in addition to the general ones described in Driver Configuration.

Transaction isolation of the Connections is managed by the ConnectionProvider itself. See ConnectionProvider support for transaction isolation setting.

hibernate.c3p0.min_size or c3p0.minPoolSize

The minimum size of the c3p0 pool. See c3p0 minPoolSize

hibernate.c3p0.max_size or c3p0.maxPoolSize

The maximum size of the c3p0 pool. See c3p0 maxPoolSize

hibernate.c3p0.timeout or c3p0.maxIdleTime

The Connection idle time. See c3p0 maxIdleTime

hibernate.c3p0.max_statements or c3p0.maxStatements

Controls the c3p0 PreparedStatement cache size (if using). See c3p0 maxStatements

hibernate.c3p0.acquire_increment or c3p0.acquireIncrement

Number of connections c3p0 should acquire at a time when the pool is exhausted. See c3p0 acquireIncrement

hibernate.c3p0.idle_test_period or c3p0.idleConnectionTestPeriod

Idle time before a c3p0 pooled connection is validated. See c3p0 idleConnectionTestPeriod

hibernate.c3p0.initialPoolSize

The initial c3p0 pool size. If not specified, default is to use the min pool size. See c3p0 initialPoolSize

Any other settings prefixed with hibernate.c3p0.

Will have the hibernate. portion stripped and be passed to c3p0.

Any other settings prefixed with c3p0.

Get passed to c3p0 as is. See c3p0 configuration

Using HikariCP

Important

To use the HikariCP this integration, the application must include the hibernate-hikari module jar (as well as its dependencies) on the classpath.

Hibernate also provides support for applications to use HikariCP connection pool.

Set all of your Hikari settings in Hibernate prefixed by hibernate.hikari. and this ConnectionProvider will pick them up and pass them along to Hikari. Additionally, this ConnectionProvider will pick up the following Hibernate-specific properties and map them to the corresponding Hikari ones (any hibernate.hikari. prefixed ones have precedence):

hibernate.connection.driver_class

Mapped to Hikari’s driverClassName setting

hibernate.connection.url

Mapped to Hikari’s jdbcUrl setting

hibernate.connection.username

Mapped to Hikari’s username setting

hibernate.connection.password

Mapped to Hikari’s password setting

hibernate.connection.isolation

Mapped to Hikari’s transactionIsolation setting. See ConnectionProvider support for transaction isolation setting. Note that Hikari only supports JDBC standard isolation levels (apparently).

hibernate.connection.autocommit

Mapped to Hikari’s autoCommit setting

Using Agroal

Important

To use the Agroal integration, the application must include the hibernate-agroal module jar (as well as its dependencies) on the classpath.

Hibernate also provides support for applications to use Agroal connection pool.

Set all of your Agroal settings in Hibernate prefixed by hibernate.agroal. and this ConnectionProvider will pick them up and pass them along to Agroal connection pool. Additionally, this ConnectionProvider will pick up the following Hibernate-specific properties and map them to the corresponding Agroal ones (any hibernate.agroal. prefixed ones have precedence):

hibernate.connection.driver_class

Mapped to Agroal’s driverClassName setting

hibernate.connection.url

Mapped to Agroal’s jdbcUrl setting

hibernate.connection.username

Mapped to Agroal’s principal setting

hibernate.connection.password

Mapped to Agroal’s credential setting

hibernate.connection.isolation

Mapped to Agroal’s jdbcTransactionIsolation setting. See ConnectionProvider support for transaction isolation setting.

hibernate.connection.autocommit

Mapped to Agroal’s autoCommit setting

Using Hibernate’s built-in (and unsupported) pooling

Important

The built-in connection pool is not supported for use in a production system.

This section is here just for completeness.

User-provided Connections

It is possible to use Hibernate by simply passing a Connection to use to the Session when the Session is opened. This usage is discouraged and not discussed here.

ConnectionProvider support for transaction isolation setting

All the provided ConnectionProvider implementations, apart from DataSourceConnectionProvider, support consistent setting of transaction isolation for all Connections obtained from the underlying pool. The value for hibernate.connection.isolation can be specified in one of 3 formats:

  • the integer value accepted at the JDBC level.

  • the name of the java.sql.Connection constant field representing the isolation you would like to use. For example, TRANSACTION_REPEATABLE_READ for java.sql.Connection#TRANSACTION_REPEATABLE_READ. Note that this is only supported for JDBC standard isolation levels, not for isolation levels specific to a particular JDBC driver.

  • a short-name version of the java.sql.Connection constant field without the TRANSACTION_ prefix. For example, REPEATABLE_READ for java.sql.Connection#TRANSACTION_REPEATABLE_READ. Again, this is only supported for JDBC standard isolation levels, not for isolation levels specific to a particular JDBC driver.

Connection handling

The connection handling mode is defined by the PhysicalConnectionHandlingMode enumeration which provides the following strategies:

IMMEDIATE_ACQUISITION_AND_HOLD

The Connection will be acquired as soon as the Session is opened and held until the Session is closed.

DELAYED_ACQUISITION_AND_HOLD

The Connection will be acquired as soon as it is needed and then held until the Session is closed.

DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT

The Connection will be acquired as soon as it is needed and will be released after each statement is executed.

DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION

The Connection will be acquired as soon as it is needed and will be released after each transaction is completed.

If you don’t want to use the default connection handling mode, you can specify a connection handling mode via the hibernate.connection.handling_mode configuration property. For more details, check out the Database connection properties section.

Transaction type and connection handling

By default, the connection handling mode is given by the underlying transaction coordinator. There are two types of transactions: RESOURCE_LOCAL (which involves a single database Connection and the transaction is controlled via the commit and rollback Connection methods) and JTA (which may involve multiple resources including database connections, JMS queues, etc).

RESOURCE_LOCAL transaction connection handling

For RESOURCE_LOCAL transactions, the connection handling mode is DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION meaning that the database connection is acquired when needed and released after the current running transaction is either committed or rolled back.

However, because Hibernate needs to make sure that the default autocommit mode is disabled on the JDBC Connection when starting a new transaction, the Connection is acquired and the autocommit mode is set to false.

Note

If you are using a connection pool DataSource that already disabled the autocommit mode for every pooled Connection, you should set the hibernate.connection.provider_disables_autocommit to true and the database connection acquisition will be, indeed, delayed until Hibernate needs to execute the first SQL statement.
JTA transaction connection handling

For JTA transactions, the connection handling mode is DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT meaning that the database connection is acquired when needed and released after each statement execution.

The reason for releasing the database connection after statement execution is because some Java EE application servers report a connection leak when a method call goes from one EJB to another. However, even if the JDBC Connection is released to the pool, the Connection is still allocated to the current executing Thread, hence when executing a subsequent statement in the current running transaction, the same Connection object reference will be obtained from the pool.

Note

If the Java EE application server or JTA transaction manager supports switching from one EJB to another while the transaction gets propagated from the outer EJB to the inner one, and no connection leak false positive is being reported, then you should consider switching to DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION via the hibernate.connection.handling_mode configuration property.

User-provided connections

If the current Session was created using the SessionBuilder and a JDBC Connection was provided via the SessionBuilder#connection method, then the user-provided Connection is going to be used, and the connection handling mode will be IMMEDIATE_ACQUISITION_AND_HOLD.

Therefore for user-provided connection, the connection is acquired right away and held until the current Session is closed, without being influenced by the Jakarta Persistence or Hibernate transaction context.

Database Dialect

Although SQL is now relatively standardized—much more so than in the past—it’s still the case that each database vendor implements a different dialect of SQL that, while overlapping significantly with ANSI SQL, forms neither a subset, nor a superset, of the standard.

Hibernate abstracts over variations between dialects of SQL via the class org.hibernate.dialect.Dialect.

  • There’s a subclass of Dialect for each supported relational database in the package org.hibernate.dialect.

  • Additional community-supported Dialects are available in the separate module hibernate-community-dialects.

In Hibernate 6, it’s no longer necessary to explicitly specify a dialect using the configuration property hibernate.dialect, and so setting that property is now discouraged. (An exception is the case of custom user-written Dialects.)