Heuristic:Apache Shardingsphere Version Cleanup After Switch
| Knowledge Sources | |
|---|---|
| Domains | Configuration_Management, Cluster_Coordination |
| Last Updated | 2026-02-10 02:00 GMT |
Overview
Aggressive old version cleanup strategy that deletes all previous configuration versions immediately after switching to a new active version.
Description
When ShardingSphere persists a new configuration version, it follows a three-step process: (1) write the new version content, (2) update the active version pointer, (3) delete all versions older than the new active version. This cleanup is aggressive — it happens synchronously as part of the version switch, not as a background task. A warning is logged if more than 2 versions are found, indicating a previous cleanup may have failed.
Usage
Apply this heuristic when:
- Debugging version issues: If the log shows "There are multiple versions of: {path}, please check the configuration", it means old versions were not cleaned up properly. This can happen if a node crashes between writing a new version and completing cleanup.
- Understanding storage growth: Under normal operation, each configuration path should have at most 1-2 versions. If more accumulate, something is wrong.
- Recovery: Manual cleanup may be needed in the cluster repository (ZooKeeper/etcd) if automated cleanup fails.
The Insight (Rule of Thumb)
- Action: After switching the active version, all older versions are deleted immediately. The initial version (version 0) is exempt from triggering cleanup.
- Value: Keeps registry storage minimal — only the current active version persists long-term.
- Trade-off: No rollback capability. Once a version is switched and old versions are deleted, reverting requires re-persisting the old configuration content. The aggressive cleanup prevents storage bloat in the cluster repository.
- Warning threshold: More than 2 versions triggers a log warning — this indicates potential cleanup failures.
Reasoning
The cluster repository (ZooKeeper or etcd) is not designed for large-scale version history storage. Each version is a separate node/key, and accumulated versions increase metadata size and watch overhead. Aggressive cleanup keeps the repository lean.
The guard `if (MetaDataVersion.INIT_VERSION != currentVersion)` prevents cleanup on the initial write — there are no old versions to delete when the first version is created.
The warning at the 2-version threshold is a diagnostic aid. During normal operation, the sequence is: write version N, switch active pointer to N, delete versions < N. If 3+ versions exist, it means a previous switch-and-cleanup did not complete fully.
Code evidence from `VersionPersistService.java:53-59`:
private void switchActiveVersion(final VersionNodePath versionNodePath,
final int currentVersion) {
repository.persist(versionNodePath.getActiveVersionPath(),
String.valueOf(currentVersion));
if (MetaDataVersion.INIT_VERSION != currentVersion) {
getVersions(versionNodePath.getVersionsPath()).stream()
.filter(version -> version < currentVersion)
.forEach(version -> repository.delete(
versionNodePath.getVersionPath(version)));
}
}
Warning for accumulated versions from `VersionPersistService.java:72-79`:
private List<Integer> getVersions(final String path) {
List<Integer> result = repository.getChildrenKeys(path).stream()
.map(Integer::parseInt).collect(Collectors.toList());
if (result.size() > 2) {
log.warn("There are multiple versions of: {}, please check the configuration.",
path);
result.sort(Collections.reverseOrder());
}
return result;
}