Implementation:Apache Shardingsphere DatabaseRuleConfigurationManager Refresh
| Knowledge Sources | |
|---|---|
| Domains | Configuration_Management, Distributed_Systems |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Concrete tool for rebuilding in-memory rule objects from updated configuration state without requiring a restart, provided by the ShardingSphere mode core module.
Description
The refresh method on DatabaseRuleConfigurationManager rebuilds the in-memory rule objects for a specific database after a configuration change. It is the final step in the dynamic rule configuration change pipeline, transforming persisted configuration data into live behavioral objects used by the query execution engine.
The method is synchronized to prevent concurrent rule rebuilds from interfering with each other, and it handles two distinct code paths:
Partial Update Path (optimized):
If the existing rule for the given configuration class implements PartialRuleUpdateSupported, the method first attempts a partial update:
- Calls partialUpdate(ruleConfig) on the existing rule, which returns a boolean indicating whether schema metadata refresh is needed.
- Calls updateConfiguration(ruleConfig) to apply the configuration change to the existing rule object in-place.
- If partialUpdate returns false (no schema refresh needed), the method returns early without rebuilding metadata contexts. This is a significant performance optimization for large deployments.
- If schema refresh is needed, execution falls through to the full rebuild path.
Full Rebuild Path:
When partial update is not supported or schema refresh is required:
- Remove old rules: Filters the database's rule collection to find rules whose configuration class is assignable from the new configuration class, and removes them.
- Build new rule: If reBuildRules is true, constructs a new ShardingSphereRule using DatabaseRulesBuilder.build() with the database name, protocol type, remaining rules, new rule configuration, compute node instance context, and resource metadata.
- Update metadata contexts: Extracts the configuration from all remaining rules, creates new metadata contexts via MetaDataContextsFactory.createByAlterRule(), and applies them using metaDataContexts.update().
- Close old rules: Iterates through the removed rule objects and closes any that implement AutoCloseable, releasing held resources.
The companion class GlobalConfigurationManager provides a similar alterGlobalRuleConfiguration method for global rules. It removes the matching global rule, closes it if needed, builds a new global rule using GlobalRulesBuilder.buildSingleRules(), replaces the global rule metadata collection, and updates the metadata contexts with a new ShardingSphereMetaData instance.
Usage
This method is called by DatabaseRuleItemManager.alter() and DatabaseRuleItemManager.drop() after they have mutated the RuleConfiguration object. It is the terminal step that makes configuration changes effective in the running system.
Code Reference
Source Location
- Repository: Apache ShardingSphere
- File: mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/manager/rule/DatabaseRuleConfigurationManager.java
- Lines: 59-72 (refresh method), 74-83 (refreshMetadata with rebuild), 85-89 (refreshMetadata with context update)
Related file for global rules:
- File: mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/manager/rule/GlobalConfigurationManager.java
- Lines: 53-63 (alterGlobalRuleConfiguration method)
Signature
// Database rule refresh
@SuppressWarnings({"unchecked", "rawtypes"})
public synchronized void refresh(final String databaseName, final RuleConfiguration ruleConfig, final boolean reBuildRules) throws SQLException
// Global rule alteration (in GlobalConfigurationManager)
public synchronized void alterGlobalRuleConfiguration(final RuleConfiguration ruleConfig)
Import
import org.apache.shardingsphere.mode.metadata.manager.rule.DatabaseRuleConfigurationManager;
import org.apache.shardingsphere.mode.metadata.manager.rule.GlobalConfigurationManager;
I/O Contract
Inputs (DatabaseRuleConfigurationManager.refresh)
| Name | Type | Required | Description |
|---|---|---|---|
| databaseName | String | Yes | The name of the database whose rules need to be rebuilt. |
| ruleConfig | RuleConfiguration | Yes | The updated rule configuration. The configuration class type is used to match and replace the existing rule. |
| reBuildRules | boolean | Yes | Whether to actually build a new rule object. Set to true for alter operations and for drop operations when the configuration is non-empty. Set to false when the configuration becomes empty after a drop. |
Inputs (GlobalConfigurationManager.alterGlobalRuleConfiguration)
| Name | Type | Required | Description |
|---|---|---|---|
| ruleConfig | RuleConfiguration | No | The updated global rule configuration. If null, the method returns immediately without performing any action. |
Outputs
| Name | Type | Description |
|---|---|---|
| return (refresh) | void | No return value. Throws SQLException if the metadata context creation fails. |
| return (alterGlobalRuleConfiguration) | void | No return value. The method completes when the global rule has been rebuilt and the metadata contexts updated. |
Usage Examples
// DatabaseRuleConfigurationManager.refresh is called by DatabaseRuleItemManager.alter():
// (This is internal framework code, shown for understanding the call chain)
// In DatabaseRuleItemManager.alter():
RuleItemConfigurationChangedProcessor processor = TypedSPILoader.getService(
RuleItemConfigurationChangedProcessor.class,
new RuleChangedItemType(databaseRuleNodePath.getRuleType(), databaseRuleNodePath.getDatabaseRuleItem().getType()));
String yamlContent = metaDataPersistFacade.getVersionService().loadContent(new VersionNodePath(databaseRuleNodePath));
RuleConfiguration currentRuleConfig = processor.findRuleConfiguration(metaDataContexts.getMetaData().getDatabase(databaseName));
String itemName = databaseRuleNodePath.getDatabaseRuleItem().getName();
synchronized (this) {
processor.changeRuleItemConfiguration(itemName, currentRuleConfig, processor.swapRuleItemConfiguration(itemName, yamlContent));
databaseRuleConfigManager.refresh(databaseName, currentRuleConfig, true);
}
// GlobalConfigurationManager.alterGlobalRuleConfiguration is called for global rule changes:
GlobalConfigurationManager globalConfigManager = metaDataContextManager.getGlobalConfigurationManager();
// Alter a global rule (e.g., authority rule, transaction rule)
globalConfigManager.alterGlobalRuleConfiguration(newAuthorityRuleConfig);
// Internally:
// 1. Check for null ruleConfig (return if null)
// 2. Remove existing rule matching ruleConfig.class, close if AutoCloseable
// 3. Build new rule via GlobalRulesBuilder.buildSingleRules(ruleConfig, databases, props)
// 4. Clear and replace global rule metadata collection
// 5. Update metadata contexts with new ShardingSphereMetaData