Last updated December 04, 2024

Heroku Key-Value Store (KVS) is an in-memory key-value data store, run by Heroku, that is provisioned and managed as an add-on. Heroku Key-Value Store is accessible from any language with a Redis driver, including all languages and frameworks supported by Heroku. KVS is compatible with both Redis and Valkey configurations.

Provisioning the Add-on

Check If a KVS Instance is Already Provisioned

Use the heroku addons command to see if your application already has a KVS instance provisioned:

$ heroku addons | grep heroku-redis
heroku-redis (cooking-peacefully-8526)                mini    $3/month

Create an Instance

You can attach Heroku Key-Value Store to an application via the CLI. This command and other examples use the Mini plan.:

$ heroku addons:create heroku-redis:mini -a your-app-name

To learn more about Heroku Key-Value Store plans, see Heroku Key-Value Store Plans and Pricing.

heroku addons:info command displays creation progress. State “creating” means that it’s still provisioning and not yet ready.

$ heroku addons:info soaring-duly-3158
=== soaring-duly-3158
Attachments:  example-app::HEROKU_REDIS
Installed at: Tue Nov 29 2016 10:12:34 GMT-0800 (PST)
Owning app:   example-app
Plan:         heroku-redis:mini
Price:        $3/month
State:        creating

After provisioning Heroku Key-Value Store, the new release is created and the application restarts. A REDIS_URL config var is available in the app configuration. It contains the URL you can use to access the newly provisioned Heroku Key-Value Store instance. You can confirm the URL with the heroku config command:

$ heroku config | grep REDIS
REDIS_URL: redis://h:asdfqwer1234asdf@ec2-111-1-1-1.compute-1.amazonaws.com:111

Establish the Primary Instance

Heroku creates the REDIS_URL config var to store the location of the primary instance. In single-instance setups, your new instance is assigned a REDIS_URL. In cases where REDIS_URL exists, your instance is assigned a HEROKU_REDIS_<color> URL instead.

Promoting an Instance

For apps that have multiple KVS instances, you can set the primary instance using the promote command:

$ heroku redis:promote HEROKU_REDIS_JADE
Promoting maturing-deeply-2628 to REDIS_URL on example-app

Sharing Heroku Key-Value Store between Applications

You can share one Heroku Key-Value Store between multiple applications.

$ heroku addons:attach my-originating-app::REDIS --app example-app
Attaching redis-addon-name to example-app... done
Setting HEROKU_REDIS_CYAN config vars and restarting example-app... done, v10

If you already have a KVS add-on provisioned, the database is attached with a color (in this example HEROKU_REDIS_CYAN but it changes each time). If you don’t have one, it’s attached as REDIS with the config var REDIS_URL.

The shared database isn’t necessarily the default database on any apps that it’s shared with. To promote the shared database to be the primary database, use the redis:promote command with the addon name on each of the apps where you want it to be the default database:

$ heroku redis:promote redis-addon-name --app example-app
Promoting redis-addon-name to REDIS_URL on example-app

Version Support and Legacy Infrastructure

Heroku offers Valkey 7.2 as the default version and continues to provide updates and support for Valkey 7.2 and Redis 7.0. Version 7.2 runs on Valkey infrastructure, which is fully compatible with existing KVS add-ons and implementations.

Heroku Key-Value Store defaults to the latest stable version of Valkey allowlisted for the platform. Heroku follows the release schedule of the Valkey project and the Redis project in that we support at least two releases on the platform. Currently supported versions include:

Deprecation and Migration of Deprecated Instances

Heroku also deprecates old versions of our infrastructure. This can happen if the operating system running beneath the database no longer receives security updates, if support for the operating system is no longer practical due to age (if necessary packages and patches are no longer available or difficult to support), or if the server instances are significantly different from our current infrastructure and are impractical to support.

When we release a new major version, we deprecate the second major version released before it. For example, Redis 7.0 deprecates when Valkey 7.4 releases.

• On the deprecation date, Heroku notifies customers via email about the deprecation process for their affected databases.
• Two months after the deprecation date, Heroku prevents provisioning new instances on the deprecated version.
• Three months after the deprecation date, Heroku schedules forced upgrades for instances that still run a deprecated version.

