发行包 application.properties 缺少 pool.config.driver-class-name 示例,使用 PostgreSQL/Oracle 数据源时按注释配置会启动失败
Is your feature request related to a problem? Please describe.
在 Nacos 3.x(develop 分支,3.3.0-SNAPSHOT)中,按照发行包自带 conf/application.properties 数据源段落的注释,把主数据源切换到 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?currentSchema=public
nacos.plugin.datasource.db.user=nacos
nacos.plugin.datasource.db.password=nacos启动直接失败:
Caused by: java.lang.RuntimeException: [db-load-error]load jdbc.properties error
Caused by: java.lang.RuntimeException: Driver com.mysql.cj.jdbc.Driver claims to not accept jdbcUrl, jdbc:postgresql://127.0.0.1:5432/nacos?currentSchema=public原因是 nacos.plugin.datasource.db.pool.config.driver-class-name 为空时会回落到 MySQL 驱动(ExternalDataSourceProperties.JDBC_DRIVER_NAME)。这个行为本身是有文档的:
specs/en/plugin/datasource-dialect-plugin-spec.md配置表中写明 "Blank uses the MySQL driver compatibility default";- 官网《多数据源》文档(https://nacos.io/en/docs/next/plugin/datasource-plugin/ )中的 PostgreSQL 配置示例已经包含了
nacos.plugin.datasource.db.pool.config.driver-class-name=org.postgresql.Driver这一行,但发行包自带的conf/application.properties中没有对应的示例。
问题在于发行包里的 distribution/conf/application.properties —— 绝大多数用户实际编辑的文件 —— 与上述文档不一致:
- 数据源段落只给了 MySQL 的
url/user/password模板,注释里提示"选择方言",却完全没有出现pool.config.driver-class-name这个 key,用户按注释改完方言和 URL 后不会想到还需要单独指定驱动。 - 同一个文件下方的 AI 向量数据源段落却明确写出了
nacos.ai.resource.search.vector.postgresql.driver-class-name=org.postgresql.Driver,前后不一致。 - 报错信息只说 MySQL 驱动不接受这个 URL,无法引导用户找到正确的配置项。
相关历史:#12634(外部数据源驱动配置)、#10179(同样的 [db-load-error] 报错,因未配置驱动,过期关闭)、#14489(PostgreSQL 插件文档同步)。
Describe the solution you'd like
仅补充示例配置,不改变任何运行时行为,使发行包配置与 specs/ 及官网文档保持一致:
在 distribution/conf/application.properties 的 Datasource Related Configurations 段落,db.password 之后补充:
### JDBC driver class name. Blank uses the MySQL driver as compatibility default,
### so it is REQUIRED when the dialect is not mysql, e.g. postgresql / oracle:
# nacos.plugin.datasource.db.pool.config.driver-class-name=org.postgresql.Driver可选:在 MySQL URL 示例旁补一条 PostgreSQL URL 示例,方便对照:
# nacos.plugin.datasource.db.url.0=jdbc:postgresql://127.0.0.1:5432/nacos?currentSchema=public如有需要,也可以在 specs/zh-cn/plugin/datasource-dialect-plugin-spec.md 与英文版中把 "Blank uses the MySQL driver compatibility default" 一句补充为更明确的提示(非 MySQL 方言必须显式配置)。
Additional context
- 复现环境:macOS,PostgreSQL 17,standalone 模式,
develop分支 46f26c1cf 使用mvn -Prelease-nacos构建。 - 加上
nacos.plugin.datasource.db.pool.config.driverClassName=org.postgresql.Driver后启动正常,PG 主数据源可正常工作。 - 我可以直接提交这个配置文件的 PR。
Source: alibaba/nacos