Skip to content

datasource-dialect-plugin-spec.md

Latest commit

 

History

History
144 lines (109 loc) · 6.3 KB

datasource-dialect-plugin-spec.md

File metadata and controls

144 lines (109 loc) · 6.3 KB
Raw

Data Source Dialect Plugin Spec

Scope

The data source dialect plugin type isolates database-specific SQL behavior from Nacos persistence logic. It covers SQL dialect functions, pagination, generated primary keys, and mapper implementations for Nacos tables.

This is an exclusive-selection plugin. The active dialect is selected by the SQL platform configuration, currently spring.sql.init.platform with legacy compatibility for spring.datasource.platform. Common lifecycle and state rules are defined by the Nacos Plugin Spec, and bundled database families are defined by the Default Data Source Dialect Implementation Spec.

The plugin exists because Nacos persistence should keep one logical schema and one repository contract while allowing different database dialects. A dialect plugin is not a persistence domain owner; it translates the repository contract into database-specific SQL. The persistence and dump boundary is defined by the Persistence And Dump Spec.

Domain modules may still own concrete persistence implementations because stored records usually carry domain semantics. For example, Config repository services own Config publish, history, gray release, and capacity semantics, while this plugin only supplies the database-specific SQL dialect and mapper layer used by those repositories.

Concepts

Concept Meaning
SQL platform Deployment-selected database type, such as derby, mysql, postgresql, or oracle.
Dialect Database-level SQL behavior such as pagination, generated keys, and functions.
Mapper Table-level SQL provider for one logical Nacos table and one database type.
Logical schema Nacos table and column semantics shared by all databases.

Repository implementations choose logical operations and invoke mappers where needed. Mappers must not decide resource identity, authorization, compatibility policy, or user-visible domain behavior.

The SQL platform must select both a DatabaseDialect and the mapper set for the same database family. Mixing a dialect from one database with mappers from another database is invalid.

SPI

Dialect implementations provide DatabaseDialect.

Method Requirement
getType() Stable database type, such as derby, mysql, postgresql, or oracle.
getLimitTopSqlWithMark(sql) Add placeholder-based top limit SQL.
getLimitPageSqlWithMark(sql) Add placeholder-based page SQL.
getLimitPageSql(sql, pageNo, pageSize) Add page SQL with numeric values.
getLimitPageSqlWithOffset(sql, startOffset, pageSize) Add offset page SQL.
getPagePrevNum(page, pageSize) Return first pagination parameter.
getPageLastNum(page, pageSize) Return second pagination parameter.
getReturnPrimaryKeys() Return generated key columns.
getFunction(functionName) Map logical function names to dialect SQL functions.

Table mapper plugins implement com.alibaba.nacos.plugin.datasource.mapper.Mapper for table-specific SQL. Dialect and mapper implementations must be packaged and loaded together for a database family.

Mapper implementations must provide base CRUD SQL and table-specific SQL for repository operations. Current mapper families cover:

  • current config data, gray data, tags, and history;
  • namespace and capacity records;
  • AI resource metadata and version records.

Starting with the Nacos 3.3 line, datasource dialect plugins are not expected to provide runtime Config migration queries for empty-tenant/default-namespace duplicates or legacy beta/tag gray tables. Such migration, if needed for a pre-3.0 deployment, is an upgrade prerequisite rather than a server runtime mapper responsibility.

MapperManager loads mapper SPI implementations and indexes them by dataSource + tableName. Missing data source or table mapper is a startup or operation error, not an empty result.

Selection And State

The core plugin manager exposes this plugin type as datasource-dialect. Only the configured dialect should be enabled by default. Built-in critical dialects required by the server cannot be disabled while in use.

If a requested dialect is disabled, startup or persistence operations must fail explicitly. If the requested dialect is missing, the current manager searches for another enabled dialect and logs the fallback. This fallback is compatibility behavior; new deployments should configure an explicit supported SQL platform.

Current DatabaseDialectManager checks unified plugin state for datasource-dialect:{databaseType} before returning a dialect. A disabled dialect must not participate in persistence operations.

Configuration

The SQL platform is selected by:

spring.sql.init.platform=${databaseType}

For compatibility with older deployments:

spring.datasource.platform=${databaseType}

Datasource connection properties remain owned by Nacos persistence configuration and the database driver. The dialect plugin must not reinterpret unrelated database connection settings.

Compatibility Rules

Database plugins must preserve Nacos table semantics, transaction expectations, pagination order, and optimistic update behavior. A dialect plugin must not change the logical schema or resource model.

Implementations must:

  • keep logical table names and column semantics stable;
  • use placeholder-based SQL for runtime values;
  • keep pagination deterministic for the same query order;
  • preserve generated primary key behavior expected by repositories;
  • keep SQL function names behind getFunction(functionName);
  • document database version requirements and migration requirements.