Table of Contents
Why this project
Adding a second database to a Spring Boot application usually means hand-writing a second
DataSource bean, a second TransactionManager, a second set of MyBatis/JPA wiring — and then
still not knowing how to route a call to one of them.
dynamic-datasource replaces all of that with a single starter: declare your datasources in
YAML, annotate a class or method with @DS("slave"), and the framework resolves the connection at
invocation time, restores it when the call returns, and nests correctly across service layers. It
has been maintained since 2018, ships artifacts for three Spring Boot generations, and is validated
by CI on a JDK 17/21/25/27 matrix (the Boot 2 line is compiled and tested through a JDK 8 toolchain)
plus GraalVM Native Image.
It does exactly one thing — choosing which DataSource a call runs against — and deliberately
does not constrain what you do afterwards. Any CRUD, any ORM, any transaction strategy.
The full reference — every configuration key, connection pool and integration recipe — lives on
doc.xiuceyun.cn (Chinese); the wiki
is taking over page by page. See Documentation.
Highlights
| Area | What you get |
|---|
| Grouping | Pure multi-DB, read/write splitting, one-master-many-slaves, or a mix of all three, expressed by naming alone. |
| Routing | @DS on method / class / interface / abstract class, nearest declaration wins; group names resolve through a load-balanced or random strategy. |
| Transactions | Local multi-datasource transactions via @DSTransactional (7 propagation levels), plus Seata AT / XA and Atomikos XA for truly distributed commits. |
| Security | ENC(...) encrypted credentials out of the box, customisable algorithm and public key; SpEL type access restricted by default. |
| Lifecycle | Start with zero datasources, lazy-initialise on first use, add/remove datasources at runtime, graceful shutdown that waits for in-flight connections. |
| Extensibility | Custom annotations that meta-annotate @DS, custom DsProcessor chain, custom DataSourceProvider, pluggable DataSourceCreator. |
| Connectivity | Curated integration for Druid, HikariCP, BeeCP, DBCP2, C3P0, Oracle UCP, unpooled basic datasources and JNDI lookups. |
| Native | GraalVM reachability metadata published as an artifact; nativeTest gates every commit in CI. |
Compatibility
Pick the starter that matches your Spring Boot line (the maintenance status of each line is defined in SUPPORT.md):
| Spring Boot | JDK | Starter artifact | Available since |
|---|
| 1.5.x ~ 2.x.x | JDK 8+ | dynamic-datasource-spring-boot-starter | 1.0.0 |
| 3.x.x | JDK 17+ | dynamic-datasource-spring-boot3-starter | 4.0.0 |
| 4.x.x | JDK 17+ | dynamic-datasource-spring-boot4-starter | 4.5.0 |
Connection pools (Druid / HikariCP / …) and JDBC drivers are not bundled. Bring your own and
keep the versions aligned with your Spring Boot line — this is what keeps the starter lightweight
and avoids the classpath conflicts that a shaded starter would cause.
Quick start
1 · Add the dependency (shown for 4.5.0; replace with the latest release).
<!-- Spring Boot 2.x (and 1.5.x) -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>dynamic-datasource-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>
<!-- Spring Boot 3.x -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>dynamic-datasource-spring-boot3-starter</artifactId>
<version>4.5.0</version>
</dependency>
<!-- Spring Boot 4.x -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>dynamic-datasource-spring-boot4-starter</artifactId>
<version>4.5.0</version>
</dependency>
// choose exactly one, matching your Spring Boot line
implementation 'com.baomidou:dynamic-datasource-spring-boot-starter:4.5.0'
implementation 'com.baomidou:dynamic-datasource-spring-boot3-starter:4.5.0'
implementation 'com.baomidou:dynamic-datasource-spring-boot4-starter:4.5.0'
2 · Declare your datasources. Everything after the datasource: key is a datasource name; the
part before the first _ becomes its group.
spring:
datasource:
dynamic:
enabled: true # master switch, default true
primary: master # default datasource or group, default "master"
strict: false # true = throw when the key does not resolve
grace-destroy: false # true = wait up to 10s for active connections on shutdown
datasource:
master:
url: jdbc:mysql://xx.xx.xx.xx:3306/dynamic
username: root
password: 123456
driver-class-name: com.mysql.cj.jdbc.Driver # optional since 3.2.0 (SPI based)
slave_1:
url: jdbc:mysql://xx.xx.xx.xx:3307/dynamic
username: root
password: 123456
driver-class-name: com.mysql.cj.jdbc.Driver
slave_2:
url: ENC(xxxxx) # built-in encryption, see the documentation
username: ENC(xxxxx)
password: ENC(xxxxx)
driver-class-name: com.mysql.cj.jdbc.Driver
This is the beginning of the README. Read the rest at the original. Read the full README ↗
