MySQL应用迁移PolarDB for MySQL避坑指南与配置要点

在进行数据库架构升级，将应用从MySQL迁移至阿里云PolarDB for MySQL时，为了充分发挥其性能并确保迁移过程平稳，需要对应用配置进行一系列调整。PolarDB for MySQL完全兼容开源MySQL协议，但在驱动和部分配置上存在差异。以下为迁移过程中关键的配置修改项与避坑指南。

1. 修改Maven依赖中的JDBC驱动

首先，需要将项目依赖中的MySQL官方驱动替换为PolarDB官方提供的JDBC驱动。

原依赖：

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
</dependency>

修改为：

<dependency>
    <groupId>com.alibaba.polardbx</groupId>
    <artifactId>polardbx-connector-java</artifactId>
    <version>${polardbx-mysql-connector-java.version}</version>
</dependency>

请将 ${polardbx-mysql-connector-java.version} 替换为实际使用的驱动版本号。

2. 修改数据库连接URL配置

驱动更换后，应用配置文件中的数据库连接字符串（JDBC URL）也需要相应修改。

原连接配置：

jdbc:mysql://ip:3306/database?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai

修改为：

jdbc:polardbx://ip:3306/database?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowMultiQueries=true&ignoreVip=false

关键参数说明：

• ignoreVip=false：此参数为必需项。无论是连接PolarDB的单节点还是集群版，都必须显式添加此参数并设置为false，否则会导致连接异常。这是在数据库与中间件迁移到云原生数据库时常见的特定配置。

3. 配置分页插件（如PageHelper）

如果您在项目中使用MyBatis分页插件（例如PageHelper），需要在配置中明确指定数据库方言。虽然部分开源插件可能有默认配置，但使用PolarDB驱动时，明确指定可以避免潜在的分页查询错误。

推荐在application.yml中添加或确认以下配置：

pagehelper:
  helperDialect: mysql
  reasonable: true
  supportMethodsArguments: true
  params: count=countSql

4. 在PolarDB控制台配置白名单

为保证访问安全，迁移后的应用服务器IP地址需要添加到PolarDB实例的白名单中。

登录阿里云PolarDB控制台，找到目标实例，进入“数据安全性” -> “白名单设置”页面。创建一个新的分组或修改默认分组，将应用部署所在服务器的IP地址（通常是ECS内网IP）添加进去，以确保网络连通性。

5. 上传并激活License证书（如需要）

根据您购买的PolarDB实例类型，可能需要在控制台上传License证书以激活全部功能。

在控制台实例的“配置信息”或相关管理页面，找到证书上传入口。请注意：

1. 上传或更新License会导致数据库实例立即重启，请在业务低峰期操作。
2. 确保证书文件格式为 .lic，且大小不超过1024KB。

完成以上五个步骤的检查和配置，您的应用从MySQL到PolarDB for MySQL的核心迁移配置就基本完成了。建议在正式切换前，在测试环境充分验证，确保所有功能正常运行。