VOLUME.STATS REPLICATION

Returns replication state for a specific standby member on a named volume.

Syntax

VOLUME.STATS <volume-name> REPLICATION <shard-kind> <shard-id> <standby-id>

Parameters

Parameter	Type	Description
volume-name	string	Name of the volume, in <kind>-shard-<id> format (e.g. bucket-shard-0)
shard-kind	string	Shard kind (e.g. BUCKET, STASH)
shard-id	integer	Numeric shard identifier
standby-id	string	Member ID of the standby to inspect

Return Value

RESP3 map with the following fields:

Field	Type	Description
stage	string	Current replication stage (e.g. SEGMENT_REPLICATION, CHANGE_DATA_CAPTURE), or empty string if not started
status	string	Replication status (e.g. WAITING, RUNNING, FAILED), or empty string if unknown
error_message	string	Error description if replication has failed, or empty string
cursor_segment_id	integer	Segment ID the replication cursor is currently on (0 if not started)
cursor_position	integer	Byte position within the cursor segment (0 if not started)
cdc_sequence_number	integer	Change data capture sequence number (0 if not in CDC stage)
cdc_position	integer	Position within the current CDC sequence (0 if not in CDC stage)

Behavior

Reads the standby’s replication status from FoundationDB. The volume name is derived from shard-kind and shard-id using the standard naming convention.

Fields default to empty strings (for stage, status, error_message) or zero (for numeric fields) when replication has not started or the standby subspace has not been initialized.

This command requires exactly 5 parameters total (volume name, subcommand, shard kind, shard ID, standby ID).

This command is available on the management port (default 3320).

Errors

Argument errors:

Error Code	Error message	Cause
ERR	invalid number of parameters	-
ERR	Unknown shard kind: '<value>'	The shard kind must be STASH or BUCKET.
ERR	invalid shard id	The shard ID is not a valid integer, or is out of the configured range.
ERR	Invalid memberId: <id>	The value is neither a 40-character member ID nor a 4-character prefix.

Examples

Replication in segment replication stage:

127.0.0.1:3320> VOLUME.STATS bucket-shard-0 REPLICATION BUCKET 0 standby-member-1
1# "stage" => "SEGMENT_REPLICATION"
2# "status" => "RUNNING"
3# "error_message" => ""
4# "cursor_segment_id" => (integer) 2
5# "cursor_position" => (integer) 51200
6# "cdc_sequence_number" => (integer) 0
7# "cdc_position" => (integer) 0

Replication in change data capture stage:

127.0.0.1:3320> VOLUME.STATS bucket-shard-0 REPLICATION BUCKET 0 standby-member-1
1# "stage" => "CHANGE_DATA_CAPTURE"
2# "status" => "RUNNING"
3# "error_message" => ""
4# "cursor_segment_id" => (integer) 3
5# "cursor_position" => (integer) 0
6# "cdc_sequence_number" => (integer) 42
7# "cdc_position" => (integer) 1024

Replication not yet started:

127.0.0.1:3320> VOLUME.STATS bucket-shard-0 REPLICATION BUCKET 0 standby-member-1
1# "stage" => ""
2# "status" => "WAITING"
3# "error_message" => ""
4# "cursor_segment_id" => (integer) 0
5# "cursor_position" => (integer) 0
6# "cdc_sequence_number" => (integer) 0
7# "cdc_position" => (integer) 0

Failed replication:

127.0.0.1:3320> VOLUME.STATS bucket-shard-0 REPLICATION BUCKET 0 standby-member-1
1# "stage" => "SEGMENT_REPLICATION"
2# "status" => "FAILED"
3# "error_message" => "Connection refused"
4# "cursor_segment_id" => (integer) 1
5# "cursor_position" => (integer) 4096
6# "cdc_sequence_number" => (integer) 0
7# "cdc_position" => (integer) 0