Mastering Dynamic Multi‑DataSource Management in Spring Boot: A Deep Dive

1 Framework Overview and Core Value

dynamic-datasource is a multi‑data‑source management framework developed by the baomidou team; version 4.3.1 is a stable release widely used in enterprise applications. It solves the core requirement of dynamic data‑source switching, supporting read‑write separation in micro‑service and complex business systems. By using annotation‑driven declarations, developers can avoid boilerplate code and focus on business logic.

Key features of dynamic‑datasource 4.3.1 include flexible configuration of multiple data sources, @DS annotation for declarative switching, support for grouped data sources and load‑balancing strategies, compatibility with popular connection pools (Druid, HikariCP, DBCP2), and seamless integration with MyBatis/MyBatis‑Plus.

2 In‑Depth Implementation Analysis

2.1 Core Architecture and Data‑Source Switching Mechanism

The framework relies on two pillars: AOP interception and dynamic routing data source. It uses Spring extension points and ThreadLocal to achieve efficient switching.

AOP Interception and Data‑Source Identifier Parsing : DynamicDataSourceAnnotationAdvisor intercepts methods or classes annotated with @DS, extracts the annotation value (e.g., @DS("slave_1")), and pushes the identifier into DynamicDataSourceContextHolder’s Deque. After method execution the identifier is popped, allowing nested method calls.

public Object invoke(MethodInvocation invocation) throws Throwable {
    String dsKey = determineDatasource(invocation); // parse @DS value
    DynamicDataSourceContextHolder.push(dsKey); // push onto stack
    try {
        return invocation.proceed(); // execute target method
    } finally {
        DynamicDataSourceContextHolder.poll(); // pop from stack
    }
}

Dynamic Routing Data Source Implementation : DynamicRoutingDataSource extends Spring’s AbstractRoutingDataSource and overrides determineCurrentLookupKey() to obtain the current identifier from DynamicDataSourceContextHolder. The actual connection is obtained in getConnection() after the target data source is resolved.

public Connection getConnection() throws SQLException {
    String xid = TransactionContext.getXID();
    if (DsStrUtils.isEmpty(xid)) {
        return determineDataSource().getConnection();
    } else {
        String ds = DynamicDataSourceContextHolder.peek();
        ds = DsStrUtils.isEmpty(ds) ? getPrimary() : ds;
        ConnectionProxy connection = ConnectionFactory.getConnection(xid, ds);
        return connection == null ? getConnectionProxy(xid, ds, determineDataSource().getConnection())
                                  : connection;
    }
}

2.2 Grouped Data Sources and Load‑Balancing

Version 4.3.1 introduces grouped data sources for advanced read‑write separation or multi‑replica load‑balancing. Data sources named with the prefix group_ (e.g., slave_1, slave_2) belong to the same group and are selected according to configured strategies.

Group Parsing Mechanism : When @DS("slave") is used, the framework selects one available data source from the group based on the defined strategy, decoupling business code from specific instances.

Load‑Balancing Strategies : LoadBalanceDynamicDataSourceStrategy – round‑robin selection. RandomDynamicDataSourceStrategy – random selection.

# Grouped data source configuration example
spring:
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://master:3306/db
        slave_1:
          url: jdbc:mysql://slave1:3306/db
        slave_2:
          url: jdbc:mysql://slave2:3306/db

2.3 Data‑Source Initialization and Health Check

Initialization Process : During Spring Boot startup, DynamicDataSourceAutoConfiguration loads configuration via DynamicDataSourceAutoConfiguration and YmlDynamicDataSourceProvider, creates actual DataSource instances with DataSourceBuilder, and registers them in DynamicRoutingDataSource’s dataSourceMap.

Health‑Check Mechanism : DbHealthIndicator extends Spring Boot’s health endpoint (/actuator/health) and runs a simple SELECT 1 on each data source. A failure of any data source currently aborts application startup because the exception is not handled.

3 Pitfalls and Solutions

3.1 Data‑Source Configuration and Connection‑Pool Issues

3.1.1 Connection‑Pool Parameter Ineffectiveness

Parameters such as maximum-pool-size must be placed under the hikari sub‑section of each data source, not at the top level.

