TTL(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 TTL — the "how long do you have, bestie" command 💖

okay so this is the TTL page from the valkey command manual (that's the 3valkey section, iykyk) and honestly? it's a short one, but it's so useful. let's get into it 🦋

✨ NAME ✨

ttl — Returns the expiration time in seconds of a key.

like. literally just "how many seconds does this key have left to live." that's the whole gig. 👑

🌸 SYNOPSIS 🌸

TTL key

one arg, no drama. key is your key. periodt.

💅 DESCRIPTION 💅

okay so TTL gives you back the remaining time to live of a key that has a timeout. it's giving introspection, and that's iconic — it means a Valkey client can just vibe check how many seconds a given key is still gonna be part of the dataset before it ✨evaporates✨.

now, the error-ish replies. bestie, these are important, don't skip:

  • The command returns -2 if the key does not exist. 💀 (it's just not there, sorry)
  • The command returns -1 if the key exists but has no associated expire. (she's here and she's staying forever, no cap)

also!! go look at the valkey-pttl(7) PTTL command — it's the same info but with milliseconds resolution, for when you need to be extra precise. obsessed with the precision tbh.

🎀 REPLY 🎀

you get one of the following, and they're all valkey-protocol(7) Integer replies:

🔥 COMPLEXITY 🔥

O(1)

constant time, baby. she's fast. no scrolling through the whole keyspace, she just knows. 💨

🌈 ACL CATEGORIES 🌈

@fast @keyspace @read

⭐ HISTORY ⭐

the glow-up timeline:

  • Available since: 1.0.0 🎂
  • Changed in 2.8.0: Added the -2 reply. (before that, no -2. the more you know 💫)

🫶 EXAMPLES 🫶

watch her work:

127.0.0.1:6379> SET mykey "Hello"
OK
127.0.0.1:6379> EXPIRE mykey 10
(integer) 1
127.0.0.1:6379> TTL mykey
(integer) 10

set it, gave it 10 seconds, asked how long it had left, got 10 back. ate. 💖

👑 SEE ALSO 👑

go be nosy, here's the whole squad:

copy(3valkey), del(3valkey), dump(3valkey), exists(3valkey), expire(3valkey), expireat(3valkey), expiretime(3valkey), keys(3valkey), migrate(3valkey), move(3valkey), object(3valkey), object-encoding(3valkey), object-freq(3valkey), object-help(3valkey), object-idletime(3valkey), object-refcount(3valkey), persist(3valkey), pexpire(3valkey), pexpireat(3valkey), pexpiretime(3valkey), pttl(3valkey), randomkey(3valkey), rename(3valkey), renamenx(3valkey), restore(3valkey), scan(3valkey), sort(3valkey), sort_ro(3valkey), touch(3valkey), type(3valkey), unlink(3valkey), wait(3valkey), waitaof(3valkey)

k that's the whole page!! remember: -1 means "no expiration, she's immortal", -2 means "girl, that key does not exist". don't mix them up or it's over for you 🧚

and that's a wrap on TTL(3valkey), from the 9.0.0 valkey command manual, dated 2025-10-21. ty for reading, mwah 💜

📦 where this page comes from