Principle:Apache Shardingsphere Active Version Switching
| Knowledge Sources | |
|---|---|
| Domains | Configuration_Management, Distributed_Systems |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Active version switching is the atomic operation of updating a version pointer in the distributed registry so that all cluster nodes can discover and converge on the latest configuration.
Description
In a versioned configuration system, the active version is a lightweight pointer (a single integer value stored at a well-known path) that indicates which version of a configuration item is currently in effect. Active version switching is the critical step that makes a newly persisted configuration version visible to the rest of the cluster.
The process involves three coordinated steps:
- Write the new version content: The configuration data is first written to a versioned path (e.g., /versions/3) without affecting the current active version. At this point, no other node sees the change.
- Update the active version pointer: The active_version node is overwritten with the new version number. This single write is the linearization point that makes the new configuration atomically visible to all watchers.
- Garbage collect old versions: All version entries with a version number less than the new active version are deleted from the repository. This prevents unbounded storage growth while keeping the system responsive.
The active version pointer serves as the trigger for the downstream event-driven pipeline. When a distributed registry (such as ZooKeeper or etcd) detects that the active_version node has been modified, it emits a DataChangedEvent to all subscribed listeners. This event is what drives the remaining stages of the dynamic rule configuration change workflow: event filtering, handler dispatch, and in-memory rule rebuild.
The design deliberately separates writing content from activating content. This two-phase approach means that if the process crashes after writing the version content but before switching the active pointer, no node will ever see the incomplete change. Only after the active version pointer is successfully updated does the change become part of the system's visible state.
Usage
Active version switching occurs internally as part of every configuration persistence operation. It is not called directly by application code but is triggered whenever:
- A database rule configuration is persisted or deleted.
- A global rule configuration is altered.
- Data source properties are registered, altered, or unregistered.
- Any metadata node that uses versioned storage is modified.
Theoretical Basis
The active version switching pattern implements a form of single-writer atomic pointer update:
PROCEDURE switch_active_version(version_node_path, new_content):
versions_path = version_node_path / "versions"
active_version_path = version_node_path / "active_version"
// Step 1: Determine next version
existing_versions = list_children(versions_path)
next_version = IF empty(existing_versions) THEN 0 ELSE max(existing_versions) + 1
// Step 2: Write content at versioned path (invisible to consumers)
repository.write(versions_path / next_version, new_content)
// Step 3: Atomically switch the active version pointer
// This write triggers DataChangedEvent to all watchers
repository.write(active_version_path, next_version)
// Step 4: Garbage collect old versions
IF next_version > 0:
FOR EACH v IN existing_versions WHERE v < next_version:
repository.delete(versions_path / v)
RETURN next_version
END PROCEDURE
The invariant maintained by this procedure is: at any point in time, the active_version pointer references a valid, fully-written version entry. Readers that query active_version and then read the corresponding version path are guaranteed to see a complete, consistent configuration snapshot.
The garbage collection of old versions after the switch is a best-effort optimization. If it fails (e.g., due to a network partition), the system remains correct -- it simply retains extra version entries that will be cleaned up on the next successful write.