Last updated October 11, 2024

Heroku Key-Value Store (KVS) is integrated directly into the Heroku CLI and offers several commands for managing a KVS instance.

redis:info

To see all KVS instances provisioned by your application and to identify the characteristics of each, use the heroku redis:info command.

$ heroku redis:info
=== maturing-deeply-2628 (REDIS_URL)
Plan:                   Premium 0
Status:                 Available
Created:                2024-09-23 21:40 UTC
Version:                7.2.4
Timeout:                60
Maxmemory:              volatile-lru
Maintenance window:     Mondays 22:30 to Tuesdays 02:30 UTC
Persistence:            AOF
Status:                 Available
Requires TLS:           Yes
Keyspace Notifications: Disabled
Plan Connection Limit:  10000

=== maturing-calmly-4191 (HEROKU_REDIS_AMBER_URL)
Plan:                   Premium 1
Status:                 Available
Created:                2024-09-30 21:40 UTC
Version:                7.2.4
Timeout:                0
Maxmemory:              noeviction
Maintenance window:     Mondays 22:30 to Tuesdays 02:30 UTC
Persistence:            AOF
Status:                 Available
Requires TLS:           Yes
Keyspace Notifications: Disabled
Plan Connection Limit:  10000

redis:cli

To establish a KVS CLI session with your remote KVS instance, use heroku redis:cli. If you don’t specify an instance, then the instance located at REDIS_URL is used by default.

$ heroku redis:cli -a myapp -c myapp
Connecting to maturing-deeply-2628 (REDIS_URL):
ec2-54-221-206-137.compute-1.amazonaws.com:6379> PING
PONG
ec2-54-221-206-137.compute-1.amazonaws.com:6379>

If there are multiple instances, specify the instance to connect to. As a shorthand, you can specify the HEROKU_REDIS_<color> config var name as the first argument to the command, or the resource name maturing-deeply-2628.

$ heroku redis:cli HEROKU_REDIS_AMBER
$ heroku redis:cli maturing-deeply-2628

redis:credentials

Heroku Key-Value Store provides convenient access to the credentials and location of your instance. This makes it easier to use a GUI to access your instance.

The instance name argument must be provided with the redis:credentials command. Use REDIS_URL for your primary data store.

$ heroku redis:credentials REDIS_URL
redis://h:pfl0cfuvr58fhsduesr9kau765k@ec2-54-221-206-137.compute-1.amazonaws.com:6379

It’s a good security practice to rotate the credentials for important services on a regular basis. On Heroku Key-Value Store, use heroku redis:credentials --reset to rotate credentials.

$ heroku redis:credentials HEROKU_REDIS_GRAY_URL --reset

When you issue this command, new credentials are created for your instance and the related config vars on your Heroku application are updated.

All of the open connections remain open until the currently running tasks complete. This is to make sure that any background jobs or other workers running on your production environment aren’t abruptly terminated, potentially leaving the system in an inconsistent state. Any new connections opened after the credentials rotation has been run but before dynos have restarted with the new value of the config var will fail.

redis:promote

In configurations where with multiple KVS instances provisioned, it’s often necessary to promote an instance to the primary role. You can promote an instance using the heroku redis:promote command.

$ heroku redis:promote shining-surely-6441 -a myapp
Promoting shining-surely-6441 to REDIS_URL on myapp

redis:promote works by setting the value of the REDIS_URL config var (which your application uses to connect) to the newly promoted instance’s URL and restarting your app. The old primary KVS instance location is still accessible via its HEROKU_REDIS_COLOR_URL setting.

redis:timeout

To change the number of seconds KVS waits before killing idle connections, use the redis:timeout command:

$ heroku redis:timeout maturing-deeply-2628 --seconds 60
Timeout for maturing-deeply-2628 (REDIS_URL) set to 60 seconds.
Connections to the redis instance will be stopped after idling for 60 seconds.

redis:maxmemory

To change the key eviction policy used when an instance reaches its storage limit, use the redis:maxmemory command:

$ heroku redis:maxmemory maturing-deeply-2628 --policy volatile-lru
Maxmemory policy for maturing-deeply-2628 (REDIS_URL) set to volatile-lru.
volatile-lru evicts keys trying to remove the less recently used keys first, but only those that have an expiry set.

redis:keyspace-notifications

Heroku Key-Value Store supports keyspace notifications. To configure this, use the redis:keyspace-notifications command:

$ heroku redis:keyspace-notifications maturing-deeply-2628 --config AKE
Keyspace notifications for maturing-deeply-2628 (REDIS_URL) set to 'AKE'.

A number of possible configurations are possible. Consult heroku help redis:keyspace-notifications for more.

redis:stats-reset

Resets the statistics on your Heroku Key-Value Store instance. This article outlines the statistics that are reset:

$ heroku redis:stats-reset maturing-deeply-2628
 ▸    WARNING: Irreversible action.
 ▸    All stats covered by RESETSTAT will be reset on maturing-deeply-2628.
 ▸    To proceed, type sushi or re-run this command with --confirm sushi

> sushi
Stats reset successful.