ROLE(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💫 ROLE 💫

okay bestie, welcome to ROLE(3valkey) — the Valkey command manual page that's about to tell you exactly who's who in your replication setup. no cap. 💅

✨ NAME ✨

role — tells you what the replication role is. that's it. that's the whole vibe check. 🎀

🌸 SYNOPSIS 🌸

ROLE

no arguments, no options, no drama. just ROLE. iconic behavior honestly. 🦋

💖 DESCRIPTION 💖

so like, this command gives you the tea on what role a Valkey instance is playing in the whole replication situation. it tells you if the instance is currently a master, a slave, or a sentinel.

and that's not even all of it — it ALSO hands over extra deets about the state of the replication (if the role is a primary or a replica), or the list of monitored primary names (if the role is a sentinel). obsessed. 😭

📋 Output format 📋

the command returns an array of elements. the very first element is the role of the instance, and it's one of these three strings, periodt:

  • "master"
  • "slave"
  • "sentinel"

the rest of the elements in that array? depends entirely on which role you got. it's giving ✨mystery✨.

👑 Primary output 👑

here's what it looks like when you call ROLE on a primary 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 primary output is made up of these parts, bestie:

  1. the string master.
  2. the current primary replication offset — this is an offset that primaries and replicas share so they can understand, during partial resynchronizations, which part of the replication stream the replicas need to fetch to keep going. lowkey important.
  3. 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 🧚

and here's what you get when ROLE is called on a replica instance:

1) "slave"
2) "127.0.0.1"
3) (integer) 9000
4) "connected"
5) (integer) 3167038

the replica output is composed of these parts:

  1. the string slave, because of Redis OSS compatibility (peep the note at the end of this page 👀).
  2. the IP of the primary.
  3. the port number of the primary.
  4. the state of the replication from the point of view of the primary. this one can be connect (the instance needs to connect to its primary), connecting (the primary-replica connection is in progress), sync (the primary and replica are trying to perform the synchronization), or connected (the replica is online).
  5. the amount of data received from the replica so far, in terms of primary replication offset.

🛰️ Sentinel output 🛰️

an example of Sentinel output, for the sentinel girlies:

1) "sentinel"
2) 1) "resque-master"
   2) "html-fragments-master"
   3) "stats-master"
   4) "metadata-master"

the sentinel output is composed of these parts:

  1. the string sentinel.
  2. an array of primary 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. slay. 💅

⚡ COMPLEXITY ⚡

O(1) — constant time, no notes, fastest girl in the room. 🔥

🔐 ACL CATEGORIES 🔐

@admin @dangerous @fast

yes bestie, it's @dangerous. it's also @admin. it's also @fast. the trifecta. handle with care but like, quickly. 💀

📜 HISTORY 📜

  • Available since: 2.8.12

an elder. a legend. been here since 2.8.12 and still thriving. 👑

🌈 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 backward compatibility, the Valkey project no longer uses the words "master" and "slave". unfortunately in the given commands these words are part of the protocol, so we'll be able to remove such occurrences only when this API will be naturally deprecated. so like. yeah. we know. it's a whole thing. 🙈

🫶 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), commandlog(3valkey), commandlog-get(3valkey), commandlog-help(3valkey), commandlog-len(3valkey), commandlog-reset(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)

and that's the whole page bestie!! this was Valkey 9.0.0, dated 2025-10-21, and it's giving ROLE(3valkey) main character energy. go forth and check your roles, you got this. 💖✨🎀

📦 where this page comes from