多数据源插件

Nacos 通过数据源方言插件适配不同数据库。插件负责处理 SQL 方言、分页、函数、主键返回方式，以及 Nacos 逻辑表对应的 mapper 实现。

从 Nacos 2.2.0 开始，数据源方言可以通过 SPI 扩展。当前 Nacos next 版本的官方默认实现已经支持 4 种数据库：derby、mysql、postgresql 和 oracle。

在统一插件管理中，本插件类型为 datasource-dialect，执行模式为 EXCLUSIVE，加载阶段为 STANDARD，并且是 critical 类型。四个内置插件身份分别为 datasource-dialect:derby、datasource-dialect:mysql、datasource-dialect:postgresql 和 datasource-dialect:oracle。它们均不声明 ConfigItemDefinition，因此管理端显示 configurable=false；数据库连接和连接池参数属于数据源模块配置，而不是任一方言插件的私有配置。

官方支持的数据库

默认数据源实现位于 Nacos 代码仓库的 plugin-default-impl/nacos-default-datasource-plugin 模块。每个数据库类型都同时注册 DatabaseDialect 和表级 Mapper SPI。

选择数据库类型

使用标准选择键指定数据库类型：

nacos.plugin.datasource-dialect.type=mysql

spring.sql.init.platform 是仍受支持的历史 alias；同时配置时标准键优先。更早的 spring.datasource.platform 已移除，不再读取。方言选择在启动时确定，不能通过运行时插件状态 API 切换。

如果没有显式指定数据库类型，Nacos 会根据运行模式选择默认存储：

选中的方言是 active critical provider。插件缺失或被禁用时，Nacos 会明确报错并终止启动，不会回退到另一个已发现的方言。生产环境建议使用外置数据库，并在启动 Nacos 前导入对应数据库的 schema。

外置数据库配置

以 PostgreSQL 为例：

nacos.plugin.datasource-dialect.type=postgresql
nacos.plugin.datasource.db.num=1
nacos.plugin.datasource.db.url.0=jdbc:postgresql://127.0.0.1:5432/nacos
nacos.plugin.datasource.db.user=nacos
nacos.plugin.datasource.db.password=nacos
nacos.plugin.datasource.db.pool.config.driver-class-name=org.postgresql.Driver
nacos.plugin.datasource.db.pool.config.connection-test-query=SELECT 1

以 Oracle 12c 及以上版本为例：

nacos.plugin.datasource-dialect.type=oracle
nacos.plugin.datasource.db.num=1
nacos.plugin.datasource.db.url.0=jdbc:oracle:thin:@127.0.0.1:1521:XE
nacos.plugin.datasource.db.user=nacos
nacos.plugin.datasource.db.password=nacos
nacos.plugin.datasource.db.pool.config.driver-class-name=oracle.jdbc.OracleDriver
nacos.plugin.datasource.db.pool.config.connection-test-query=SELECT 1 FROM dual

稳定的数据源模块配置如下。它们均为静态、重启生效，不会出现在方言插件详情或 PUT 配置 API 中。

同一配置同时出现标准键和 alias 时，标准键优先；索引项逐项解析，迁移期间允许标准 url.0 与历史 url.1 并存。nacos.plugin.datasource.db.pool.config.{hikari-property} 仍可向 HikariCP 传递其他 JavaBean 属性，但只有上表列出的稳定子集属于长期配置契约。

JDBC 驱动的选择

Nacos 3.3 按以下顺序选择外置数据源的驱动：

1. 使用显式配置的驱动类。标准键 nacos.plugin.datasource.db.pool.config.driver-class-name 优先于历史 db.pool.config.driverClassName；已有有效配置不会被方言默认值覆盖。
2. 未配置驱动时，使用所选 DatabaseDialect 的 getDefaultDriverClassName()。
3. 方言没有提供默认值时，保留 com.mysql.cj.jdbc.Driver 作为兼容回退。使用其他数据库的旧插件时，应显式配置对应驱动。

