SpringBoot多数据源实战：PostgreSQL+SQL Server配置与踩坑记录

多数据源这个需求，我在实际项目里遇到过太多次了。最常见的一个场景就是：新系统跑在 PostgreSQL 上，但库里还存着早年 SQL Server 里的老数据，管理层要看报表、运营要查历史订单，不可能等数据完全迁移完才上线。于是同一个 SpringBoot 服务里连两个库，就成了最务实的解法。

这篇文章我就拿一个真实的改造项目来拆。需求本身不复杂——SpringBoot 同时连 PostgreSQL 和 SQL Server，两个库的表通过接口聚合返回。但真正落地的时候，版本兼容、驱动差异、事务边界、SQL Server 连不上的各种幺蛾子，每一个都能卡住大半天。这篇文章会把我的设计思路、配置方案、完整代码，以及实测中踩过的坑全部记录下来，给正在做同样事的同学一个可以直接抄的作业。

1. 多数据源需求分析与方案选型

1.1 核心需求解读

先把需求说清楚。我当时接到的任务是：一个后台管理系统，主业务库是 PostgreSQL，存用户、商品、订单等核心业务数据；但系统里有个“历史数据查询”模块，需要去另一台 SQL Server 2008 R2 上读十年前的老订单。两个库不在同一个实例，也不在同一台机器，甚至连数据库类型都不同。

这里有个关键点要先想明白：我们说的“多数据源”，到底是要解决什么问题？是把两个库的数据放在同一个事务里写？还是两边独立读写、互不干扰？还是需要跨库 join 查询？

这三种诉求对应的是完全不同的技术方案。我当时的需求是第二种——两边独立读写，偶尔在 service 层做内存聚合，不涉及跨库事务。这就把复杂度降下来了，不需要引入分布式事务中间件，只需要做好数据源路由和配置隔离就行了。

1.2 三种主流实现方案对比

实现 SpringBoot 多数据源，业界主流有三条路。我先把它们放在一起对比，再讲我为什么选了其中一条。

我最开始想走第一条路，毕竟不引第三方依赖，能少一个问题源。但后来评估了一下工作量：除了实现 DynamicDataSource 类，还要写拦截器或者 AOP 切面，让 @DS 注解能生效，还要处理事务管理器绑定数据源的问题。这套东西自己写起来，至少要半天起步，而且边界情况很多——比如事务开启之后，事务内数据源切换是失效的，这个坑我当年踩过。

后来我换成了 dynamic-datasource-spring-boot-starter，这是 MyBatis-Plus 官方出的一个多数据源方案，底层基于 AbstractRoutingDataSource 做了深度封装。用起来就一个 @DS 注解的事，事务边界、连接池隔离都给你处理好了。我的建议是：除非你公司有强制“零第三方依赖”的规范，否则直接用这个 starter，省下的时间拿去处理业务逻辑和排查 SQL Server 的连接问题，性价比高得多。

2. 环境准备与依赖引入

2.1 SpringBoot 版本选型与依赖清单

版本选型是很多人容易忽略、但恰恰是最容易出坑的一步。spring boot 版本“太高”导致的各种兼容性问题，在这类多数据源场景下特别常见。

我当时项目的 SpringBoot 版本是 2.7.18，对应 JDK 1.8。为什么选这个组合？因为 2.7.x 是 SpringBoot 2.x 的最后一个维护版本，稳定、资料多，而且 dynamic-datasource 对 2.x 系列的兼容性最好。如果你的项目已经上了 SpringBoot 3.x，那需要 JDK 17 起步，dynamic-datasource 也要选 3.6.0 以上版本，否则启动阶段会直接报 ClassNotFoundException 或者 BeanDefinitionStoreException。

依赖引入只需要在 pom.xml 里加这么几个东西：

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>dynamic-datasource-spring-boot-starter</artifactId>
    <version>3.6.1</version>
</dependency>

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.5</version>
</dependency>

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.6.0</version>
</dependency>

