KalamDB Cluster Operations

Use the CLI to inspect nodes and replication groups, then perform one maintenance action at a time. Connect with a DBA or system account to an existing cluster; the commands below do not provision hosts or configure networking.

Inspect a KalamDB cluster

BASH

1kalam --url http://127.0.0.1:2900 -c '\cluster list'2kalam --url http://127.0.0.1:2900 -c '\cluster list groups'

For machine-readable output, query the views:

BASH

1kalam --url http://127.0.0.1:2900 --json \2  -c 'SELECT * FROM system.cluster ORDER BY node_id;'

SQL

1SELECT * FROM system.cluster ORDER BY is_leader DESC, node_id;2SELECT * FROM system.cluster_groups ORDER BY group_id;

Check reachable nodes and the leader for each group. Multi-Raft groups can have different leaders. Maintain quorum during maintenance; restarting a majority of voting members together can stop progress.

Command reference

These are CLI meta-commands, entered inside kalam or passed to kalam -c:

Command	Purpose	Before running
`\cluster list`	Show nodes	Check node reachability
`\cluster list groups`	Show group leadership and replication state	Identify the affected group
`\cluster snapshot`	Request snapshots	Inspect success for every returned group
`\cluster join <id> <rpc> <api>`	Add a configured node	Use a unique node ID and reachable RPC/API addresses
`\cluster rebalance`	Request leader redistribution	Check cluster health and allow work to settle
`\cluster trigger-election`	Request elections	Expect leader changes and possible brief interruption
`\cluster transfer-leader <node_id>`	Request transfer to a node	Check target membership; runtime support depends on the Raft implementation
`\cluster stepdown`	Ask local leaders to step down	Use during controlled maintenance
`\cluster purge --upto <index>`	Request log purge through an index	Confirm the snapshot and recovery implications; do not guess an index
`\cluster clear`	Clean snapshot files	Inspect what will be removed; do not treat this as routine health repair

Commands that touch several groups return per-group results. A successful HTTP response is not enough: inspect the success and error fields for every group.

Snapshot and inspect

BASH

1kalam -c '\cluster snapshot'2kalam -c '\cluster list groups'

Record the snapshot indices and failed groups, if any. A Raft snapshot is not a substitute for a complete backup and restore procedure.

Join a configured node

After configuring and starting the new node according to Clustering & High Availability, substitute its actual addresses:

BASH

1kalam -c '\cluster join 4 10.0.0.4:2910 http://10.0.0.4:2900'2kalam -c '\cluster list'3kalam -c '\cluster list groups'

The first address is the inter-node RPC listener; the second is the HTTP API. A successful join request is not evidence that every group is caught up. Inspect membership, replication, and errors before moving traffic or stopping another node.

If redistribution is needed after the cluster is healthy:

BASH

1kalam -c '\cluster rebalance'2kalam -c '\cluster list groups'

Maintenance and limitations

Keep the original deployment configuration, backups, and node identities available. For a single-node deployment, cluster inspection may show standalone behavior and cluster-only operations may be unavailable.

CLUSTER LEAVE is unsupported. Use CLI list commands or system views instead of old CLUSTER LIST, STATUS, or LS SQL forms. Leader-transfer requests can return an unsupported result in some builds; inspect the response instead of assuming leadership moved.

Next step

Monitor cluster health and diagnose failures →

Reference: Multi-Raft architecture and configuration.