Package org.hibernate.engine.jdbc.connections.spi

Interface MultiTenantConnectionProvider<T>

Type Parameters:
T - The tenant identifier type
All Superinterfaces:
Serializable, Service, Wrapped
All Known Implementing Classes:
AbstractDataSourceBasedMultiTenantConnectionProviderImpl, AbstractMultiTenantConnectionProvider, DataSourceBasedMultiTenantConnectionProviderImpl
public interface MultiTenantConnectionProvider<T> extends Service, Wrapped
A specialized Connection provider contract used when the application is using multi-tenancy support requiring tenant-aware connections.

A MultiTenantConnectionProvider may be selected using the configuration property "hibernate.multi_tenant_connection_provider".

An application usually implements its own custom MultiTenantConnectionProvider by subclassing AbstractMultiTenantConnectionProvider.

Support for read-only replicas may be implemented by overriding the operations getReadOnlyConnection(T) and releaseReadOnlyConnection(T, java.sql.Connection).

See Also:

  • Method Details

    • getAnyConnection

      Connection getAnyConnection() throws SQLException
      Allows access to the database metadata of the underlying database(s) in situations where we do not have a tenant id (like startup processing, for example).
      Returns:
      The database metadata.
      Throws:
      SQLException - Indicates a problem opening a connection

    • releaseAnyConnection

      void releaseAnyConnection(Connection connection) throws SQLException
      Release a connection obtained from getAnyConnection()
      Parameters:
      connection - The JDBC connection to release
      Throws:
      SQLException - Indicates a problem closing the connection

    • getConnection

      Connection getConnection(T tenantIdentifier) throws SQLException
      Obtains a connection for use according to the underlying strategy of this provider.
      Parameters:
      tenantIdentifier - The identifier of the tenant for which to get a connection
      Returns:
      The obtained JDBC connection
      Throws:
      SQLException - Indicates a problem opening a connection
      HibernateException - Indicates a problem obtaining a connection

    • getReadOnlyConnection

      @Incubating default Connection getReadOnlyConnection(T tenantIdentifier) throws SQLException
      Obtains a connection to a read-only replica for use according to the underlying strategy of this provider.
      Parameters:
      tenantIdentifier - The identifier of the tenant for which to get a connection
      Returns:
      The obtained JDBC connection
      Throws:
      SQLException - Indicates a problem opening a connection
      HibernateException - Indicates a problem obtaining a connection
      Since:
      7.2
      Implementation Note:
      This default implementation simply calls getConnection(Object), which returns a connection to a writable replica. If this operation is overridden to return a connection to a distinct read-only replica, the matching operation releaseReadOnlyConnection(Object, Connection) must also be overridden.

    • releaseConnection

      void releaseConnection(T tenantIdentifier, Connection connection) throws SQLException
      Release a connection from Hibernate use.
      Parameters:
      tenantIdentifier - The identifier of the tenant.
      connection - The JDBC connection to release
      Throws:
      SQLException - Indicates a problem closing the connection
      HibernateException - Indicates a problem releasing a connection

    • releaseReadOnlyConnection

      @Incubating default void releaseReadOnlyConnection(T tenantIdentifier, Connection connection) throws SQLException
      Release a connection to a read-only replica from Hibernate use.
      Parameters:
      tenantIdentifier - The identifier of the tenant.
      connection - The JDBC connection to release
      Throws:
      SQLException - Indicates a problem closing the connection
      HibernateException - Indicates a problem releasing a connection
      Since:
      7.2
      Implementation Note:
      This default implementation simply calls releaseConnection(Object, Connection). If getReadOnlyConnection(Object) is overridden to return a connection to a distinct read-only replica, this operation must also be overridden.

    • supportsAggressiveRelease

      boolean supportsAggressiveRelease()
      Does this connection provider support aggressive release of JDBC connections and later re-acquisition of those connections if needed?

      This is used in conjunction with ConnectionReleaseMode.AFTER_STATEMENT to aggressively release JDBC connections. However, the configured ConnectionProvider must support re-acquisition of the same underlying connection for that semantic to work.

      Typically, this is only true in managed environments where a container tracks connections by transaction or thread.

      Note that JTA semantic depends on the fact that the underlying connection provider does support aggressive release.

      Returns:
      true if aggressive releasing is supported; false otherwise.

    • handlesConnectionSchema

      @Incubating default boolean handlesConnectionSchema()
      Does this connection provider correctly set the schema of the returned JDBC connections?
      Returns:
      true if the connection provider handles this; false if the client should set the schema
      Implementation Note:
      If necessary, a ConnectionProvider may call MultiTenancy.getTenantSchemaMapper(java.util.Map<java.lang.String, java.lang.Object>, org.hibernate.boot.registry.StandardServiceRegistry) to obtain the TenantSchemaMapper.

    • handlesConnectionReadOnly

      @Incubating default boolean handlesConnectionReadOnly()
      Does this connection provider correctly set the read-only mode of the returned JDBC connections?
      Returns:
      true if the connection provider handles this; false if the client should set the read-only mode

    • getDatabaseConnectionInfo

      default DatabaseConnectionInfo getDatabaseConnectionInfo(Dialect dialect)