<dependency>
    <groupId>com.microsoft.sqlserver</groupId>
    <artifactId>mssql-jdbc</artifactId>
    <version>9.4.1.jre8</version>
</dependency>

这里重点说两个驱动版本的选择逻辑。

PostgreSQL 驱动用的是 42.6.0，这个版本对 PG 9.x~15.x 都做了兼容，包含了对 SCRAM 认证方式的完整支持。如果你的 PG 是 10 以下的老版本，可能需要往下退一版到 42.2.x，但新装的 PG 基本不用考虑这个问题。

SQL Server 驱动是我专门挑的 9.4.1.jre8。为什么不用更新的版本？因为当时目标库是 SQL Server 2008 R2，而 mssql-jdbc 从 12.2 版本开始已经明确不再支持 2008 和 2008 R2。如果用太高版本的驱动连老库，启动可能没问题，一执行查询就报“此驱动程序不支持 SQL Server 2008 R2 的 TLS 版本”之类的错误。这块我会在第 5 节展开讲，算是整个配置过程中最容易踩的暗坑。

2.2 数据库连接准备与连接串写法

依赖配好了，先别急着写配置，先确认两个库能连上。我习惯先用数据库客户端把连接信息测一遍，这里有个细节容易让人困惑：PostgreSQL 的默认端口 5432，SQL Server 是 1433，这两个别搞混。

PostgreSQL 的连接串标准写法是：

text复制jdbc:postgresql://localhost:5432/business_db

驱动类是 org.postgresql.Driver，参数用 ? 拼接，比如 ?useUnicode=true&characterEncoding=utf8。

SQL Server 的 JDBC 连接串格式和 MySQL、PostgreSQL 差异很大，容易踩坑：

text复制jdbc:sqlserver://localhost:1433;DatabaseName=legacy_db;encrypt=false

注意它是用分号分隔参数，不是问号，这是 SQL Server 驱动特有的风格。encrypt=false 这个参数很关键。在高版本驱动里，默认会开启加密通信，如果 SQL Server 服务端没配好证书，连接的时候就会报 SSL 握手失败。连 2008 R2 这种老库，写法上直接关掉加密最省事。

另外提醒一个容易忽视的点：如果 SQL Server 那边启用了命名实例（形如 localhost\SQLEXPRESS），连接串要写成 jdbc:sqlserver://localhost\\SQLEXPRESS;DatabaseName=xxx，反斜杠在 YAML 里记得转义或者用引号包起来。

3. 动态数据源配置与代码实现

3.1 application.yml 多数据源配置

依赖准备好之后，接下来就是配置文件的编写。我用的是 dynamic-datasource 的配置格式，核心都在 spring.datasource.dynamic 节点下面。

yaml复制spring:
  datasource:
    dynamic:
      primary: postgres
      strict: true
      datasource:
        postgres:
          driver-class-name: org.postgresql.Driver
          url: jdbc:postgresql://localhost:5432/business_db?useUnicode=true&characterEncoding=utf8
          username: postgres
          password: postgres123
        sqlserver:
          driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
          url: jdbc:sqlserver://localhost:1433;DatabaseName=legacy_db;encrypt=false
          username: sa
          password: sa123456

解释一下两个关键属性的作用。

primary: postgres 指定默认数据源。意思是，如果某个方法或者 Mapper 上没有标注 @DS 注解，会默认走 postgres 这个数据源。这里我故意把主数据源设成 postgres，因为系统里 80% 的查询都是走新库的，减少注解的书写量。

strict: true 是严格模式，开启后路由到不存在的 @DS("xxx") 时会直接报错，而不是静默回退到主数据源。这个建议一开始就打开，否则配置写错数据源名称，服务不会报错，但数据查出来是错的，排查起来非常痛苦。

3.2 理解动态路由的核心机制

刚开始用 dynamic-datasource 的同学，建议花十分钟理解一下它的底层原理，否则出了问题都不知道去哪找。

