Spring Boot Setup And Demo
For this demo, we will create a spring boot application with common dependencies - Web, JPA, Lombok, PostgreSQL, actuator etc.
How it works
The whole purpose of the master and replica databases are to distribute the load on the databases.
Every write operation must go to master database and all the read operation should come from replications.
Since all the master and replica databases are the same and have async replications, then eventually all the data would be the same.
Whenever any write operation will happen in master instance, database will get sync with other replications.
So we need to create connection with master and all the replica databases at the same time. We will follow multiple data source connection and decide the data source required based on transaction operation.
To determine which data source to select, we will be utilizing spring provided transaction along with some custom annotations.
Whenever any transaction is marked as read-only @Transaction(readOnly=true) , the system will route to replication and without read-only to master.
To mark certain APIs or methods to use forcefully replica or master data source, we will be writing custom annotations.
Since the whole operation would be thread base, so will use a custom DataSourceContextHolder to mark current transaction as for replica or master
Project Structure
Application Properties
Here we have configured the dataSouce properties for master and replica databases.
We have added the hikari configuration as separated as we will configure dataSource manually.
# Application Configuration
server:
port: 8080
# Logging Configuration
logging:
level:
com.app: DEBUG
org.springframework.jdbc: DEBUG
org.springframework.transaction: DEBUG
com.zaxxer.hikari: info
# pattern:
# console: "%d{yyyy-MM-dd HH:mm:ss} - %msg%n"
# file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
file:
name: logs/application.log
# Master Database Configuration
spring:
datasource:
master:
url: jdbc:postgresql://192.168.1.17:6000/readreplicademo
username: ${MASTER_DB_USER:postgres}
password: ${MASTER_DB_PASSWORD:root}
driver-class-name: org.postgresql.Driver
# Replica Database Configurations
replica1:
url: jdbc:postgresql://192.168.1.17:6000/readreplicademo
username: ${MASTER_DB_USER:postgres}
password: ${MASTER_DB_PASSWORD:root}
driver-class-name: org.postgresql.Driver
replica2:
url: jdbc:postgresql://192.168.1.17:6000/readreplicademo
username: ${MASTER_DB_USER:postgres}
password: ${MASTER_DB_PASSWORD:root}
driver-class-name: org.postgresql.Driver
replica3:
url: jdbc:postgresql://192.168.1.17:6000/readreplicademo
username: ${MASTER_DB_USER:postgres}
password: ${MASTER_DB_PASSWORD:root}
driver-class-name: org.postgresql.Driver
# Transaction Configuration
transaction:
default-timeout: 30
rollback-on-commit-failure: true
# JPA Configuration (if using JPA)
jpa:
hibernate:
ddl-auto: update
show-sql: false
properties:
hibernate:
dialect: org.hibernate.dialect.PostgreSQLDialect
format_sql: true
use_sql_comments: true
jdbc:
batch_size: 20
connection:
provider_disables_autocommit: true
threads:
virtual:
enabled: true
# Retry Configuration
# retry:
# enabled: true
# Management & Monitoring
management:
endpoints:
web:
exposure:
include: health,info,metrics,prometheus
endpoint:
health:
show-details: always
metrics:
access: read_only
health:
db:
enabled: true
metrics:
enable:
all: true
# metrics:
# export:
# prometheus:
# enabled: true
# Custom Application Properties
app:
database:
read-timeout: 30
write-timeout: 60
health-check-interval: 30000
connection-retry-attempts: 3
connection-retry-delay: 2000
async:
core-pool-size: 10
max-pool-size: 50
queue-capacity: 100
keep-alive-seconds: 60
scheduling:
pool-size: 5
health-check-cron: "0 */1 * * * *" # Every minute
maintenance-cron: "0 0 2 * * *" # Daily at 2 AM
hikari:
auto-commit: false
connection-timeout: 20000
idle-timeout: 300000
max-lifetime: 1200000
maximum-pool-size: 20
minimum-idle: 5
# circuit-breaker:
# enabled: true
# failure-threshold: 5
# timeout: 10000
# reset-timeout: 60000DataSouceConfig
We will read the properties file and create beans of master and replica datasources
We will use RoutingDataSource that helps in routing the database connection between master and replicas.
@RequiredArgsConstructor
@Configuration(proxyBeanMethods = false)
@EnableTransactionManagement
@EnableJpaRepositories(
basePackages = "com.app.readreplica.repositories",
entityManagerFactoryRef = "entityManagerFactory",
transactionManagerRef = "transactionManager"
)
public class DataSourceConfig {
private final ApplicationProperties applicationProperties;
// reading master datasource properties
@Bean(name = "masterDataSourceProperties")
@ConfigurationProperties(prefix = "spring.datasource.master")
public DataSourceProperties masterDataSourceProperties() {
return new DataSourceProperties();
}
// creating HikariDatasource for master
@Bean(name = "masterDataSource")
public DataSource masterDataSource(@Qualifier("masterDataSourceProperties") DataSourceProperties properties) {
var ds= properties.initializeDataSourceBuilder().type(HikariDataSource.class).build();
populateHikariConfig((HikariDataSource) ds);
ds.setPoolName("MasterCP");
return ds;
}
// reading replica datasource properties
@Bean(name = "replica1DataSourceProperties")
@ConfigurationProperties(prefix = "spring.datasource.replica1")
public DataSourceProperties replica1DataSourceProperties() {
return new DataSourceProperties();
}
// replica hikari datasource
@Bean(name = "replica1DataSource")
public DataSource replica1DataSource(@Qualifier("replica1DataSourceProperties") DataSourceProperties properties) {
var ds= properties.initializeDataSourceBuilder().type(HikariDataSource.class).build();
populateHikariConfig((HikariDataSource) ds);
ds.setPoolName("Replica1CP");
return ds;
}
@Bean(name = "replica2DataSourceProperties")
@ConfigurationProperties(prefix = "spring.datasource.replica2")
public DataSourceProperties replica2DataSourceProperties() {
return new DataSourceProperties();
}
@Bean(name = "replica2DataSource")
public DataSource replica2DataSource(@Qualifier("replica2DataSourceProperties") DataSourceProperties properties) {
var ds= properties.initializeDataSourceBuilder().type(HikariDataSource.class).build();
populateHikariConfig((HikariDataSource) ds);
ds.setPoolName("Replica2");
return ds;
}
@Bean(name = "replica3DataSourceProperties")
@ConfigurationProperties(prefix = "spring.datasource.replica3")
public DataSourceProperties replica3DataSourceProperties() {
return new DataSourceProperties();
}
//
@Bean(name = "replica3DataSource")
public DataSource replica3DataSource(@Qualifier("replica3DataSourceProperties") DataSourceProperties properties) {
var ds= properties.initializeDataSourceBuilder().type(HikariDataSource.class).build();
populateHikariConfig((HikariDataSource) ds);
ds.setPoolName("MasterCP");
return ds;
}
private void populateHikariConfig(HikariDataSource ds) {
var hikari = applicationProperties.getHikari();
ds.setAutoCommit(hikari.isAutoCommit());
ds.setConnectionTimeout(hikari.getConnectionTimeout());
ds.setIdleTimeout(hikari.getIdleTimeout());
ds.setMaxLifetime(hikari.getMaxLifetime());
ds.setMaximumPoolSize(hikari.getMaximumPoolSize());
ds.setMinimumIdle(hikari.getMinimumIdle());
}
// bean to all the datasources
@Bean(name = "replicaDataSources")
public List<DataSource> replicaDataSources(
@Qualifier("replica1DataSource") DataSource replica1,
@Qualifier("replica2DataSource") DataSource replica2,
@Qualifier("replica3DataSource") DataSource replica3) {
return List.of(replica1, replica2, replica3);
}
// Routing datasource bean that will pick the correct datasoruce based on transaction choice
@Bean(name = "routingDataSource")
public DataSource routingDataSource(@Qualifier("masterDataSource") DataSource masterDataSource,
@Qualifier("replicaDataSources") List<DataSource> replicaDataSources) {
ReadWriteRoutingDataSource routingDataSource = new ReadWriteRoutingDataSource();
routingDataSource.setMasterDataSource(masterDataSource);
routingDataSource.setReplicaDataSources(replicaDataSources);
routingDataSource.afterPropertiesSet();
return routingDataSource;
}
// now creating main datasource object , with instance of routing data source
@Primary
@Bean(name = "dataSource")
public DataSource dataSource(@Qualifier("routingDataSource") DataSource routingDataSource) {
// LazyConnectionDataSourceProxy ensures connection is obtained only when needed
return new LazyConnectionDataSourceProxy(routingDataSource);
}
Routing DataSource
This class is responsible for selecting data source based on the transaction type of query.
It has instances of master and replica data sources and take helpes of DataSourceContextHolder class to determine the user selected choice.
package com.app.readreplica.config.database;
import lombok.Getter;
import lombok.Setter;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.jdbc.datasource.lookup.AbstractRoutingDataSource;
import org.springframework.lang.NonNullApi;
import org.springframework.transaction.support.TransactionSynchronizationManager;
import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.SQLException;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.atomic.AtomicInteger;
@Getter
@Setter
public class ReadWriteRoutingDataSource extends AbstractRoutingDataSource {
private static final Logger logger = LoggerFactory.getLogger(ReadWriteRoutingDataSource.class);
private DataSource masterDataSource;
private List<DataSource> replicaDataSources;
private final AtomicInteger replicaCounter = new AtomicInteger(0);
private final ThreadLocal<String> forceDataSource = new ThreadLocal<>();
@Override
public void afterPropertiesSet() {
Map<Object, Object> targetDataSources = new HashMap<>();
// Add master datasource
targetDataSources.put(DataSourceType.MASTER, masterDataSource);
// Add replica data-sources
for (int i = 0; i < replicaDataSources.size(); i++) {
targetDataSources.put(DataSourceType.REPLICA.name() + "_" + i, replicaDataSources.get(i));
}
setTargetDataSources(targetDataSources);
setDefaultTargetDataSource(masterDataSource);
super.afterPropertiesSet();
}
// calls before cometting the transaction to get the key datasource
@Override
protected Object determineCurrentLookupKey() {
if(DataSourceContextHolder.isMasterRequired()){
logger.debug("Using master datasource for write transaction");
return DataSourceType.MASTER;
}
if(DataSourceContextHolder.isReplicaRequired() || TransactionSynchronizationManager.isCurrentTransactionReadOnly()){
String replicaKey = selectReadReplica();
logger.debug("Using read replica: {}", replicaKey);
return replicaKey;
}
if(TransactionSynchronizationManager.isActualTransactionActive() ){
logger.debug("Using master datasource for write transaction");
return DataSourceType.MASTER;
}
// 3. Default to master
return DataSourceType.MASTER;
// return selectReadReplica();
}
private String selectReadReplica() {
if (replicaDataSources.isEmpty()) {
logger.warn("No replica datasources available, falling back to master");
return DataSourceType.MASTER.name();
}
// Round-robin load balancing with failover based on health check
for (int i = 0; i < replicaDataSources.size(); i++) {
int index = replicaCounter.getAndIncrement() % replicaDataSources.size();
String replicaKey = DataSourceType.REPLICA.name() + "_" + index;
// Check if replica is healthy
if (isDataSourceHealthy(replicaDataSources.get(index))) {
return replicaKey;
}
logger.warn("Replica {} is unhealthy, trying next replica", replicaKey);
}
// All replicas failed, fallback to master
logger.error("All replica datasources are unhealthy, falling back to master");
return DataSourceType.MASTER.name();
// Random load balancing
// int index = Math.abs(replicaCounter.getAndIncrement() % replicaDataSources.size());
// Object key = index;
// logger.debug("Routing to REPLICA index: {}, key: {}", index, DataSourceType.REPLICA.name() + "_" + key);
// return DataSourceType.REPLICA.name() + "_" + index;
}
private boolean isDataSourceHealthy(DataSource dataSource) {
try (Connection connection = dataSource.getConnection()) {
return connection.isValid(1); // 1 second timeout
} catch (SQLException e) {
logger.error("Health check failed for replica datasource", e);
return false;
}
}
}DataSourceContextHolder
A helper that store the current choice of routing decision. ReadWriteRoutingDataSource uses this class to determine the current lookup key.
public enum DataSourceType {
MASTER, REPLICA
}
/**
* Uses a ThreadLocal to store the routing decision for the current thread.
* This allows the AOP aspect to signal the routing data source to use a replica.
*/
public class DataSourceContextHolder {
private static final ThreadLocal<Boolean> replicaRequestHolder = new ThreadLocal<>();
private static final ThreadLocal<Boolean> masterRequestHolder = new ThreadLocal<>();
public static void setReplicaRequired(boolean isReplicaRequired) {
replicaRequestHolder.set(isReplicaRequired);
}
public static boolean isReplicaRequired() {
return replicaRequestHolder.get() != null && replicaRequestHolder.get();
}
public static void clearReplica() {
replicaRequestHolder.remove();
}
public static void setMasterRequired(boolean isMasterRequired) {
masterRequestHolder.set(isMasterRequired);
}
public static boolean isMasterRequired() {
return masterRequestHolder.get() != null && masterRequestHolder.get();
}
public static void clearMaster() {
masterRequestHolder.remove();
}
}Annotations
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ForceMaster {
/**
* Force using master datasource even for read operations
*/
}
/**
* Annotation to force a read-only transaction.
*
* @Author saurabh vaish
* @Date 23-07-2025
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ReadOnlyReplica {
}
Aspect to perform action based on these annotations
So when ever any api or method is marked with the above annotations this aspect will check and based on the annotation it will set the routing choice in DataSourceContextHolder. When actual datasource decision will happen the updated context will force the routing to go to master or replica
@Aspect
@Component
@Order(0)
public class ReadOnlyRouteAspect {
@Before("@annotation(com.app.readreplica.config.database.annotations.ReadOnlyReplica)")
public void setReadDataSourceType() {
DataSourceContextHolder.setReplicaRequired(true);
}
@After("@annotation(com.app.readreplica.config.database.annotations.ReadOnlyReplica)")
public void clearDataSourceType() {
DataSourceContextHolder.clearReplica();
}
@AfterThrowing(pointcut = "@annotation(com.app.readreplica.config.database.annotations.ReadOnlyReplica)", throwing = "ex")
public void clearAfterException(Throwable ex) {
DataSourceContextHolder.clearReplica();
}
@Before("@annotation(com.app.readreplica.config.database.annotations.ForceMaster)")
public void setForceMasterDataSourceType() {
DataSourceContextHolder.setMasterRequired(true);
}
@After("@annotation(com.app.readreplica.config.database.annotations.ForceMaster)")
public void clearForceMasterDataSourceType() {
DataSourceContextHolder.clearMaster();
}
@AfterThrowing(pointcut = "@annotation(com.app.readreplica.config.database.annotations.ForceMaster)", throwing = "ex")
public void clearForceMasterAfterException(Throwable ex) {
DataSourceContextHolder.clearMaster();
}
}
Example Service
// routed to master
@Transactional
public Token createToken() {
log.info("Starting token creation process");
String tokenValue = generateRandomToken();
Token token = new Token();
token.setToken(tokenValue);
log.info("Creating new token with value: {}", tokenValue);
Token savedToken = tokenRepository.save(token);
log.info("Successfully created token with id: {} and value: {}", savedToken.getId(), tokenValue);
return savedToken;
}
// read from replica, here either one of is requied
@ReadOnlyReplica
@Transactional(readOnly = true)
public List<Token> findAll() {
log.info("Starting retrieval of all tokens");
List<Token> tokens = tokenRepository.findAll();
// Thread.sleep(1000);
log.info("Successfully retrieved {} tokens", tokens.size());
log.debug("Token count details: {}", tokens.size());
return tokens;
}
// will force read operation to go master even if its read only
@ForceMaster
@Transactional(readOnly = true)
public Optional<Token> findById(Long id) {
log.info("Starting search for token with id: {}", id);
Optional<Token> result = tokenRepository.findById(id);
if (result.isPresent()) {
log.info("Successfully found token with id: {}", id);
log.debug("Token details - id: {}, value: {}", result.get().getId(), result.get().getToken());
} else {
log.warn("No token found with id: {}", id);
}
return result;
}
// routed to master
@Transactional
public Token updateToken(Long id, String newTokenValue) {
log.info("Starting token update for id: {} with new value: {}", id,
newTokenValue != null ? "provided" : "auto-generated");
Optional<Token> tokenOpt = tokenRepository.findById(id);
if (tokenOpt.isPresent()) {
Token token = tokenOpt.get();
String oldValue = token.getToken();
String finalTokenValue = newTokenValue != null ? newTokenValue : generateRandomToken();
token.setToken(finalTokenValue);
log.info("Updating token id: {} - old value: {}, new value: {}", id, oldValue, finalTokenValue);
Token updatedToken = tokenRepository.save(token);
log.info("Successfully updated token with id: {}", id);
return updatedToken;
} else {
log.error("Token not found with id: {} for update operation", id);
throw new TokenNotFoundException(id);
}
}
Last updated