Principle:Apache Shardingsphere Cluster Repository Initialization

Knowledge Sources	Apache ShardingSphere ShardingSphere Docs
Domains	Cluster_Mode, Distributed_Coordination
Last Updated	2026-02-10 00:00 GMT

Overview

Initializing a distributed coordination repository establishes the persistent, highly available state store that underpins all cluster-mode operations in a distributed database system.

Description

Cluster Repository Initialization is the principle of connecting to and configuring a distributed coordination service (such as Apache ZooKeeper or etcd) as the foundational state management layer for cluster-mode operation. The repository provides:

• Persistent storage for metadata, rules, data source configurations, and schema information
• Ephemeral storage for online node registration and session-bound state
• Distributed locking for exclusive operations across compute nodes
• Watch/notification capabilities for reacting to configuration changes in real time

In Apache ShardingSphere, the ClusterPersistRepository interface defines the contract for all cluster repository operations. Two SPI implementations are provided:

• ZookeeperRepository (type: "ZooKeeper") -- uses Apache Curator as the ZooKeeper client
• EtcdRepository (type: "etcd") -- uses the jetcd client library

Both implementations share the same init() contract defined by the interface:

void init(ClusterPersistRepositoryConfiguration config, ComputeNodeInstanceContext computeNodeInstanceContext);

The initialization process is responsible for:

1. Parsing repository-specific properties (timeouts, retry policies, authentication)
2. Establishing the network connection to the coordination service cluster
3. Configuring the namespace (logical isolation within the coordination service)
4. Registering session lifecycle listeners for automatic reconnection
5. Blocking until the connection is confirmed or a timeout is reached

The repository instance, once initialized, is shared across the entire context manager and serves as the backbone for all persistence and coordination operations throughout the lifetime of the ShardingSphere instance.

Usage

Use this principle during the early phase of cluster-mode initialization, immediately after the compute node instance context is created. The repository must be fully connected before any metadata loading, node registration, or event listener setup can proceed. The repository type is determined by the type field in the ClusterPersistRepositoryConfiguration and loaded via SPI.

Theoretical Basis

The Cluster Repository Initialization principle addresses several distributed systems concerns:

1. Connection Establishment with Retry

Both ZooKeeper and etcd operate as remote services subject to network partitions and transient failures. The initialization must incorporate retry logic:

FUNCTION initRepository(config, instanceContext):
    props = parseProperties(config.getProps())
    client = buildClient(config.getServerLists(), config.getNamespace(), props)
    client.addConnectionListener(reconnectListener(instanceContext))
    client.start()

    maxWait = props.retryInterval * props.maxRetries
    IF NOT client.blockUntilConnected(maxWait):
        client.close()
        THROW OperationTimeoutException

2. Namespace Isolation

Each ShardingSphere cluster operates within a dedicated namespace in the coordination service. This prevents key collisions between different ShardingSphere deployments sharing the same ZooKeeper or etcd cluster:

// ZooKeeper: namespace is set as the Curator root path
builder.namespace(config.getNamespace())

// etcd: namespace is set as a key prefix
Client.builder().namespace(ByteSequence.from(config.getNamespace()))

3. Session Lifecycle Management

The repository registers a session connection listener that detects disconnections and triggers automatic re-registration of the compute node when the session is restored. This is critical for maintaining cluster membership through transient network failures.

4. Provider Abstraction via SPI

The choice of coordination backend is abstracted behind the ClusterPersistRepository interface. Application code interacts only with the interface, and the specific provider (ZooKeeper or etcd) is selected at runtime via SPI based on the configuration type string.

5. Authentication and Access Control

For production deployments, the repository initialization supports optional authentication. In ZooKeeper, this is implemented via digest-based ACL:

IF digest IS NOT EMPTY:
    builder.authorization("digest", digest.getBytes())
    builder.aclProvider(CREATOR_ALL_ACL)

Related Pages

Implemented By

• Implementation:Apache_Shardingsphere_ClusterPersistRepository_Init