它的核心其实还是 Spring 自带的 AbstractRoutingDataSource。这个类的关键方法是 determineCurrentLookupKey()，用于决定当前线程应该用哪个数据源。dynamic-datasource 做的事情就是在这个方法返回一个 key（比如 postgres 或者 sqlserver），然后从内部维护的一个 Map 里取出对应的真实数据源来建立连接。

那这个 key 是怎么和线程绑定的？靠的是 @DS 注解加 AOP 切面。每次调用带 @DS 注解的方法时，切面会先把注解指定的数据源名称塞进一个 ThreadLocal，等 determineCurrentLookupKey() 执行的时候再从 ThreadLocal 里取出来。方法执行完，切面会清理 ThreadLocal，避免线程池复用导致数据源串了。

理解了这套机制，你就能明白两件事：

第一，数据源切换的粒度是“方法级”的，不是“事务级”的。如果你想在同一个方法里先查 PostgreSQL，再切到 SQL Server 查另一张表，再切回来，这样是可行的，因为每次调用 Mapper 方法都相当于一次新路由。

第二，事务和数据源是强绑定的。Spring 事务是基于连接做的，一旦事务开启，数据库连接就被绑定到当前线程了，这个连接是哪个数据源的，整个事务内就只会用这个数据源。所以如果你在一个 @Transactional 方法里用 @DS 切换数据源，后一次切换是不会生效的，这是动态数据源最大的一个限制，我在第 3.4 节会详细展开。

3.3 @DS 注解完成数据源切换

配置写好之后，代码这边的改动量其实很小，核心就是 @DS 注解。

先看一下我的 Mapper 层。这里我用了 MyBatis-Plus 的 BaseMapper，两个库的表结构差异很大，就分开建了实体和 Mapper：

java复制@Mapper
public interface UserMapper extends BaseMapper<User> {
}

java复制@Mapper
public interface LegacyOrderMapper extends BaseMapper<LegacyOrder> {
    
    @Select("SELECT order_id, customer_name, total_amount FROM t_legacy_order WHERE order_date >= #{startDate}")
    List<LegacyOrder> selectOrdersByDate(@Param("startDate") String startDate);
}

然后是两个 Service，通过 @DS 指定各自的数据源：

java复制@Service
public class UserService {
    
    @Autowired
    private UserMapper userMapper;
    
    @DS("postgres")
    public List<User> listUsers() {
        return userMapper.selectList(null);
    }
}

java复制@Service
public class LegacyOrderService {
    
    @Autowired
    private LegacyOrderMapper legacyOrderMapper;
    
    @DS("sqlserver")
    public List<LegacyOrder> listLegacyOrders(String startDate) {
        return legacyOrderMapper.selectOrdersByDate(startDate);
    }
}

在 Controller 层把它们聚合起来：

java复制@RestController
@RequestMapping("/api/dashboard")
public class DashboardController {
    
    @Autowired
    private UserService userService;
    
    @Autowired
    private LegacyOrderService legacyOrderService;
    
    @GetMapping("/overview")
    public Map<String, Object> overview(@RequestParam String startDate) {
        Map<String, Object> result = new HashMap<>();
        result.put("users", userService.listUsers());
        result.put("legacyOrders", legacyOrderService.listLegacyOrders(startDate));
        return result;
    }
}

你没看错，核心代码就这么多。@DS 注解加在 Service 方法上之后，整个方法的内部调用都会走这个数据源，不需要把注解打在 Mapper 上，也不需要手动管理连接。

这里我想多说一句设计层面的体会。你在写多数据源代码的时候，一定要按“库”来划分 Service，而不是把所有 Mapper 都塞到一个 Service 里。比如我这里专门建了一个 LegacyOrderService 去管 SQL Server 的数据，将来如果老库的查询逻辑变复杂了，我可以独立演进这个 Service，不会影响 PostgreSQL 那边的业务逻辑。

3.4 多数据源下的事务处理策略

事务这块值得单独拿出来说。很多同学第一版写出来，发现 @DS 确实能切换，但一旦在方法上加了 @Transactional，切换就失效了，然后各种百度都找不到答案。

