Command: TTL
Overview
The TTL
command checks the remaining time-to-live (in seconds) for a specific key in the database. It’s useful for understanding when a key is going to expire or confirming whether it has an expiration at all.
Command Name
TTL
Description
The TTL
command returns the time remaining before a key expires:
-
Returns
-2
if the key does not exist. -
Returns
-1
if the key exists but does not have an expiry set. -
Returns a positive integer (in seconds) indicating how much time is left before expiration.
Use Cases
-
Check how much longer a session or cache key is valid.
-
Debug TTL-related logic in applications (e.g., auto-expiring keys).
-
Verify if a key has expired or not.
-
Check the difference between keys with and without expirations.
Syntax
TTL <key>
<key>
: The name of the key you want to check for time-to-live.
Permissions
-
Requires read access to the key.
-
No special write permissions are required.
Examples
Check TTL on a valid key with expiration:
localhost:9219> TTL.EXPIRE mykey 120
OK 1
localhost:9219> TTL mykey
Ok 85
Explanation:
-
TTL.EXPIRE mykey 120
sets a TTL of 120 seconds. -
TTL mykey
returns the remaining TTL (e.g., 85 seconds).
Check TTL on a nonexistent key:
localhost:9219> TTL nonexistent
Ok -2
Explanation:
-
The key
"nonexistent"
does not exist in the store. -
TTL returns
-2
.
Check TTL on a key without expiration:
localhost:9219> TTL keExists
Ok -1
Explanation:
-
The key
"keExists"
exists but has no expiration set. -
TTL returns
-1
.
Behavior on Error
Error Condition | Error Message |
---|---|
Key is not provided | InvalidArgsError: Key must be provided |
Notes
-
TTL values are rounded to seconds.
-
This command does not reset or affect the TTL of the key—it is read-only.
-
A TTL of
0
is not valid output; if seen, verify underlying storage behavior.