Implementation:Apache Shardingsphere DatabaseRulePersistService Persist

Knowledge Sources	Apache ShardingSphere
Domains	Configuration_Management, Distributed_Systems
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for persisting database rule configurations with version tracking, provided by the ShardingSphere mode core module.

Description

The persist method on DatabaseRulePersistService writes a collection of rule configurations to the distributed repository with automatic version management. It decomposes each rule configuration into granular node tuples, persists each tuple through the VersionPersistService (which handles version numbering and active version switching), and returns a collection of MetaDataVersion objects that describe what changed.

The method performs these steps:

1. YAML conversion: Converts each RuleConfiguration to its YAML representation using YamlRuleConfigurationSwapperEngine. This produces YamlRuleConfiguration objects that capture the rule's structure in a serializable format.
2. Tuple decomposition: Each YAML configuration is decomposed into RuleNodeTuple objects by the YamlRuleNodeTupleSwapperEngine. Each tuple represents a single rule item (e.g., one sharding table rule, one algorithm definition) with its repository path and serialized content.
3. Versioned persistence: Each tuple is passed to the private persistTuples method, which calls versionPersistService.persist(new VersionNodePath(tuple.getNodePath()), tuple.getContent()) for each tuple. The VersionPersistService determines the next version number, writes the content at the versioned path, switches the active version pointer, and cleans up old versions.
4. MetaDataVersion collection: For each persisted tuple, a MetaDataVersion is constructed with the node path and the previous active version (calculated as max(INIT_VERSION, nextVersion - 1)). This collection is returned to the caller.

The returned MetaDataVersion collection enables the caller to know exactly which repository paths were modified and what their previous version numbers were, which is essential for rollback scenarios and audit logging.

Usage

This method is called whenever database-scoped rule configurations need to be written to the distributed repository. Primary callers include:

• ClusterMetaDataManagerPersistService.alterRuleConfiguration() for persisting altered rules.
• ClusterMetaDataManagerPersistService.alterSingleRuleConfiguration() for persisting single table rule changes.
• Any code path that modifies database-level rule configuration in cluster mode.

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/config/database/DatabaseRulePersistService.java
• Lines: 107-113

Signature

public Collection<MetaDataVersion> persist(final String databaseName, final Collection<RuleConfiguration> configs)

Import

import org.apache.shardingsphere.mode.metadata.persist.config.database.DatabaseRulePersistService;

I/O Contract

Inputs

Name	Type	Required	Description
databaseName	String	Yes	The name of the database whose rule configurations are being persisted.
configs	Collection<RuleConfiguration>	Yes	The collection of rule configurations to persist. Each configuration is converted to YAML, decomposed into tuples, and written with version tracking.

Outputs

Name	Type	Description
return	Collection<MetaDataVersion>	A collection of MetaDataVersion objects, one per persisted rule node tuple. Each MetaDataVersion contains the node path and the previous active version number (before this write).

Usage Examples

// Persisting a sharding rule configuration for database "my_db"
DatabaseRulePersistService databaseRuleService = metaDataPersistFacade.getDatabaseRuleService();

Collection<RuleConfiguration> configs = Collections.singleton(shardingRuleConfig);
Collection<MetaDataVersion> versions = databaseRuleService.persist("my_db", configs);

// Each MetaDataVersion in the result represents one rule item that was persisted
for (MetaDataVersion version : versions) {
    // version.getNodePath() -- the repository path of the rule item
    // version.getActiveVersion() -- the previous active version before this write
}

// Internal flow: how persist() processes each configuration
// 1. yamlSwapperEngine.swapToYamlRuleConfigurations(configs)
//    -> Converts RuleConfiguration objects to YamlRuleConfiguration objects
//
// 2. tupleSwapperEngine.swapToTuples(databaseName, yamlConfig)
//    -> Decomposes each YAML config into RuleNodeTuple objects
//    -> Each tuple has a node path (e.g., /metadata/my_db/rules/sharding/tables/t_order)
//       and content (serialized YAML for that item)
//
// 3. versionPersistService.persist(new VersionNodePath(tuple.getNodePath()), tuple.getContent())
//    -> Determines next version number
//    -> Writes content at /versions/{nextVersion}
//    -> Switches active_version pointer to nextVersion
//    -> Cleans up old version entries
//    -> Returns nextVersion

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Versioned_Change_Persistence

Uses Heuristic

• Heuristic:Apache_Shardingsphere_Version_Cleanup_After_Switch