原因是这样的：事务启动的优先级高于 @DS 的切换。Spring 开启事务时，数据源和连接已经绑定了，此时 AbstractRoutingDataSource 已经确定了要连哪个库。等 @DS 切面再执行的时候，连接已经拿好了，切换也就无从谈起。

所以分情况讨论：

如果是单数据源内的事务，比如一个方法里要连续往 PostgreSQL 的 user 表和 user_log 表写数据，那直接在 Service 方法上加 @Transactional 就行，前提是这个 Service 方法没加 @DS 或者加的 @DS 和事务数据源一致。

如果是跨数据源的事务，比如同时往 PostgreSQL 写一条用户数据，往 SQL Server 写一条对应的日志，那普通 @Transactional 是无解的。这时候要引入分布式事务方案，常见的有 Seata、Atomikos，以及基于消息队列的最终一致性方案。

我的建议是：在绝大多数“多数据源查询聚合”场景下，你根本不需要跨库事务。读操作不需要事务，写操作尽量做数据源隔离——哪个库的数据就在哪个 Service 里写，跨库的联动用业务代码补偿，或者用消息队列做异步处理。分布式事务的开销很大，引入前一定要想清楚是否真的需要强一致。

如果实在躲不开，可以试试 dynamic-datasource 官方提供的 Seata 集成方案，但那是另一个大的话题了，这篇先不展开。

3.5 MyBatis-Plus 与分页/逻辑删除兼容

如果你用了 MyBatis-Plus，多数据源场景下还有一个隐性问题：分页插件和逻辑删除的全局配置，默认只对主数据源生效吗？

不是的。dynamic-datasource 对 MyBatis-Plus 做了一层兼容，分页拦截器、逻辑删除拦截器是全局的，不管你切到哪个数据源，拦截器都会生效。我实际测试过，在两个库上执行分页查询，生成的 COUNT 语句和 LIMIT/TOP 语法都能正确适配。

唯一的差异点是数据库方言。MyBatis-Plus 的分页插件需要手动指定 DbType。我的做法是在配置分页拦截器的时候不写死数据库类型，让它自动识别：

java复制@Configuration
public class MybatisPlusConfig {
    
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        PaginationInnerInterceptor pagination = new PaginationInnerInterceptor();
        // 不指定 DbType，让插件根据连接自动判断
        interceptor.addInnerInterceptor(pagination);
        return interceptor;
    }
}

实际测试下来，同样的分页代码，在 PostgreSQL 上生成的是 LIMIT ? OFFSET ?，在 SQL Server 2008 R2 上生成的是 OFFSET ? ROWS FETCH NEXT ? ROWS ONLY，自动判断是正确的。不过要提醒一句：SQL Server 2012 以下的版本不支持 OFFSET-FETCH 分页，如果你的老库是 2008 R2，用 MyBatis-Plus 自带的分页是会报语法错误的。我当时是老库数据量不大，直接没用分页插件，手写 SQL 用 TOP 关键字来解决。

4. 实操验证与效果检查

4.1 启动项目和路由验证

配置和代码都写完之后，最让人紧张的就是启动那一刻。我建议先做两个小验证，再启动项目，能省掉很多排查时间。

第一个验证是数据库客户端连通性。用 DBeaver 或者 Navicat 分别连一下 PostgreSQL 和 SQL Server，确认连接串、账号密码、库名都没问题。这一步过了，说明问题大概率出在项目配置上，而不是数据库本身。

第二个验证是检查驱动类和配置项的拼写。动态数据源启动时，如果配置的驱动类加载不到，会直接报 Cannot load driver class: com.microsoft.sqlserver.jdbc.SQLServerDriver。如果报这个错，优先检查是不是用了 SpringBoot 3.x 导致依赖版本对不上。

一切正常的话，启动日志里会看到类似这样的输出：

text复制o.s.j.e.a.AnnotationConfigEmbeddedWebApplicationContext : Refreshing org.springframework.boot.context.embedded.AnnotationConfigEmbeddedWebApplicationContext@xxx: startup date ...
com.baomidou.dynamic.datasource.DynamicRoutingDataSource : dynamic-datasource init completed, primary datasource name: postgres

