HHH-19708 prototype support for read/write replicas

1. allow a session to be created in a read-only mode
2. pass that mode through to the MultiTenantConnectionProvider

Author: gavinking

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -440,6 +440,8 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *
 	 * @param readOnly {@code true}, the default for loaded entities/proxies is read-only;
 	 *				 {@code false}, the default for loaded entities/proxies is modifiable
+	 * @throws SessionException if the session was originally
+	 *         {@linkplain SessionBuilder#readOnly created in read-only mode}
 	 */
 	void setDefaultReadOnly(boolean readOnly);
 

hibernate-core/src/main/java/org/hibernate/SessionBuilder.java

@@ -165,6 +165,29 @@ public interface SessionBuilder {
 	 */
 	SessionBuilder tenantIdentifier(Object tenantIdentifier);
 
+	/**
+	 * Specify a {@linkplain Session#isDefaultReadOnly read-only mode}
+	 * for the session.
+	 * <p>
+	 * If read/write replication is in use, then:
+	 * <ul>
+	 * <li>a read-only session will connect to a read-only replica, but
+	 * <li>a non-read-only session will connect to a writable replica.
+	 * </ul>
+	 * <p>
+	 * If a session is created in read-only mode, then it cannot be
+	 * changed to read-write mode, and any call to
+	 * {@link Session#setDefaultReadOnly(boolean)} with fail. On the
+	 * other hand, if a session is created in read-write mode, then it
+	 * may later be switched to read-only mode, but all database access
+	 * is directed to the writable replica.
+	 *
+	 * @return {@code this}, for method chaining
+	 * @since 7.2
+	 */
+	@Incubating
+	SessionBuilder readOnly(boolean readOnly);
+
 	/**
 	 * Add one or more {@link SessionEventListener} instances to the list of
 	 * listeners for the new session to be built.

hibernate-core/src/main/java/org/hibernate/StatelessSessionBuilder.java

@@ -41,7 +41,7 @@ public interface StatelessSessionBuilder {
 	 * @return {@code this}, for method chaining
 	 * @deprecated Use {@link #tenantIdentifier(Object)} instead
 	 */
-	@Deprecated(forRemoval = true)
+	@Deprecated(since = "6.4", forRemoval = true)
 	StatelessSessionBuilder tenantIdentifier(String tenantIdentifier);
 
 	/**
@@ -54,13 +54,28 @@ public interface StatelessSessionBuilder {
 	 */
 	StatelessSessionBuilder tenantIdentifier(Object tenantIdentifier);
 
+	/**
+	 * Specify a read-only mode for the stateless session.
+	 * <p>
+	 * If read/write replication is in use, then:
+	 * <ul>
+	 * <li>a read-only session will connect to a read-only replica, but
+	 * <li>a non-read-only session will connect to a writable replica.
+	 * </ul>
+	 *
+	 * @return {@code this}, for method chaining
+	 * @since 7.2
+	 */
+	@Incubating
+	StatelessSessionBuilder readOnly(boolean readOnly);
+
 	/**
 	 * Applies the given statement inspection function to the session.
 	 *
 	 * @param operator An operator which accepts a SQL string, returning
 	 *                 a processed SQL string to be used by Hibernate
-	 *                 instead of the given original SQL. Alternatively.
-	 *                 the operator may work by side effect, and simply
+	 *                 instead of the given original SQL. Alternatively,
+	 *                 the operator may work by side effect and simply
 	 *                 return the original SQL.
 	 *
 	 * @return {@code this}, for method chaining

hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/MultiTenantConnectionProvider.java

@@ -57,21 +57,55 @@ public interface MultiTenantConnectionProvider<T> extends Service, Wrapped {
 	 * @return The obtained JDBC connection
 	 *
 	 * @throws SQLException Indicates a problem opening a connection
-	 * @throws org.hibernate.HibernateException Indicates a problem otherwise obtaining a connection.
+	 * @throws org.hibernate.HibernateException Indicates a problem obtaining a connection
 	 */
 	Connection getConnection(T tenantIdentifier) throws SQLException;
 
+	/**
+	 * Obtains a connection to a read-only replica for use according to the underlying
+	 * strategy of this provider.
+	 *
+	 * @param tenantIdentifier The identifier of the tenant for which to get a connection
+	 *
+	 * @return The obtained JDBC connection
+	 *
+	 * @throws SQLException Indicates a problem opening a connection
+	 * @throws org.hibernate.HibernateException Indicates a problem obtaining a connection
+	 *
+	 * @since 7.2
+	 */
+	default Connection getReadOnlyConnection(T tenantIdentifier)
+			throws SQLException {
+		throw new UnsupportedOperationException( "No read-only replica is available" );
+	}
+
 	/**
 	 * Release a connection from Hibernate use.
 	 *
 	 * @param connection The JDBC connection to release
 	 * @param tenantIdentifier The identifier of the tenant.
 	 *
 	 * @throws SQLException Indicates a problem closing the connection
-	 * @throws org.hibernate.HibernateException Indicates a problem otherwise releasing a connection.
+	 * @throws org.hibernate.HibernateException Indicates a problem releasing a connection
 	 */
 	void releaseConnection(T tenantIdentifier, Connection connection) throws SQLException;
 
+	/**
+	 * Release a connection to a read-only replica from Hibernate use.
+	 *
+	 * @param connection The JDBC connection to release
+	 * @param tenantIdentifier The identifier of the tenant.
+	 *
+	 * @throws SQLException Indicates a problem closing the connection
+	 * @throws org.hibernate.HibernateException Indicates a problem releasing a connection
+	 *
+	 * @since 7.2
+	 */
+	default void releaseReadOnlyConnection(T tenantIdentifier, Connection connection)
+			throws SQLException {
+		throw new UnsupportedOperationException( "No read-only replica is available" );
+	}
+
 	/**
 	 * Does this connection provider support aggressive release of JDBC connections and later
 	 * re-acquisition of those connections if needed?

hibernate-core/src/main/java/org/hibernate/internal/AbstractSharedSessionContract.java

@@ -161,6 +161,7 @@ public abstract class AbstractSharedSessionContract implements SharedSessionCont
 	private final Interceptor interceptor;
 
 	private final Object tenantIdentifier;
+	private final boolean readOnly;
 	private final TimeZone jdbcTimeZone;
 
 	// mutable state
@@ -190,6 +191,7 @@ public AbstractSharedSessionContract(SessionFactoryImpl factory, SessionCreation
 
 		cacheTransactionSynchronization = factory.getCache().getRegionFactory().createTransactionContext( this );
 		tenantIdentifier = getTenantId( factoryOptions, options );
+		readOnly = options.isReadOnly();
 		interceptor = interpret( options.getInterceptor() );
 		jdbcTimeZone = options.getJdbcTimeZone();
 		sessionEventsManager = createSessionEventsManager( factoryOptions, options );
@@ -296,9 +298,13 @@ private static Object getTenantId( SessionFactoryOptions factoryOptions, Session
 		return tenantIdentifier;
 	}
 
+	boolean isReadOnly() {
+		return readOnly;
+	}
+
 	private static SessionEventListenerManager createSessionEventsManager(
 			SessionFactoryOptions factoryOptions, SessionCreationOptions options) {
-		final List<SessionEventListener> customListeners = options.getCustomSessionEventListener();
+		final var customListeners = options.getCustomSessionEventListener();
 		return customListeners == null
 				? new SessionEventListenerManagerImpl( factoryOptions.buildSessionEventListeners() )
 				: new SessionEventListenerManagerImpl( customListeners );
@@ -694,6 +700,7 @@ public JdbcConnectionAccess getJdbcConnectionAccess() {
 				// we're using datasource-based multitenancy
 				jdbcConnectionAccess = new ContextualJdbcConnectionAccess(
 						tenantIdentifier,
+						readOnly,
 						sessionEventsManager,
 						factory.multiTenantConnectionProvider,
 						this

hibernate-core/src/main/java/org/hibernate/internal/ContextualJdbcConnectionAccess.java

@@ -13,25 +13,26 @@
 import org.hibernate.engine.jdbc.connections.spi.JdbcConnectionAccess;
 import org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
-import org.hibernate.event.monitor.spi.EventMonitor;
-import org.hibernate.event.monitor.spi.DiagnosticEvent;
 
 /**
  * @author Steve Ebersole
  */
 public class ContextualJdbcConnectionAccess implements JdbcConnectionAccess, Serializable {
 	private final Object tenantIdentifier;
+	private final boolean readOnly;
 	private final SessionEventListener listener;
 	private final MultiTenantConnectionProvider<Object> connectionProvider;
 	private final SharedSessionContractImplementor session;
 
 
 	public ContextualJdbcConnectionAccess(
 			Object tenantIdentifier,
+			boolean readOnly,
 			SessionEventListener listener,
 			MultiTenantConnectionProvider<Object> connectionProvider,
 			SharedSessionContractImplementor session) {
 		this.tenantIdentifier = tenantIdentifier;
+		this.readOnly = readOnly;
 		this.listener = listener;
 		this.connectionProvider = connectionProvider;
 		this.session = session;
@@ -43,11 +44,13 @@ public Connection obtainConnection() throws SQLException {
 			throw new HibernateException( "Tenant identifier required" );
 		}
 
-		final EventMonitor eventMonitor = session.getEventMonitor();
-		final DiagnosticEvent connectionAcquisitionEvent = eventMonitor.beginJdbcConnectionAcquisitionEvent();
+		final var eventMonitor = session.getEventMonitor();
+		final var connectionAcquisitionEvent = eventMonitor.beginJdbcConnectionAcquisitionEvent();
 		try {
 			listener.jdbcConnectionAcquisitionStart();
-			return connectionProvider.getConnection( tenantIdentifier );
+			return readOnly
+					? connectionProvider.getReadOnlyConnection( tenantIdentifier )
+					: connectionProvider.getConnection( tenantIdentifier );
 		}
 		finally {
 			eventMonitor.completeJdbcConnectionAcquisitionEvent( connectionAcquisitionEvent, session, tenantIdentifier );
@@ -61,11 +64,16 @@ public void releaseConnection(Connection connection) throws SQLException {
 			throw new HibernateException( "Tenant identifier required" );
 		}
 
-		final EventMonitor eventMonitor = session.getEventMonitor();
-		final DiagnosticEvent connectionReleaseEvent = eventMonitor.beginJdbcConnectionReleaseEvent();
+		final var eventMonitor = session.getEventMonitor();
+		final var connectionReleaseEvent = eventMonitor.beginJdbcConnectionReleaseEvent();
 		try {
 			listener.jdbcConnectionReleaseStart();
-			connectionProvider.releaseConnection( tenantIdentifier, connection );
+			if ( readOnly ) {
+				connectionProvider.releaseReadOnlyConnection( tenantIdentifier, connection );
+			}
+			else {
+				connectionProvider.releaseConnection( tenantIdentifier, connection );
+			}
 		}
 		finally {
 			eventMonitor.completeJdbcConnectionReleaseEvent( connectionReleaseEvent, session, tenantIdentifier );

hibernate-core/src/main/java/org/hibernate/internal/NonContextualJdbcConnectionAccess.java

@@ -37,8 +37,8 @@ public NonContextualJdbcConnectionAccess(
 
 	@Override
 	public Connection obtainConnection() throws SQLException {
-		final EventMonitor eventMonitor = session.getEventMonitor();
-		final DiagnosticEvent connectionAcquisitionEvent = eventMonitor.beginJdbcConnectionAcquisitionEvent();
+		final var eventMonitor = session.getEventMonitor();
+		final var connectionAcquisitionEvent = eventMonitor.beginJdbcConnectionAcquisitionEvent();
 		try {
 			listener.jdbcConnectionAcquisitionStart();
 			return connectionProvider.getConnection();
@@ -51,8 +51,8 @@ public Connection obtainConnection() throws SQLException {
 
 	@Override
 	public void releaseConnection(Connection connection) throws SQLException {
-		final EventMonitor eventMonitor = session.getEventMonitor();
-		final DiagnosticEvent connectionReleaseEvent = eventMonitor.beginJdbcConnectionReleaseEvent();
+		final var eventMonitor = session.getEventMonitor();
+		final var connectionReleaseEvent = eventMonitor.beginJdbcConnectionReleaseEvent();
 		try {
 			listener.jdbcConnectionReleaseStart();
 			connectionProvider.closeConnection( connection );

hibernate-core/src/main/java/org/hibernate/internal/SessionCreationOptions.java

@@ -46,6 +46,8 @@ public interface SessionCreationOptions {
 
 	Object getTenantIdentifierValue();
 
+	boolean isReadOnly();
+
 	boolean isIdentifierRollbackEnabled();
 
 	TimeZone getJdbcTimeZone();

hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java

@@ -34,7 +34,6 @@
 import org.hibernate.HibernateException;
 import org.hibernate.Interceptor;
 import org.hibernate.Session;
-import org.hibernate.SessionBuilder;
 import org.hibernate.SessionEventListener;
 import org.hibernate.SessionFactory;
 import org.hibernate.SessionFactoryObserver;
@@ -1130,6 +1129,7 @@ public static class SessionBuilderImpl implements SessionBuilderImplementor, Ses
 		private boolean autoClose;
 		private boolean autoClear;
 		private Object tenantIdentifier;
+		private boolean readOnly;
 		private boolean identifierRollback;
 		private TimeZone jdbcTimeZone;
 		private boolean explicitNoInterceptor;
@@ -1238,6 +1238,11 @@ public Object getTenantIdentifierValue() {
 			return tenantIdentifier;
 		}
 
+		@Override
+		public boolean isReadOnly() {
+			return readOnly;
+		}
+
 		@Override
 		public boolean isIdentifierRollbackEnabled() {
 			return identifierRollback;
@@ -1283,7 +1288,7 @@ public SessionBuilderImpl statementInspector(StatementInspector statementInspect
 		}
 
 		@Override
-		public SessionBuilder statementInspector(UnaryOperator<String> operator) {
+		public SessionBuilderImpl statementInspector(UnaryOperator<String> operator) {
 			this.statementInspector = operator::apply;
 			return this;
 		}
@@ -1301,7 +1306,7 @@ public SessionBuilderImpl connectionHandlingMode(PhysicalConnectionHandlingMode
 		}
 
 		@Override
-		public SessionBuilder connectionHandling(ConnectionAcquisitionMode acquisitionMode, ConnectionReleaseMode releaseMode) {
+		public SessionBuilderImpl connectionHandling(ConnectionAcquisitionMode acquisitionMode, ConnectionReleaseMode releaseMode) {
 			this.connectionHandlingMode = PhysicalConnectionHandlingMode.interpret( acquisitionMode, releaseMode);
 			return this;
 		}
@@ -1343,7 +1348,13 @@ public SessionBuilderImpl tenantIdentifier(Object tenantIdentifier) {
 		}
 
 		@Override
-		public SessionBuilder identifierRollback(boolean identifierRollback) {
+		public SessionBuilderImpl readOnly(boolean readOnly) {
+			this.readOnly = readOnly;
+			return this;
+		}
+
+		@Override
+		public SessionBuilderImpl identifierRollback(boolean identifierRollback) {
 			this.identifierRollback = identifierRollback;
 			return this;
 		}
@@ -1384,6 +1395,7 @@ public static class StatelessSessionBuilderImpl implements StatelessSessionBuild
 		private StatementInspector statementInspector;
 		private Connection connection;
 		private Object tenantIdentifier;
+		private boolean readOnly;
 
 		public StatelessSessionBuilderImpl(SessionFactoryImpl sessionFactory) {
 			this.sessionFactory = sessionFactory;
@@ -1418,6 +1430,12 @@ public StatelessSessionBuilder tenantIdentifier(Object tenantIdentifier) {
 			return this;
 		}
 
+		@Override
+		public StatelessSessionBuilder readOnly(boolean readOnly) {
+			this.readOnly = readOnly;
+			return this;
+		}
+
 		@Override @Deprecated
 		public StatelessSessionBuilder statementInspector(StatementInspector statementInspector) {
 			this.statementInspector = statementInspector;
@@ -1493,6 +1511,11 @@ public String getTenantIdentifier() {
 					: sessionFactory.getTenantIdentifierJavaType().toString( tenantIdentifier );
 		}
 
+		@Override
+		public boolean isReadOnly() {
+			return readOnly;
+		}
+
 		@Override
 		public Object getTenantIdentifierValue() {
 			return tenantIdentifier;