role.3valkey - Man Page
Returns the replication role.
Synopsis
ROLE
Description
Provide information on the role of a Valkey instance in the context of replication, by returning if the instance is currently a master, slave, or sentinel. The command also returns additional information about the state of the replication (if the role is master or slave) or the list of monitored master names (if the role is sentinel).
Output format
The command returns an array of elements. The first element is the role of the instance, as one of the following three strings:
- “master”
- “slave”
- “sentinel”
The additional elements of the array depends on the role.
Master output
An example of output when ROLE is called in a master instance:
1) "master"
2) (integer) 3129659
3) 1) 1) "127.0.0.1"
2) "9001"
3) "3129242"
2) 1) "127.0.0.1"
2) "9002"
3) "3129543"The master output is composed of the following parts:
- The string
master. - The current master replication offset, which is an offset that masters and replicas share to understand, in partial resynchronizations, the part of the replication stream the replicas needs to fetch to continue.
- An array composed of three elements array representing the connected replicas. Every sub-array contains the replica IP, port, and the last acknowledged replication offset.
Output of the command on replicas
An example of output when ROLE is called in a replica instance:
1) "slave" 2) "127.0.0.1" 3) (integer) 9000 4) "connected" 5) (integer) 3167038
The replica output is composed of the following parts:
- The string
slave, because of Redis OSS compatibility (see note at the end of this page). - The IP of the master.
- The port number of the master.
- The state of the replication from the point of view of the master, that can be
connect(the instance needs to connect to its master),connecting(the master-replica connection is in progress),sync(the master and replica are trying to perform the synchronization),connected(the replica is online). - The amount of data received from the replica so far in terms of master replication offset.
Sentinel output
An example of Sentinel output:
1) "sentinel" 2) 1) "resque-master" 2) "html-fragments-master" 3) "stats-master" 4) "metadata-master"
The sentinel output is composed of the following parts:
- The string
sentinel. - An array of master names monitored by this Sentinel instance.
Reply
valkey-protocol(7) Array reply: where the first element is one of master, slave, or sentinel, and the additional elements are role-specific as illustrated above.
Complexity
O(1)
Acl Categories
@admin @dangerous @fast
History
- Available since: 2.8.12
Examples
127.0.0.1:6379> ROLE 1) "master" 2) (integer) 0 3) (empty array)
A note about the word slave used in this man page: If not for Redis OSS compatibility, the Valkey project does not use the word slave. Unfortunately in this command the word slave is part of the protocol, so we’ll be able to remove such occurrences only when this API will be naturally deprecated.
See Also
acl(3valkey), acl-cat(3valkey), acl-deluser(3valkey), acl-dryrun(3valkey), acl-genpass(3valkey), acl-getuser(3valkey), acl-help(3valkey), acl-list(3valkey), acl-load(3valkey), acl-log(3valkey), acl-save(3valkey), acl-setuser(3valkey), acl-users(3valkey), acl-whoami(3valkey), bgrewriteaof(3valkey), bgsave(3valkey), command(3valkey), command-count(3valkey), command-docs(3valkey), command-getkeys(3valkey), command-getkeysandflags(3valkey), command-help(3valkey), command-info(3valkey), command-list(3valkey), config(3valkey), config-get(3valkey), config-help(3valkey), config-resetstat(3valkey), config-rewrite(3valkey), config-set(3valkey), dbsize(3valkey), debug(3valkey), failover(3valkey), flushall(3valkey), flushdb(3valkey), info(3valkey), lastsave(3valkey), latency(3valkey), latency-doctor(3valkey), latency-graph(3valkey), latency-help(3valkey), latency-histogram(3valkey), latency-history(3valkey), latency-latest(3valkey), latency-reset(3valkey), lolwut(3valkey), memory(3valkey), memory-doctor(3valkey), memory-help(3valkey), memory-malloc-stats(3valkey), memory-purge(3valkey), memory-stats(3valkey), memory-usage(3valkey), module(3valkey), module-help(3valkey), module-list(3valkey), module-load(3valkey), module-loadex(3valkey), module-unload(3valkey), monitor(3valkey), psync(3valkey), replconf(3valkey), replicaof(3valkey), restore-asking(3valkey), save(3valkey), shutdown(3valkey), slowlog(3valkey), slowlog-get(3valkey), slowlog-help(3valkey), slowlog-len(3valkey), slowlog-reset(3valkey), swapdb(3valkey), sync(3valkey), time(3valkey)