看到 “init completed” 和 “primary datasource name: postgres” 这两行，说明数据源初始化成功了。接下来进入接口验证环节。

4.2 接口联调与日志观察

我把聚合接口部署起来之后，用 Postman 打了个请求，先是正常返回了两个库的数据，说明基本流程通了。

但光看见返回成功还不够，我习惯再确认一下“路由真的按预期走了”。我故意在 PostgreSQL 里建了一张表，SQL Server 里也建了一张同名表，结构完全不同，然后分别写查询接口。如果路由没问题，访问 /api/source/postgres 返回的是 PostgreSQL 的字段，访问 /api/source/sqlserver 返回的是 SQL Server 的字段。这样一比就能发现数据源是否串了。

另外一个很好的观测手段是打开 MyBatis 的 SQL 日志：

yaml复制logging:
  level:
    com.example.demo.mapper: debug

打开后，每次 Mapper 执行都会打印 SQL 和执行参数。同时 dynamic-datasource 也支持打印当前数据源的提示信息，在配置里加一行：

yaml复制spring:
  datasource:
    dynamic:
      show-sql: true

这样控制台会输出类似 [dynamic-datasource] [postgres] - SQL executed in X ms 的日志，一眼就能看出当前查询走的是哪个库。检查完路由没问题，记得把 show-sql 关掉，或者调整到只在测试环境开启，避免生产环境日志量过大。

5. 常见问题与排查技巧实录

5.1 SpringBoot 版本过高的兼容性问题

这个问题的出现频率最高。最近不少同学反馈，直接新建一个 SpringBoot 3.2 甚至 3.4 的项目，引入 dynamic-datasource 3.5.x 的依赖，启动直接抛 ClassNotFoundException: javax.sql.DataSource 或者各种 BeanCreationException。

原因很简单：SpringBoot 3.x 是从 javax * 包迁移到 jakarta * 包的大版本，底层 API 的包名做了调整，老版本的 dynamic-datasource 没有适配这个变更。对应关系我整理了一张表：

如果不是非要上 SpringBoot 3 不可，我建议先稳住 2.7.x。这个版本生态成熟，网上能搜到的资料最多，遇到问题最容易解决。如果团队已经定了 SpringBoot 3，那就把 dynamic-datasource 升到 3.6.0 以上，同时注意 MyBatis-Plus 也要用 3.5.4+ 的版本，否则同样存在 mybatis 集成兼容的问题。

5.2 SQL Server 2008 R2 驱动与 TLS 兼容问题

这个坑我几乎可以断定，凡是连 SQL Server 2008 R2 的同学都会遇到。

现象是这样的：用最新版 SQL Server 驱动（比如 12.x）连 2008 R2，连接会失败，报错信息类似下面这样：

text复制The driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption.
Error: "SQL Server did not return a response. The connection has been closed."

原因是 2008 R2 比较老，默认只支持 TLS 1.0，而新版 JDBC 驱动出于安全考虑，默认要求 TLS 1.2 以上，两边协议对不上，握手失败。

我用的解法是双管齐下：

第一，驱动降级到 9.4.1.jre8，这个版本还保留了对老数据库的兼容逻辑，会自动协商协议。第二，连接串加上 encrypt=false，明确告诉驱动不需要启用加密。这两步做完，连接就稳稳的了。

如果你的 SQL Server 是 2012 以上版本，可以不用降驱动版本，但建议保留 encrypt=false;trustServerCertificate=true 的组合，避免自签名证书导致的证书链校验失败问题。

5.3 PostgreSQL 锁文件权限错误

还有一个高频问题，但不是出在 Java 端，而是出在 PostgreSQL 服务端。环境是 Linux，PostgreSQL 装好后启动时报：

text复制FATAL: could not create lock file "/var/run/postgresql/.s.PGSQL.5432.lock": Permission denied