# Correct configuration example
spring:
  datasource:
    dynamic:
      datasource:
        master:
          type: com.zaxxer.hikari.HikariDataSource
          url: jdbc:mysql://localhost:3306/main
          username: root
          password: root
          hikari:
            maximum-pool-size: 20
            connection-timeout: 30000

3.1.2 Inconsistent Exception Handling During Data‑Source Creation

Different connection pools handle creation failures differently, making troubleshooting harder. Recommended solutions: unify exception capture by customizing DataSourceCreator to wrap all errors in ErrorCreateDataSourceException, and enable DEBUG logging for detailed information.

3.2 Transaction Management and Startup Exceptions

3.2.1 Transaction‑Scoped Switching Failure

When @Transactional is applied, the transaction manager determines the Connection at beginTransaction, preventing subsequent @DS switches. Solutions: move data‑source‑switching operations outside the transaction, split into separate transactional methods, or use read‑only transactions with @DS("slave").

// Incorrect example: switch fails inside transaction
@Transactional
@DS("master")
public void updateOrder(Order order) {
    orderMapper.update(order);
    @DS("slave")
    List<Log> logs = logMapper.queryByOrderId(order.getId());
}

// Correct example: split methods
@DS("master")
@Transactional
public void updateOrder(Order order) {
    orderMapper.update(order);
    queryLogs(order.getId());
}

@DS("slave")
@Transactional(propagation = Propagation.REQUIRES_NEW)
public List<Log> queryLogs(Long orderId) {
    return logMapper.queryByOrderId(orderId);
}

3.2.2 Health‑Check Blocking Startup

If any data source is unavailable, the default health check aborts startup. Work‑arounds: temporarily disable health check, customize the indicator to catch exceptions, or enable loose mode ( spring.datasource.dynamic.strict=false) to fall back to the primary source.

// Custom health indicator example
public class SafeDbHealthIndicator extends AbstractHealthIndicator {
    @Override
    protected void doHealthCheck(Health.Builder builder) {
        for (Map.Entry<String, DataSource> entry : dynamicDataSource.getDataSources().entrySet()) {
            try {
                Integer result = executeQuery(entry.getValue());
                builder.withDetail(entry.getKey(), result == 1 ? "UP" : "DOWN");
            } catch (Exception e) {
                builder.withDetail(entry.getKey(), "DOWN - " + e.getMessage());
            }
        }
    }
}

3.3 Version Compatibility and Configuration Traps

3.3.1 Compatibility with Spring Boot 3.3.x

dynamic‑datasource 4.3.1 may fail to load @EnableDynamicDataSource or core beans under Spring Boot 3.3.x. Solutions: downgrade to Spring Boot 3.2.x, wait for an updated release, or manually configure essential beans.

3.3.2 Multiple Data‑Source Bean Conflict

When multiple DataSource beans exist, Spring cannot decide which to use. Mark the primary data source with @Primary, exclude automatic DataSourceAutoConfiguration, or use @Qualifier to specify the target.

4 Best Practices and Optimization Recommendations

4.1 Configuration and Usage Advice

Connection‑Pool Choice : Prefer Druid or HikariCP for production; set maximum-pool-size to roughly twice the maximum thread count and connection-timeout to 3000‑5000 ms.

Multi‑Environment Strategy : Use Spring profiles (application‑dev.yml, application‑test.yml, application‑prod.yml) to separate configurations.

4.2 Exception Handling and Monitoring

Unified Exception Strategy : Implement DataSourceCreateFailStrategy with modes STRICT, LOG_ONLY, and RETRY.

Monitoring Integration : Expose /actuator/health, collect pool metrics with Micrometer‑Prometheus, and add DEBUG logs to DynamicDataSourceContextHolder for tracing.

4.3 High‑Availability and Disaster‑Recovery Design

Failover Mechanism : Periodic heartbeat SELECT 1, mark repeatedly failing nodes as SICK, and retry recovery after a cooldown.

Hot Configuration Update : Combine with a configuration center (Nacos, Apollo) to refresh data‑source definitions without restarting.

Architecture Selection Advice : Small‑to‑medium projects (≤10 data sources): use dynamic‑datasource directly. Large distributed systems: consider ShardingSphere or custom routing for sharding. Cloud‑native environments: integrate with a service mesh for transparent database routing.