Last updated March 16, 2022

Heroku Redis is an in-memory key-value data store, run by Heroku, that is provisioned and managed as an add-on. Heroku Redis is accessible from any language with a Redis driver, including all languages and frameworks supported by Heroku.

Provisioning the Add-on

Check If a Redis Instance is Already Provisioned

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

$ heroku addons | grep heroku-redis
heroku-redis (cooking-peacefully-8526)                hobby-dev    free

Create an Instance

Heroku Redis can be attached to an application via the CLI:

$ heroku addons:create heroku-redis:hobby-dev -a your-app-name

This and other examples use the hobby-dev plan. To learn more about Heroku Redis plans, see Heroku Redis 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:  sushi::HEROKU_REDIS
Installed at: Tue Nov 29 2016 10:12:34 GMT-0800 (PST)
Owning app:   sushi
Plan:         heroku-redis:hobby-dev
Price:        free
State:        creating

After Heroku Redis has been created, 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 Redis 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 Redis 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 sushi

Sharing Heroku Redis between Applications

You can share one Heroku Redis between multiple applications.

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

If you already have a Redis addon 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 is attached as REDIS with the config var REDIS_URL.

The shared database won’t necessarily be 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 sushi
Promoting redis-addon-name to REDIS_URL on sushi

Version Support and Legacy Infrastructure

Heroku currently offers Redis version 6.2 as the default.

Heroku Redis defaults to the latest stable version of Redis allowlisted for the platform. Heroku follows the release schedule of the Redis project in that at least two releases are supported on the platform. Currently supported versions include:

Hobby plans can’t be created using Redis versions earlier than 6, however production plans can be created using older supported versions. For example, to create a Redis service on version 5 using the premium-0 plan:

$ heroku addons:create heroku-redis:premium-0 --version 5 -a your-app-name

The Redis project only supports the current release and the previous stable release based on its release cycle documentation. This means that bug reports can be filed and fix for either branch. Heroku makes every effort to keep each of the instances up to the latest patch release when possible.

Heroku also deprecates old versions of our infrastructure. This can happen if the operating system running beneath the database will no longer receive security updates, if support for the operating system is no longer practical due to age (if required 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.

Upgrading a Heroku Redis Plan

You can upgrade your Heroku Redis plan. To upgrade, first, find the resource name of the Heroku Redis 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 -a sushi
=== maturing-calmly-4191 (HEROKU_REDIS_ROSE_URL)
Plan                Premium 0
Status              Available
Created             2015-07-20 20:26 UTC
Timeout             300
Maxmemory           noeviction
Maintenance window: Mondays 22:30 to Tuesdays 02:30 UTC
Persistence:        AOF

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 Redis instance and not the application in this case:

$ heroku addons:upgrade maturing-calmly-4191 heroku-redis:premium-1 -a sushi
Changing maturing-calmly-4191 plan to heroku-redis:premium-1... done, ($30.00/month)
The Heroku 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 -a sushi
===maturing-calmly-4191 (HEROKU_REDIS_ROSE_URL)
Plan                Premium 0
Status              Preparing (upgrade in progress)
Created             2015-07-20 20:26 UTC
Timeout             300
Maxmemory           noeviction
Maintenance window: Mondays 22:30 to Tuesdays 02:30 UTC
Persistence:        AOF

Migrating to Heroku Redis

You can populate a new Heroku Redis instance using another Redis instance, using heroku addons:create:

$ heroku addons:create heroku-redis:premium-0 --fork rediss://h:<password>@<hostname>:<port> -a sushi
Creating heroku-redis:premium-0 on ⬢ sushi... $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 -a sushi
===redis-acute-6762 (HEROKU_REDIS_PURPLE_URL)
Plan                Premium 0
Status              Preparing (fork in progress)
Created             2015-07-20 20:30 UTC
Timeout             300
Maxmemory           noeviction
Maintenance window: Mondays 22:30 to Tuesdays 02:30 UTC
Persistence:        AOF

Upgrading a Heroku Redis Version

See Upgrading a Heroku Redis Version for instructions.

High Availability

All premium Heroku Redis plans come with the High Availability (HA) feature. When the primary Redis 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 is 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 Redis. 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/framework emits logs on instance access, you can retrieve them through Heroku’s log stream.

$ heroku logs -t

To view logs from the instance service itself, use the -s redis flag to indicate that you only want to see the logs from Heroku Redis.

$ heroku logs -s redis -t

The format of output has the following pieces of information:

• Timestamp
• Service
• Resource Name
• Message

2016-04-22T21:25:09Z redis[redis-clear-69157]: * The server is now ready to accept connections on port 7889

Configuring Your Instance

Heroku Redis 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 are not 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 6 has native TLS support to encrypt traffic.

On production plans using Redis 6, connecting to Heroku Redis requires TLS. For versions older than 6, see Securing Heroku Redis Versions 4 and 5 for more information.

On hobby plans, Heroku Redis accepts both TLS and non-TLS connections and exposes two different connection strings via the *_TLS_URL and *_URL config vars. The TLS config var, REDIS_TLS_URL by default, uses the rediss scheme in the connection string and points to the TLS port. The non-TLS config var, REDIS_URL by default, uses the redis scheme in the connection string and points to the non-TLS port.

Currently, Heroku Redis uses self-signed certificates, which can require you to configure the verify_mode SSL setting of your Redis client. See the connection guides later in this article for examples on setting up TLS connections.

Using the CLI

For more information about managing Heroku Redis using the CLI, see Managing Heroku Redis Using the CLI.

Connecting to Heroku Redis

For more information about connecting to Heroku Redis, see Connecting to Heroku Redis.

Persistence

The hobby tier for Heroku Redis 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 Redis (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 Redis.

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 Redis 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 Redis 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 Redis add-on (e.g. REDIS, HEROKU_REDIS_BLUE)
• the name of the Heroku Redis add-on (e.g. redis-fitted-65964)

Support

All Heroku Redis support and runtime issues should be submitted via one of the Heroku Support channels.