原因很简单，/var/run/postgresql 目录的所有者是 root，而 PostgreSQL 服务是以 postgres 用户跑的，没有权限在这个目录下创建 socket 文件。

解决的姿势有两种。一种是修正目录权限：

bash复制sudo mkdir -p /var/run/postgresql
sudo chown postgres:postgres /var/run/postgresql

另一种是改 socket 目录配置，在 postgresql.conf 里把 unix_socket_directories 指向一个 postgres 用户有权限的目录，比如 /tmp，然后重启服务。

这个问题本身和 SpringBoot 无关，但在联调环境里特别常见，所以放在了这里一起说。很多时候我们排查了很久 Java 代码，最后发现是数据库服务自己没跑起来，这种挫败感我太懂了。

5.4 SQL Server 用户 'sa' 登录失败

SQL Server 侧另一个高频问题，就是 sa 账号登录失败，报错信息是：

text复制Login failed for user 'sa'. (ClientConnectionId:xxxx)

通常原因是 SQL Server 的认证模式没设置对。SQL Server 安装时默认是 Windows 身份验证模式，这种情况下 sa 账号是被禁用的，用密码登录 sa 自然失败。

解决方法是在 SQL Server Management Studio（SSMS）里，右键服务器选择“属性”，在“安全性”选项卡中，把服务器身份验证改为“SQL Server 和 Windows 身份验证模式”。然后在“安全性 → 登录名 → sa”里启用该账户，设置一个强密码，最后重启 SQL Server 服务让配置生效。

需要注意重启 SQL Server 服务这个动作一定要做，只改配置不重启，连接依然会失败。而且重启期间所有依赖这个库的服务都会断连，最好在业务低峰期操作。

5.5 Named Pipes 连接失败

还有一个连接 SQL Server 时可能遇到的报错，来自 ODBC 驱动的场景：

text复制[08001] [Microsoft][ODBC Driver 17 for SQL Server]Named Pipes Provider: Could not open a connection to SQL Server

这个错误虽然描述的是 ODBC，但在 JDBC 连接场景下可能触发相似问题：客户端尝试用 Named Pipes 协议连接，但服务端没有开启这个协议。

解决办法有两个方向。一个是在 SQL Server Configuration Manager 里，确认 “Client Protocols” 中的 TCP/IP 已启用，并且把 TCP/IP 调到最前优先。

另一个方向更直接：在连接串里明确指定 TCP 协议。JDBC 连接串可以通过 instanceName 或者 socketFactory 之类的方式指定，但最省事的方法是先设好 Server= 为 IP 加端口形式（如 jdbc:sqlserver://192.168.1.100:1433;DatabaseName=legacy_db），这样驱动默认走 TCP，不会去尝试 Named Pipes。

附：整套排查思路的核心要点

如果你按照上面的步骤还是没搞定，我建议回头梳理一下排查思路。

多数据源连不上的问题，百分之九十的根因可以归为三类：第一是依赖版本不对（SpringBoot 版本、驱动版本），第二是连接串格式问题（尤其是 SQL Server 的分号风格和加密参数），第三是数据库服务端本身的配置（认证模式、端口、协议）。我每次排查都是按这个顺序来，大多数情况下能很快定位。

最后一个经验是：多数据源这种基础能力，一定要在最开始就做好“验证开关”。我后来在项目里加了一个简单的测试接口，专门返回两个库各自查询当前时间的 SQL 结果，任何环境部署完先点这个接口，两个库通不通一目了然。这样可以避免排查业务问题时，还要花时间判断是不是数据源的问题。

最后再分享一个小技巧，配置多数据源的时候，一定要在类名、配置项、数据源名称上保持一套统一的前缀。比如 PostgreSQL 相关的类都带 Pg，SQL Server 相关的类都带 Sqls。这个习惯在项目膨胀之后会救你一命，不然几十个 Service、几十个 Mapper 堆在一起，你很难分清哪个类走哪个库，改错数据源就是那种“看似代码没问题、数据偏偏是错的”的灵异事件。