Multiple DataSources in Spring Boot — Configuration and Routing

Direct Answer

Spring Boot auto-configures a single DataSource. For multiple databases, manually define each DataSource as a @Bean, build a separate EntityManagerFactory and TransactionManager per DataSource, and use @Qualifier (or @Primary) plus @EnableJpaRepositories(entityManagerFactoryRef, transactionManagerRef, basePackages) so each repository targets the right one. AbstractRoutingDataSource dynamically routes a single logical DataSource to multiple physical databases based on a ThreadLocal context key — used for read/write splitting (replica vs primary) or multi-tenancy (per-tenant DB). Mixing EntityManagerFactory instances across DataSources is the most common bug — entities end up in the wrong persistence context.

Code Example

Spring Boot auto-configures one DataSource by default. For read/write splitting or multi-tenant setups, you define each DataSource manually and mark one @Primary. An AbstractRoutingDataSource then picks the active one per request.

@Configuration
public class DataSourceConfig {

    @Bean @Primary @ConfigurationProperties("app.datasource.primary")
    public DataSource primaryDataSource() { return DataSourceBuilder.create().build(); }

    @Bean @ConfigurationProperties("app.datasource.replica")
    public DataSource replicaDataSource() { return DataSourceBuilder.create().build(); }

    @Bean
    public DataSource routingDataSource(@Qualifier("primaryDataSource") DataSource primary,
                                        @Qualifier("replicaDataSource") DataSource replica) {
        RoutingDataSource r = new RoutingDataSource();
        r.setTargetDataSources(Map.of("PRIMARY", primary, "REPLICA", replica));
        r.setDefaultTargetDataSource(primary);
        return r;
    }
}

public class RoutingDataSource extends AbstractRoutingDataSource {
    private static final ThreadLocal<String> KEY = ThreadLocal.withInitial(() -> "PRIMARY");
    public static void useReplica() { KEY.set("REPLICA"); }
    public static void useWriter()  { KEY.set("PRIMARY"); }
    public static void clear()      { KEY.remove(); }
    @Override protected Object determineCurrentLookupKey() { return KEY.get(); }
}

@Aspect @Component
class ReadOnlyRoutingAspect {
    @Around("@annotation(org.springframework.transaction.annotation.Transactional)")
    public Object route(ProceedingJoinPoint pjp) throws Throwable {
        Transactional tx = ((MethodSignature) pjp.getSignature())
            .getMethod().getAnnotation(Transactional.class);
        if (tx != null && tx.readOnly()) RoutingDataSource.useReplica();
        try { return pjp.proceed(); } finally { RoutingDataSource.clear(); }
    }
}

app:
  datasource:
    primary:
      jdbc-url: jdbc:postgresql://primary:5432/app
    replica:
      jdbc-url: jdbc:postgresql://replica:5432/app
      read-only: true

• Each DataSource needs its own EntityManagerFactory and PlatformTransactionManager when you use JPA — bind them with @EnableJpaRepositories(basePackages=..., entityManagerFactoryRef=..., transactionManagerRef=...).
• The aspect flips the ThreadLocal key before the transaction starts; swapping mid-transaction is unsafe because the connection is already bound to one DataSource.
• For multi-tenant apps, key by tenant ID (RoutingDataSource.useTenant(currentTenantId())) instead of read/write — same mechanism, different lookup key.

Common Mistakes & Pitfalls

Forgetting that each DataSource needs its own EntityManagerFactory and TransactionManager — mixing them causes entities to be managed by the wrong persistence context