KR.ADMIN ROUTE

Manages shard-to-member routing for primary and standby assignments.

Syntax

KR.ADMIN ROUTE <operation-kind> <route-kind> <shard-kind> <shard-id> <member-id>

Parameters

Parameter	Type	Description
`operation-kind`	string	`SET` or `UNSET`. Case-insensitive.
`route-kind`	string	`PRIMARY` or `STANDBY`. Case-insensitive.
`shard-kind`	string	`STASH` or `BUCKET`. Case-insensitive.
`shard-id`	integer or `*`	Zero-based shard index, or `*` to target all shards atomically.
`member-id`	string	Full 40-character hex member ID or a 4-character prefix. A prefix is resolved against currently registered members.

Note: STASH is an experimental shard kind, disabled by default. See Stash in the configuration reference.

Return Value

Simple string. Returns OK on success.

Behavior

Requires cluster initialization.

SET PRIMARY

Assigns a member as the primary owner of a shard.

When no primary is assigned yet, the member is written directly as the primary.

Reassignment, when a primary already exists, enforces strict pre-conditions:

The shard status must not be READWRITE.
The new primary must currently be a standby on that shard.
The volume status must be READONLY.
The standby must be fully caught up with the primary’s replication state.

On successful promotion the member is removed from the standby set.

SET STANDBY

Adds a member to the shard’s standby set. A primary must already be assigned. The member must not be the current primary and must not already be a standby.

UNSET STANDBY

Removes a member from the standby set. A primary must be assigned and the member must be in the standby set.

UNSET PRIMARY

Not supported. Always returns an error.

Wildcard shard-id

When shard-id is *, the operation applies to every shard of the specified kind within a single FoundationDB transaction. If any shard fails a pre-condition, the entire transaction is rolled back.

Topology notification

Every successful mutation triggers the cluster topology watcher, causing other members to refresh their routing tables.

Errors

Argument errors:

Error Code	Error message	Cause
`ERR`	`invalid number of parameters`	-
`ERR`	`Unknown operation kind: '<value>'`	The operation kind must be `SET` or `UNSET`.
`ERR`	`Unknown route kind: '<value>'`	The route kind must be `PRIMARY` or `STANDBY`.
`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: <value>`	The value is neither a 40-character member ID nor a 4-character prefix.

Cluster errors:

Error Code	Error message	Cause
`ERR`	`cluster has not been initialized yet`	-
`ERR`	`no member found with prefix: <prefix>`	-
`ERR`	`more than one member found with prefix: <prefix>`	-
`ERR`	`member not found`	-
`ERR`	`no primary member assigned yet`	SET or UNSET STANDBY requires an existing primary.
`ERR`	`primary cannot be assigned as a standby`	-
`ERR`	`already assigned as a standby`	-
`ERR`	`member is not a standby`	-
`ERR`	`UNSET PRIMARY is not supported`	-
`ERR`	`Shard status must not be READWRITE`	Reassigning a primary requires the shard to be non-READWRITE first.
`ERR`	`Member could not be found: <id>`	The target member could not be resolved during reassignment.
`ERR`	`Primary shard owner could not be found: <id>`	The current primary could not be resolved during reassignment.
`ERR`	`Member id: <id> is not a standby`	The new primary must be a current standby during reassignment.
`ERR`	`Volume status must be READONLY`	The volume must be READONLY before primary reassignment.
`ERR`	`Standby is not caught up: <details>`	The standby has not finished replicating from the primary. The detail indicates whether the lag is in the replication stage, segment position, or sequence number.

Examples

Assign a primary to a shard:

127.0.0.1:3320> KR.ADMIN ROUTE SET PRIMARY BUCKET 0 006cdc459c59e600c76494e8388857fc3cba2fa8
OK

Add a standby to a shard:

127.0.0.1:3320> KR.ADMIN ROUTE SET STANDBY BUCKET 0 a3f18b2e74d9c5601f82e4a7b390d612c8f7e149
OK

Assign a standby to all bucket shards:

127.0.0.1:3320> KR.ADMIN ROUTE SET STANDBY BUCKET * a3f18b2e74d9c5601f82e4a7b390d612c8f7e149
OK

Remove a standby from a shard:

127.0.0.1:3320> KR.ADMIN ROUTE UNSET STANDBY BUCKET 0 a3f18b2e74d9c5601f82e4a7b390d612c8f7e149
OK

Error: assigning standby without a primary

127.0.0.1:3320> KR.ADMIN ROUTE SET STANDBY BUCKET 0 a3f18b2e74d9c5601f82e4a7b390d612c8f7e149
(error) ERR no primary member assigned yet

Error: unsetting primary

127.0.0.1:3320> KR.ADMIN ROUTE UNSET PRIMARY BUCKET 0 006cdc459c59e600c76494e8388857fc3cba2fa8
(error) ERR UNSET PRIMARY is not supported