Heroku highly recommends that you perform the version upgrade before support ends so that you can test compatibility, plan for unforeseen issues, and migrate your database on your own schedule.

End-of-Life

The end-of-life date of each version occurs four months after its deprecation date. We start restricting access and deleting instances for non-compliance after this date.

Upgrading a Heroku Key-Value Store Plan

You can upgrade your Heroku Key-Value Store plan. To upgrade, first, find the resource name of the Heroku Key-Value Store instance that must be upgraded. The resource name is a globally unique name of the instance across all of your apps and add-ons:

$ heroku redis:info maturing-calmly-4191 -a example-app
=== maturing-calmly-4191 (HEROKU_REDIS_ROSE_URL)
Plan:                   Premium 0
Status:                 Available
Created:                2024-09-30 21:40 UTC
Version:                7.2.4
Timeout:                300
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

In this example, maturing-calmly-4191 is upgraded from a Premium-0 plan to a Premium-1 plan. Remember, maturing-calmly-4191 is the name of the KVS instance and not the application in this case:

$ heroku addons:upgrade maturing-calmly-4191 heroku-redis:premium-1 -a example-app
Changing maturing-calmly-4191 plan to heroku-redis:premium-1... done, ($30.00/month)
The Heroku Data for Redis instance is in the process of being upgraded.
The time it takes to upgrade is dependent on how much data exists in the instance.

You can follow this process using heroku redis:info:

$ heroku redis:info maturing-calmly-4191 -a example-app
=== maturing-calmly-4191 (HEROKU_REDIS_ROSE_URL)
Plan:                   Premium 0
Status:                 Preparing (upgrade in progress)
Created:                2024-09-30 21:40 UTC
Timeout:                300
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

Migrating to Heroku Key-Value Store

You can populate a new Heroku Key-Value Store instance using another KVS instance, using heroku addons:create:

$ heroku addons:create heroku-redis:premium-0 --fork rediss://h:<password>@<hostname>:<port> -a example-app

$ heroku addons:create heroku-redis:premium-0 -a example-app -- --fork rediss://h:<password>@<hostname>:<port>
Creating heroku-redis:premium-0 on ⬢ example-app... $15/month
Your add-on is being provisioned and will be available shortly
redis-acute-6762 is being created in the background. The app will restart when complete...
Use heroku addons:info redis-acute-6762 to check creation progress
Use heroku addons:docs heroku-redis to view documentation

You can follow this process using heroku redis:info:

$ heroku redis:info redis-acute-6762 -a example-app
===redis-acute-6762 (HEROKU_REDIS_PURPLE_URL)
Plan:                   Premium 0
Status:                 Preparing (fork in progress)
Created:                2024-09-30 21:40 UTC
Timeout:                300
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

Upgrading a Heroku Key-Value Store Version

See Upgrading a Heroku Key-Value Store Version for instructions.

High Availability

All premium Heroku Key-Value Store plans come with the High Availability (HA) feature. When the primary KVS instance fails, it’s automatically replaced with another replica, called a standby.

Failover Conditions

In order to prevent problems commonly seen with hair-trigger failover systems, we run a suite of checks to ensure that failover is the appropriate response. These checks are run every few seconds and consist of establishing connections to the underlying host using the SSH protocol. However, when only the Redis process becomes unavailable for any reason, a failover is unnecessary and the process is booted back into availability instead, ensuring an even shorter downtime period whenever possible.

After our systems initially detect a problem, we confirm that the instance is truly unavailable by running several checks for two minutes across multiple network locations. This prevents transient problems from triggering a failover.

Standbys are kept up to date asynchronously. It’s possible for data to be committed on the primary instance but not yet on the standby. Typically, data loss is minimal because Redis isn’t committing the data to disk.

After Failover

After a successful failover, there are a few things to keep in mind. First, the URL for the instance has changed, and your app automatically restarts with the new credentials. If you’re on a single tenant plan (including Premium-7 and above), the failover is transparent. The underlying resource changes but the Elastic IP address (a URL) doesn’t. Finally, regardless of plan, a new standby is automatically recreated, and HA procedures can’t be performed until it becomes available and meets our failover conditions.