内置方言提供以下默认值：

上面的 PostgreSQL 和 Oracle 示例保留了显式驱动配置；使用内置方言默认驱动时可省略该项。驱动类名不会自动下载驱动 JAR，仍需确保它在服务端 classpath 或 ${nacos.home}/plugins 中。

驱动回退不会将数据库方言改成 MySQL。所选方言缺失或被禁用时，仍会因方言校验失败而无法启动；改动方言或连接池配置后需重启。

配置多个数据库连接

db.num 表示外置数据库连接数量。Nacos 会对多个连接做健康检查和主库选择。多个连接应属于同一种数据库类型。

nacos.plugin.datasource-dialect.type=mysql
nacos.plugin.datasource.db.num=2
nacos.plugin.datasource.db.url.0=jdbc:mysql://db-0:3306/nacos?characterEncoding=utf8&useSSL=false&serverTimezone=UTC
nacos.plugin.datasource.db.url.1=jdbc:mysql://db-1:3306/nacos?characterEncoding=utf8&useSSL=false&serverTimezone=UTC
nacos.plugin.datasource.db.user.0=nacos
nacos.plugin.datasource.db.password.0=nacos_password_0
nacos.plugin.datasource.db.user.1=nacos
nacos.plugin.datasource.db.password.1=nacos_password_1

如果所有连接使用同一个用户名和密码，也可以只配置不带索引的 nacos.plugin.datasource.db.user 和 nacos.plugin.datasource.db.password。

社区数据源插件

除官方内置的 4 种数据库外，Nacos 社区在 nacos-group/nacos-plugin 仓库维护了一批扩展数据源插件。当前仓库中包含以下数据源扩展模块：

社区插件的版本兼容性、schema、驱动依赖和部署方式以插件仓库对应 README 为准。生产使用前，请在测试环境完成 schema、启动、读写、升级和回滚验证。

部署外部插件

如果使用社区插件或自定义插件，通常需要：

1. 选择与 Nacos 版本匹配的插件版本。
2. 编译插件并取得插件 JAR。
3. 将插件 JAR 和数据库驱动 JAR 放到 ${nacos.home}/plugins，或者通过启动参数追加到 classpath。
4. 在 application.properties 中将 nacos.plugin.datasource-dialect.type 设置为插件声明的数据库类型。
5. 导入对应数据库 schema。
6. 重启 Nacos，并检查启动日志中是否加载了目标 dialect 和 mapper。

自定义数据源插件

自定义数据源插件至少需要实现两类 SPI：

一个数据库类型的 dialect 和 mapper 必须一起打包和加载。只提供 dialect 或只提供 mapper 都会导致启动或运行时失败。

getDefaultDriverClassName() 是默认返回 null 的 SPI 方法，已有方言实现无需仅为此方法重新编译。若旧插件没有提供默认驱动，部署时应显式配置；这不免除 Nacos 3.3 对其他已移除 Mapper SPI 的迁移要求，详见插件迁移指南。

当前 mapper 覆盖范围包括：

• 配置表：config_info、config_info_gray、config_tags_relation、his_config_info；
• 容量和命名空间表：tenant_info、tenant_capacity、group_capacity；
• AI 资源表：ai_resource、ai_resource_version。

Nacos 3.3 起当前 mapper 不再包含 Config 3.0 之前兼容迁移查询，也不再包含旧 config_info_beta、config_info_tag 表 mapper。仍保留这类旧数据的部署，应在升级到 3.3 前将 beta/tag 灰度数据迁移到 config_info_gray 当前灰度模型。

开发时可以参考官方默认实现中的 derby、mysql、postgresql 和 oracle 模块。插件需要在 META-INF/services 下注册：

com.alibaba.nacos.plugin.datasource.dialect.DatabaseDialect
com.alibaba.nacos.plugin.datasource.mapper.Mapper

排障建议