Implementation:Apache Shardingsphere VersionPersistService SwitchActiveVersion

Knowledge Sources	Apache ShardingSphere
Domains	Configuration_Management, Distributed_Systems
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for atomically switching the active configuration version pointer and triggering cluster-wide change propagation, provided by the ShardingSphere mode core module.

Description

The switchActiveVersion method on VersionPersistService is a private method that performs the atomic version pointer update within the versioned persistence workflow. It is called internally by the public persist method after the new version's content has been written to the repository. This is the linearization point that makes a configuration change visible to all cluster nodes.

The method performs three operations:

1. Active version pointer update: Writes the new version number (as a string) to the active_version path of the version node. This single write to the distributed registry is what triggers DataChangedEvent notifications to all watchers. The registry infrastructure (ZooKeeper, etcd) guarantees that this write is atomic and linearized.
2. Old version garbage collection: If the new version is not the initial version (version 0), the method retrieves all existing version numbers from the versions path and deletes any version entry whose number is less than the current version. This prevents unbounded growth of version history in the repository.
3. Guard for initial version: When the version is INIT_VERSION (0), garbage collection is skipped because there are no older versions to clean up.

The public persist method that calls switchActiveVersion follows this sequence:

1. Compute the next version number via getNextVersion, which lists existing version children and returns max + 1 (or INIT_VERSION if no versions exist).
2. Write the configuration content to the versioned path (e.g., /versions/3).
3. Call switchActiveVersion to update the pointer and clean up old versions.
4. Return the next version number to the caller.

The getVersions helper method includes a diagnostic warning: if more than 2 versions are found at any path, it logs a warning suggesting a configuration issue, since under normal operation only the current and at most one previous version should exist.

Usage

The switchActiveVersion method is called internally during every versioned persistence operation. It is not invoked directly by external code. The public entry point is the persist method, which is called by:

• DatabaseRulePersistService.persistTuples() when persisting database rule configurations.
• Any other service that uses VersionPersistService for versioned content storage.

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/version/VersionPersistService.java
• Lines: 46-51 (public persist method), 53-59 (private switchActiveVersion method)

Signature

// Public entry point that calls switchActiveVersion internally
public int persist(final VersionNodePath versionNodePath, final String content)

// Private method that performs the atomic version switch
private void switchActiveVersion(final VersionNodePath versionNodePath, final int currentVersion)

Import

import org.apache.shardingsphere.mode.metadata.persist.version.VersionPersistService;

I/O Contract

Inputs

For the public persist method:

Name	Type	Required	Description
versionNodePath	VersionNodePath	Yes	The version node path object that provides the base path, versions directory path, active version path, and versioned content paths.
content	String	Yes	The serialized configuration content to persist at the new version.

For the private switchActiveVersion method:

Name	Type	Required	Description
versionNodePath	VersionNodePath	Yes	The version node path object used to compute the active version path and version entry paths.
currentVersion	int	Yes	The version number that should become the new active version. All versions less than this value will be garbage collected.

Outputs

For the public persist method:

Name	Type	Description
return	int	The version number assigned to the newly persisted content. This is the value that was written to the active_version pointer.

For the private switchActiveVersion method:

Name	Type	Description
return	void	No return value. The method completes when the active version pointer has been updated and old versions have been garbage collected.

Usage Examples

// The public persist method is the external entry point:
VersionPersistService versionPersistService = new VersionPersistService(repository);
VersionNodePath versionNodePath = new VersionNodePath(databaseRuleNodePath);

// Persist new content and get the assigned version number
int newVersion = versionPersistService.persist(versionNodePath, yamlContent);

// Internally, persist() does:
//   1. int nextVersion = getNextVersion(versionNodePath.getVersionsPath());
//   2. repository.persist(versionNodePath.getVersionPath(nextVersion), content);
//   3. switchActiveVersion(versionNodePath, nextVersion);
//      -> repository.persist(versionNodePath.getActiveVersionPath(), String.valueOf(nextVersion));
//      -> delete old versions where version < nextVersion
//   4. return nextVersion;

// Reading the currently active content uses the active version pointer:
String activeContent = versionPersistService.loadContent(versionNodePath);
// Internally: reads active_version, then reads /versions/{activeVersion}

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Active_Version_Switching

Uses Heuristic

• Heuristic:Apache_Shardingsphere_Version_Cleanup_After_Switch