wehub-resource-sync
3.5 KiB
Default Data Source Dialect Implementation Spec
Scope
The built-in data source dialect implementations live under
plugin-default-impl/nacos-default-datasource-plugin. They provide the database
dialects and table mappers bundled with the Nacos server distribution. They are
the bundled implementations of the
Data Source Dialect Plugin Spec.
The default implementation set is a persistence compatibility layer. It must not introduce database-specific resource semantics.
Built-In Database Types
The current implementation packages these database families:
| Database type | Dialect provider | Mapper package |
|---|---|---|
derby |
DerbyDatabaseDialect |
impl.derby |
mysql |
MysqlDatabaseDialect and DefaultDatabaseDialect |
impl.mysql |
postgresql |
PostgresqlDatabaseDialect |
impl.postgresql |
oracle |
OracleDatabaseDialect |
impl.oracle |
Each database package must register both
com.alibaba.nacos.plugin.datasource.dialect.DatabaseDialect and
com.alibaba.nacos.plugin.datasource.mapper.Mapper SPI files.
Mapper Coverage
Each built-in database family is expected to provide mapper implementations for:
- current config tables:
config_info,config_info_gray,config_tags_relation,his_config_info; - capacity and namespace tables:
tenant_info,tenant_capacity,group_capacity; - AI registry tables: AI resource metadata and AI resource versions.
Starting with the Nacos 3.3 line, built-in database families are not required to
provide runtime Config migration mappers for default-namespace storage
duplicates or legacy beta/tag gray tables. Deployments that still carry
pre-3.0 config_info_beta or config_info_tag data must migrate those rows
before upgrading to a 3.3 server that relies on the current mapper set.
If a future Nacos version adds a persistent table, the built-in database families must add the corresponding mapper before that table becomes a documented server feature.
Selection
Nacos selects the database type from spring.sql.init.platform, with legacy
compatibility for spring.datasource.platform.
When the selected type is mysql, MySQL mappers and MySQL-compatible default
dialect behavior are used. When the selected type is derby, Derby remains the
embedded default for standalone development and local testing.
Compatibility
Built-in implementations must:
- preserve Nacos logical schema across database families;
- keep SQL placeholders and parameter order compatible with repository code;
- preserve generated key columns expected by insert operations;
- keep AI resource mapper behavior aligned with the resource model;
- add migration notes when a database family requires schema changes.
Built-in database dialect plugins are critical while the server is using them. They cannot be disabled through plugin state without breaking persistence.