Multiple Data Sources

Nacos uses datasource dialect plugins to support different databases. A dialect plugin handles SQL dialect differences, pagination, database functions, generated keys, and table-level mapper implementations for the Nacos logical schema.

Since Nacos 2.2.0, datasource dialects can be extended through SPI. In the current Nacos next version, the official default implementation supports four database types: derby, mysql, postgresql, and oracle.

In unified plugin management, the plugin type is datasource-dialect, its execution mode is EXCLUSIVE, its load phase is STANDARD, and the type is critical. The four built-in plugin identities are datasource-dialect:derby, datasource-dialect:mysql, datasource-dialect:postgresql, and datasource-dialect:oracle. None declares a ConfigItemDefinition, so the management APIs report configurable=false; connection and pool settings belong to the datasource module, not to an individual dialect plugin.

Officially Supported Databases

The official implementation is located in the plugin-default-impl/nacos-default-datasource-plugin module of the Nacos source repository. Each database type registers both DatabaseDialect and table-level Mapper SPI files.

Select A Database Type

Use the standard selector to choose the database type:

nacos.plugin.datasource-dialect.type=mysql

spring.sql.init.platform remains a legacy alias, and the standard key wins when both are present. The older spring.datasource.platform property has been removed and is no longer read. Dialect selection is fixed at startup and cannot be changed through the runtime plugin status API.

If the platform is not specified, Nacos selects storage based on the running mode:

The selected dialect is the active critical provider. If it is missing or disabled, startup fails with the selected dialect and property instead of falling back to another discovered provider. For production, use an external database and import the matching schema before starting Nacos.

External Database Configuration

PostgreSQL example:

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 or later example:

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

The stable datasource module settings are listed below. They are static, require restart, and are not exposed by the dialect plugin detail or PUT configuration API.

For the same item, the canonical key wins over its alias. Indexed items are resolved independently, so canonical url.0 and legacy url.1 can coexist during migration. nacos.plugin.datasource.db.pool.config.{hikari-property} can still pass additional JavaBean properties to HikariCP, but only the stable subset above is a long-term Nacos configuration contract.

Configure Multiple Database Connections

db.num is the number of external database connections. Nacos performs health checks and master selection across these connections. All connections should belong to the same database type.

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

If all connections share credentials, configure only the unindexed nacos.plugin.datasource.db.user and nacos.plugin.datasource.db.password.

Community Datasource Plugins

Besides the four official database types, the Nacos community maintains more datasource plugins in nacos-group/nacos-plugin. The repository currently contains these datasource extension modules:

For community plugins, follow the corresponding README for version compatibility, schema files, driver dependencies, and deployment steps. Before production use, validate schema initialization, startup, read/write behavior, upgrade, and rollback in a test environment.

Deploy An External Plugin

When using a community or custom plugin:

1. Select a plugin version that matches your Nacos version.
2. Build the plugin JAR.
3. Put the plugin JAR and the database driver JAR into ${nacos.home}/plugins, or add them to the startup classpath.
4. Set nacos.plugin.datasource-dialect.type to the database type declared by the plugin.
5. Import the matching database schema.
6. Restart Nacos and check the startup logs to confirm that the target dialect and mappers are loaded.

Develop A Custom Datasource Plugin

A custom datasource plugin must implement at least two SPI types:

The dialect and mappers for the same database type must be packaged and loaded together. Providing only one side causes startup or runtime failures.

Current mapper coverage includes:

• Config tables: config_info, config_info_gray, config_tags_relation, his_config_info;
• Capacity and namespace tables: tenant_info, tenant_capacity, group_capacity;
• AI resource tables: ai_resource, ai_resource_version.

Starting with Nacos 3.3, current mappers no longer include Config migration queries for versions before 3.0 and no longer include legacy config_info_beta or config_info_tag table mappers. Deployments that still have this legacy data must migrate beta/tag gray data into the current config_info_gray gray model before upgrading to 3.3.

Use the official derby, mysql, postgresql, and oracle modules as references. Register plugin implementations under META-INF/services:

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

Troubleshooting