Implementation:Apache Shardingsphere ClusterMetaDataManagerPersistService AlterRuleConfiguration

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

Overview

Concrete tool for initiating database rule configuration changes in a ShardingSphere cluster, provided by the ShardingSphere cluster mode module.

Description

The alterRuleConfiguration method on ClusterMetaDataManagerPersistService is the entry point for modifying database-scoped rule configurations in cluster mode. When a user executes a DistSQL ALTER statement or invokes the management API, this method is called to persist the new rule configuration and wait for the change to propagate across the cluster.

The method performs the following operations in sequence:

1. Null guard: Returns immediately if the provided rule configuration is null, preventing unnecessary persistence operations.
2. Snapshot current state: Creates a snapshot of the current MetaDataContexts (both metadata and statistics) to serve as a comparison baseline for detecting when the reload has completed.
3. Persist rule configuration: Delegates to MetaDataPersistFacade.getDatabaseRuleService().persist() which writes the configuration to the distributed repository with versioned storage. This triggers the active version switch, which in turn emits DataChangedEvent notifications to all cluster watchers.
4. Wait for reload: Calls getReloadedMetaDataContexts() which first sleeps for 3 seconds to allow initial propagation, then polls with a RetryExecutor (30-second timeout, 1-second interval) until the MetaDataContexts reference has changed from the original snapshot. This confirms that the event-driven pipeline has processed the change and rebuilt the in-memory rules.
5. Persist reloaded metadata: Persists any database-level metadata changes (schema alterations, table modifications) that resulted from the rule reconfiguration by comparing the reloaded database against the original.

This class implements the MetaDataManagerPersistService interface, which is the SPI contract for metadata persistence operations. In standalone mode, a different implementation handles persistence without distributed event propagation.

Usage

This method is called by ShardingSphere's DistSQL execution engine when processing rule alteration statements such as:

• ALTER SHARDING TABLE RULE
• ALTER ENCRYPT RULE
• ALTER READWRITE_SPLITTING RULE
• Any DistSQL statement that modifies a database-scoped rule configuration

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: mode/type/cluster/core/src/main/java/org/apache/shardingsphere/mode/manager/cluster/persist/service/ClusterMetaDataManagerPersistService.java
• Lines: 187-196

Signature

@Override
public void alterRuleConfiguration(final ShardingSphereDatabase database, final RuleConfiguration toBeAlteredRuleConfig)

Import

import org.apache.shardingsphere.mode.manager.cluster.persist.service.ClusterMetaDataManagerPersistService;

I/O Contract

Inputs

Name	Type	Required	Description
database	ShardingSphereDatabase	Yes	The database object representing the target database whose rule configuration is being altered. Provides the database name and current metadata.
toBeAlteredRuleConfig	RuleConfiguration	No	The new rule configuration to persist. If null, the method returns immediately without performing any action.

Outputs

Name	Type	Description
return	void	This method does not return a value. It completes when the configuration has been persisted and the cluster has reloaded the metadata, or throws an exception if the reload times out.

Usage Examples

// Example: Altering a sharding rule configuration in cluster mode
// This is typically called by the DistSQL execution engine, not directly by user code

ShardingSphereDatabase database = metaDataContexts.getMetaData().getDatabase("my_database");
RuleConfiguration newShardingConfig = buildNewShardingRuleConfiguration();

// The persist service is obtained from the context manager
MetaDataManagerPersistService persistService = contextManager.getPersistServiceFacade().getMetaDataManagerPersistService();
persistService.alterRuleConfiguration(database, newShardingConfig);

// After this call returns, all cluster nodes have applied the new sharding rule

// Internal flow within alterRuleConfiguration:
// 1. Null check on toBeAlteredRuleConfig
// 2. Snapshot: new MetaDataContexts(currentMetaData, currentStatistics)
// 3. Persist: metaDataPersistFacade.getDatabaseRuleService().persist(database.getName(), Collections.singleton(toBeAlteredRuleConfig))
// 4. Wait: getReloadedMetaDataContexts(originalMetaDataContexts) -- blocks until reload detected
// 5. Finalize: metaDataPersistFacade.getDatabaseMetaDataFacade().persistReloadDatabase(...)

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Configuration_Change_Initiation