wehub-resource-sync
76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
<!--
|
||
Copyright 1999-2026 Alibaba Group Holding Ltd.
|
||
|
||
Licensed under the Apache License, Version 2.0 (the "License");
|
||
you may not use this file except in compliance with the License.
|
||
You may obtain a copy of the License at
|
||
|
||
http://www.apache.org/licenses/LICENSE-2.0
|
||
|
||
Unless required by applicable law or agreed to in writing, software
|
||
distributed under the License is distributed on an "AS IS" BASIS,
|
||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
See the License for the specific language governing permissions and
|
||
limitations under the License.
|
||
-->
|
||
|
||
# 默认数据源方言插件实现规范
|
||
|
||
## 范围
|
||
|
||
内置数据源方言实现位于 `plugin-default-impl/nacos-default-datasource-plugin`。它提供随
|
||
Nacos 服务端发行包一起发布的数据库方言和表级 mapper，是
|
||
[数据源方言插件规范](datasource-dialect-plugin-spec.md)的内置实现。
|
||
|
||
默认实现集合是持久化兼容层，不得引入数据库特有的资源语义。
|
||
|
||
## 内置数据库类型
|
||
|
||
当前实现包含以下数据库族：
|
||
|
||
| 数据库类型 | Dialect provider | Mapper 包 |
|
||
|------------|------------------|-----------|
|
||
| `derby` | `DerbyDatabaseDialect` | `impl.derby` |
|
||
| `mysql` | `MysqlDatabaseDialect` 和 `DefaultDatabaseDialect` | `impl.mysql` |
|
||
| `postgresql` | `PostgresqlDatabaseDialect` | `impl.postgresql` |
|
||
| `oracle` | `OracleDatabaseDialect` | `impl.oracle` |
|
||
|
||
每个数据库包必须同时注册
|
||
`com.alibaba.nacos.plugin.datasource.dialect.DatabaseDialect` 和
|
||
`com.alibaba.nacos.plugin.datasource.mapper.Mapper` SPI 文件。
|
||
|
||
## Mapper 覆盖范围
|
||
|
||
每个内置数据库族都应提供以下 mapper 实现：
|
||
|
||
- 当前配置表：`config_info`、`config_info_gray`、`config_tags_relation`、`his_config_info`；
|
||
- 容量和命名空间表：`tenant_info`、`tenant_capacity`、`group_capacity`；
|
||
- AI Registry 表：AI 资源元数据和 AI 资源版本。
|
||
|
||
从 Nacos 3.3 版本线开始，内置数据库族不再要求提供默认 namespace 存储重复记录或 legacy
|
||
beta/tag 灰度表的运行时 Config 迁移 mapper。仍保留 pre-3.0 `config_info_beta` 或
|
||
`config_info_tag` 数据的部署，必须在升级到依赖当前 mapper 集合的 3.3 服务端前完成迁移。
|
||
|
||
如果未来 Nacos 版本新增持久化表，在该表成为文档化服务端能力之前，内置数据库族必须补充
|
||
对应 mapper。
|
||
|
||
## 选择
|
||
|
||
Nacos 从 `spring.sql.init.platform` 选择数据库类型，并兼容旧配置
|
||
`spring.datasource.platform`。
|
||
|
||
当选择类型为 `mysql` 时，使用 MySQL mapper 和 MySQL 兼容的默认 dialect 行为。当选择类型
|
||
为 `derby` 时，Derby 仍是 standalone 开发和本地测试的嵌入式默认数据库。
|
||
|
||
## 兼容性
|
||
|
||
内置实现必须：
|
||
|
||
- 在不同数据库族之间保持 Nacos 逻辑 schema；
|
||
- 保持 SQL 占位符和参数顺序与 repository 代码兼容；
|
||
- 保持插入操作期望的生成主键列；
|
||
- 保持 AI 资源 mapper 行为与[资源模型](../design/resource-model-spec.md)对齐；
|
||
- 当某个数据库族需要 schema 变化时补充迁移说明。
|
||
|
||
服务端正在使用的内置数据库方言插件属于关键插件，不能通过插件状态禁用，否则会破坏持久化。
|