Principle:Apache Shardingsphere In Memory Rule Rebuild
| Knowledge Sources | |
|---|---|
| Domains | Configuration_Management, Distributed_Systems |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
In-memory rule rebuild is the process of constructing new runtime rule objects from updated configuration state, applying configuration changes to the live system without requiring a restart.
Description
The final stage of the dynamic rule configuration change workflow is rebuilding the in-memory rule objects that govern query routing, data encryption, read-write splitting, and other database behaviors. This stage transforms the persisted configuration (a data structure) into live rule objects (behavioral components) that the query execution engine uses for every SQL statement.
The rebuild process addresses two distinct scopes:
Database-Scoped Rule Rebuild:
Database rules (sharding, encryption, shadow, etc.) are rebuilt by the DatabaseRuleConfigurationManager. The process is synchronized to prevent concurrent modifications and follows these steps:
- Rule matching: The manager identifies the existing rule whose configuration class matches the incoming rule configuration class.
- Partial update optimization: If the existing rule implements PartialRuleUpdateSupported, the manager attempts a partial update first. This allows rules that support incremental changes (e.g., adding a single sharding table without rebuilding the entire sharding rule) to apply the change efficiently. The partial update returns a flag indicating whether schema metadata needs to be refreshed.
- Full rebuild fallback: If partial update is not supported or if the rule does not implement the optimization interface, a full rebuild is performed. The old rule is removed from the rule collection, a new rule is constructed from the updated configuration using DatabaseRulesBuilder, and the metadata contexts are updated.
- Metadata refresh: The MetaDataContextsFactory creates new metadata contexts that reflect the rule change, including updated schema metadata, table metadata, and routing information.
- Resource cleanup: The old rule objects that were replaced are closed if they implement AutoCloseable, releasing any held resources such as connection pools or background threads.
Global Rule Rebuild:
Global rules (authority, transaction, SQL parser, etc.) are rebuilt by the GlobalConfigurationManager. The process:
- Removes the existing global rule whose configuration class matches the incoming configuration.
- Closes the old rule if it is AutoCloseable.
- Builds a new rule from the updated configuration using GlobalRulesBuilder.
- Replaces the global rule metadata and updates the metadata contexts.
Usage
In-memory rule rebuild is triggered at the end of the configuration change pipeline whenever:
- A rule item is altered or dropped via the change handler dispatch mechanism.
- A DistSQL statement modifies rule configurations.
- Global properties or global rule configurations are changed.
Theoretical Basis
The rebuild process implements a synchronized replace-and-close pattern:
PROCEDURE refresh_database_rule(database_name, new_rule_config, should_rebuild):
SYNCHRONIZED:
database = metadata_contexts.get_database(database_name)
rules = copy(database.rules)
// Find existing rule with matching config type
existing_rule = find_rule_by_config_class(rules, new_rule_config.class)
IF existing_rule SUPPORTS partial_update:
needs_schema_refresh = existing_rule.partial_update(new_rule_config)
existing_rule.update_configuration(new_rule_config)
IF NOT needs_schema_refresh:
RETURN // partial update sufficient, no metadata rebuild needed
// Full rebuild path
old_rules = remove_rules_by_config_class(rules, new_rule_config.class)
IF should_rebuild:
new_rule = build_rule(database_name, new_rule_config, database.resources)
rules.add(new_rule)
// Update metadata contexts atomically
new_configs = extract_configs(rules)
metadata_contexts.update(create_new_contexts(database_name, new_configs))
// Release resources held by replaced rules
FOR EACH old_rule IN old_rules:
IF old_rule IS AutoCloseable:
old_rule.close()
END PROCEDURE
The synchronization block ensures that concurrent configuration changes are serialized, preventing race conditions where two rule changes might partially overlap. The should_rebuild flag controls whether a new rule object is actually constructed -- this allows the drop path to remove a rule without building a replacement when the configuration becomes empty.
The partial update optimization is critical for production performance. In a system with thousands of sharding tables, rebuilding the entire sharding rule for a single table change would be prohibitively expensive. The PartialRuleUpdateSupported interface allows rules to apply surgical updates when possible, falling back to full rebuild only when necessary.