Principle:Apache Shardingsphere Configuration Change Initiation
| Knowledge Sources | |
|---|---|
| Domains | Configuration_Management, Distributed_Systems |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Configuration change initiation is the entry point for modifying distributed database rule configurations, triggering a propagation pipeline that ensures all cluster nodes converge on the updated state.
Description
In a distributed database system, configuration changes such as altering sharding rules, encryption policies, or read-write splitting strategies must be propagated reliably across all participating nodes. Configuration change initiation is the first stage of this pipeline: an administrative action (typically a DistSQL statement or management API call) is translated into a persistence operation that writes the new configuration to a shared registry.
The initiating node is responsible for:
- Validating the new configuration is non-null and well-formed before proceeding.
- Snapshotting the current MetaDataContexts to enable later comparison for reload detection.
- Persisting the rule configuration to the distributed repository via the database rule persist service, which assigns version numbers and triggers downstream change events.
- Waiting for reload of the MetaDataContexts by comparing the current context against the snapshot, employing a retry mechanism with configurable timeout to handle propagation delay.
- Persisting schema metadata changes that result from the configuration alteration, ensuring the database-level metadata remains consistent with the new rules.
This principle ensures that configuration changes are durable before any in-memory state is updated, providing crash-recovery guarantees even if the initiating node fails mid-operation.
Usage
Apply this principle whenever a user or automation system needs to modify rule configurations in a ShardingSphere cluster. Common scenarios include:
- Executing DistSQL ALTER statements through the ShardingSphere-Proxy.
- Programmatically changing sharding, encryption, or read-write splitting rules via the management API.
- Removing or adding data sources that require rule reconfiguration.
Theoretical Basis
The configuration change initiation follows a write-then-wait pattern common in distributed consensus systems:
PROCEDURE initiate_configuration_change(database, new_rule_config):
IF new_rule_config IS NULL:
RETURN // guard clause
// 1. Snapshot current state for comparison
original_context = snapshot(current_metadata_contexts)
// 2. Persist to distributed registry (triggers version increment + events)
persist_service.persist(database.name, {new_rule_config})
// 3. Wait for cluster propagation to reload metadata
reloaded_context = wait_for_reload(original_context, timeout=30s, interval=1s)
// 4. Persist resulting metadata changes (schema/table alterations)
persist_reloaded_database_metadata(database.name, reloaded_context, original_context)
END PROCEDURE
The key insight is that the initiating node does not directly update its own in-memory state. Instead, it persists the change to the shared repository and then waits for the event-driven pipeline (version switching, event emission, listener filtering, handler dispatch, and rule rebuild) to propagate the change back to all nodes, including itself. This ensures that every node follows the same code path for applying configuration changes, preventing divergence between the initiator and other cluster members.
The retry mechanism with exponential backoff (initial 3-second sleep followed by polling at 1-second intervals for up to 30 seconds) handles the inherent latency of distributed event propagation while providing a bounded wait time to avoid indefinite blocking.