Skip to main content

Client API

The Client class connects to a dqlite cluster.

Client​

Client for connecting to and managing a dqlite cluster.

The client connects to a cluster of dqlite nodes and provides methods for cluster management (adding/removing nodes) and querying the cluster state.

Example:

>>> from dqlitepy import Client
>>> client = Client(["127.0.0.1:9001", "127.0.0.1:9002"])
>>> leader = client.leader()
>>> print(f"Current leader: {leader}")
>>> client.add(3, "127.0.0.1:9003")
>>> nodes = client.cluster()
>>> for node in nodes:
...     print(f"Node {node.id}: {node.address} ({node.role_name})")

Properties​

cluster_addresses​

Get the list of cluster addresses this client knows about.

Methods​

__enter__(self) -> "'Client'"​

Context manager entry.

__exit__(self, exc_type: 'Optional[Type[BaseException]]', exc_val: 'Optional[BaseException]', exc_tb: 'Optional[TracebackType]') -> 'None'​

Context manager exit with safe cleanup.

add(self, node_id: 'int', address: 'str') -> 'None'​

Add a node to the cluster.

The node must already be running (via Node class) before adding it to the cluster.

Args: node_id: Unique identifier for the node address: Network address of the node (e.g., "127.0.0.1:9002")

Raises: ClientClosedError: If client is closed ClientError: If unable to add the node.

Example:

>>> from dqlitepy import Node, Client
>>> node2 = Node("127.0.0.1:9002", "/data/node2", node_id=2)
>>> node2.start()
>>> client = Client(["127.0.0.1:9001"])
>>> client.add(2, "127.0.0.1:9002")

close(self) -> 'None'​

Close the client connection with safe cleanup.

After calling this method, the client cannot be used anymore. This is called automatically when the client is garbage collected.

cluster(self) -> 'List[NodeInfo]'​

Get information about all nodes in the cluster.

Returns: List of NodeInfo objects describing each node in the cluster.

Raises: ClientClosedError: If client is closed ClientError: If unable to query cluster information.

Example:

>>> client = Client(["127.0.0.1:9001"])
>>> nodes = client.cluster()
>>> for node in nodes:
...     print(f"Node {node.id}: {node.address} - {node.role_name}")
Node 1: 127.0.0.1:9001 - Voter
Node 2: 127.0.0.1:9002 - Voter

leader(self) -> 'str'​

Get the address of the current cluster leader.

Returns: The address of the leader node (e.g., "127.0.0.1:9001")

Raises: ClientClosedError: If client is closed ClientError: If unable to determine the leader.

remove(self, node_id: 'int') -> 'None'​

Remove a node from the cluster.

Args: node_id: Unique identifier of the node to remove

Raises: ClientClosedError: If client is closed ClientError: If unable to remove the node.

Note: You cannot remove the leader node. Transfer leadership first or let the cluster elect a new leader.