Performance Analytics

Performance Analytics is the visibility suite for Heroku Key-Value Store. It enables you to monitor the performance of your instance and to diagnose potential problems. It consists of several components.

Plan Limit Metrics

The leading cause of poor Redis performance is reaching the upper limit of your plan’s performance. Plan limit metrics, available via data.heroku.com, helps you identify and understand your Redis usage in terms of connections and memory usage over time.

Logging

If your application or framework emits logs on instance access, you can retrieve them through Heroku’s log stream.

$ heroku logs -t

To view logs from the Redis service itself, use the process type -p flag and the add-on name. This command indicates that you only want to see the logs from a specific Heroku Key-Value Store add-on.

$ heroku logs -p redis-triangular-12345 -t

The format of the output includes following pieces of information:

• Timestamp
• Service
• Resource Name
• Message

2024-03-15T14:25:57.000000+00:00 app[redis-triangular-12345]: Error accepting a client connection

Configuring Your Instance

Heroku Key-Value Store allows you to change your instance timeout and maxmemory-policy settings. These settings are kept across upgrades and HA failover.

timeout

The timeout setting sets the number of seconds Redis waits before killing idle connections. A value of zero means that connections aren’t closed. The default value is 300 seconds (5 minutes). You can change this value using the CLI:

$ 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.

maxmemory-policy

The maxmemory-policy setting sets the key eviction policy used when an instance reaches its storage limit. Available policies for key eviction include:

• noeviction returns errors when the memory limit is reached.
• allkeys-lru removes less recently used keys first.
• volatile-lru removes less recently used keys first that have an expiry set.
• allkeys-random evicts random keys.
• volatile-random evicts random keys that have an expiry set.
• volatile-ttl evicts keys with an expiry set and a short TTL.
• volatile-lfu evicts using approximated LFU among the keys with an expire set.
• allkeys-lfu evicts any key using approximated LFU.

By default, this setting is set to noeviction. You can change this value using the CLI:

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

Security and Compliance

Redis connections on Heroku Key-Value Store has native TLS support to encrypt traffic. All Key-Value Store plans require TLS with the REDIS_URL config var. As of December 2024, mini plans also require TLS with REDIS_URL instead of REDIS_TLS_URL.

Heroku Key-Value Store uses self-signed certificates, which can require you to configure the verify_mode SSL setting of your Redis client. See Connecting to Heroku Key-Value Store for examples on setting up TLS connections.

Using the CLI

For more information about managing Heroku Key-Value Store using the CLI, see Managing Heroku Key-Value Store Using the CLI.

Connecting to Heroku Key-Value Store

For more information about connecting to Heroku Key-Value Store, see Connecting to Heroku Key-Value Store.

Persistence

The Mini plan for Heroku Key-Value Store doesn’t persist instance data. If the instance must reboot or a failure occurs, the data on instance is lost.

The production plans of Heroku Key-Value Store (Premium, Private and Shield) use AOF persistence to write to disk every second. These plans have a high-availability standby for failover.

To get a backup of your data use the CLI fork option or use external replication. For more information about the fork option, see Migrating to Heroku Key-Value Store.

Deleting the Add-on

You can delete the add-on using the Heroku dashboard or using the CLI.

Delete Using the Dashboard

To delete a KVS instance from the Heroku dashboard:

1. From the Heroku Dashboard, navigate to your application and then select the Resources tab.
2. On the Resources tab, on the Heroku Key-Value Store resource, choose the selector on the right, and then select Delete Add-on.
3. On the Remove Add-on page, enter the app’s name as confirmation, and then select Remove add-on.

Delete Using the CLI

To delete the add-on from the CLI, use the following command:

$ heroku addons:destroy REDIS -a example-app
Destroying soaring-duly-3158 on example-app... done
Removing vars for REDIS from example-app and restarting... done, v75

Specify the add-on to be destroyed with one of the following:

• the attachment name of the Heroku Key-Value Store add-on (for example, REDIS, HEROKU_REDIS_BLUE)
• the name of the Heroku Key-Value Store add-on (for example, redis-fitted-65964)

Support

All Heroku Key-Value Store support and runtime issues must be submitted via one of the Heroku Support channels.