Last updated January 28, 2021

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 a new instance

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

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

heroku addons:info command will show you the progress of creation. State “creating” means that it is 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

Once Heroku Redis has been created, the new release will be created and the application will restart. A REDIS_URL config var will be made available in the app configuration and will contain the URL used to access the newly provisioned Heroku Redis instance. This can be confirmed using 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 recommends using the REDIS_URL config var to store the location of the primary instance. In single-instance setups, your new instance will have already been assigned a REDIS_URL. In cases where REDIS_URL already exists, your instance will be 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 an Redis addon provisioned, the database will be attached with a color (in this example HEROKU_REDIS_CYAN but it will change each time). If you don’t have one, it will be attached as REDIS with the config var REDIS_URL.

The shared database will not necessarily be the default database on any apps that it is 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 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:

• 4.0
• 5.0
• 6.0 (default)

Hobby plans cannot 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 will also deprecate old versions of our infrastructure. We typically do this if the operating system running beneath the database will no longer receive security updates, if support for the OS 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 instance

Heroku Redis provides a seamless upgrade experience. First, find the resource name of the Heroku Redis instance that needs to 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 will be 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

Heroku Redis defaults to the latest stable version of Redis allowlisted for the platform, so newly created Heroku Redis will always use the latest version. You can upgrade the Redis version by creating a new Heroku Redis instance. If you’re using Redis for a caching purpose, or if you don’t need to transfer the Redis data to the new instance, you can simply provision a new Redis and promote it. If you’d like to transfer the data to the new database, you can use --fork to copy the current data in Redis to the new instance.

1. Prevent new updates

It is important that no new data is written to your application during the upgrade process or it will not be transferred to the new Redis instance. To accomplish this, place your app into maintenance mode. If you have scheduler jobs running as well, you should disable them.

Maintenance mode does not automatically scale down any dynos. Web and any non-web dynos (especially worker dynos, if you’re using Redis for queueing jobs) should be scaled down to make sure that no connections are writing data to the Redis.

2. Create fork

Once you’ve made sure that there are no updates, create a new fork. You can obtain the connection info (rediss://h:<password>@<hostname>:<port>) of the current Redis instance by using heroku config:get REDIS_URL. The following command creates a new Heroku Redis add-on instance, forking the data from the URL of the old one:

$ 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-spherical-37410 is being created in the background. The app will restart when complete...
Use heroku addons:info redis-spherical-37410 to check creation progress
Use heroku addons:docs heroku-redis to view documentation

You can follow this process using heroku redis:info.

3. Promote fork

The fork will create a new Redis instance and copy the data over to the new instance. This process can take a few minutes. You can monitor the progress with heroku redis:info, and once you’ve confirmed that the forked Redis instance is in an available state, you will need to promote it. You will need to specify the name of the Redis instance such as redis-spherical-37410, you can get this with heroku redis:info command.

$ heroku redis:promote redis-spherical-37410 -a sushi
Promoting redis-spherical-37410 to REDIS_URL on sushi

Promoting a forked Redis instance will update the REDIS_URL config var, and will restart the application.

4. Make application active

To resume normal application operation, scale any non-web dynos back to their original levels. (If the application was not previously using non-web dynos, skip this step in order to avoid scaling any dynos that you may not need). Then, turn off maintenance mode.

High availability

All premium Heroku Redis plans come with the High Availability (HA) feature. When the primary Redis instance fails, it is 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 simply 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. This means that 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 is not 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 will have changed, and your app will automatically restart with the new credentials. If you’re on a single tenant plan, this includes Premium-7 and above, the failover will happen transparently meaning the underlying resource will change but the Elastic IP address will not. Finally, regardless of plan, a new standby is automatically recreated, and HA procedures cannot 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 will be able to 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 will have 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 will be 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 will not be 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 will return errors when the memory limit is reached.
• allkeys-lru will remove less recently used keys first.
• volatile-lru will remove less recently used keys first that have an expiry set.
• allkeys-random will evict random keys.
• volatile-random will evict random keys but only those that have an expiry set.
• volatile-ttl will only evict keys with an expiry set and a short TTL.
• volatile-lfu will evict using approximated LFU among the keys with an expire set.
• allkeys-lfu will evict 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 data stores using version 6 or newer, use native TLS support to encrypt traffic. TLS is required on production plans. On hobby plans, there is a REDIS_TLS_URL that is encrypted. For versions older than 6, please see the Securing Heroku Redis Dev Center article for more information.

Using the CLI

Heroku Redis is integrated directly into the Heroku CLI and offers several commands for managing a Redis instance.

redis:info

To see all Redis 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            2015-03-26 23:40 UTC
Timeout            60
Maxmemory          volatile-lru
Maintenance window Mondays 22:30 to Tuesdays 02:30 UTC
Persistence        AOF

=== maturing-calmly-4191 (HEROKU_REDIS_AMBER_URL)
Plan               Premium 1
Status             Available
Created            2015-03-20 23:40 UTC
Timeout            0
Maxmemory          noeviction
Maintenance window Mondays 22:30 to Tuesdays 02:30 UTC
Persistence        AOF

redis:cli

To establish a Redis CLI session with your remote Redis 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 you have more than one instance, 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 Redis provides convenient access to the credentials and location of your instance should you want 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 is a good security practice to rotate the credentials for important services on a regular basis. On Heroku Redis, this can be done with heroku redis:credentials --reset.

$ 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 bee run but before dynos have restarted with the new value of the config var will fail.

redis:promote

In configurations where more than one Redis instance is provisioned, it is often necessary to promote an instance to the primary role. This is accomplished with 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 Redis instance location is still accessible via its HEROKU_REDIS_COLOR_URL setting.

redis:timeout

To change the number of seconds Redis waits before killing idle connections, as explained earlier, 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, as explained earlier, 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.

Connecting in Java

A variety of ways exist to connect to Heroku Redis but each depends on the Java framework in use. All methods of connecting use the REDIS_URL environment variable to determine connection information.

Spring Boot

Spring Boot’s support for Redis picks up all Redis configuration such as REDIS_URL automatically. We only need to define a LettuceClientConfigurationBuilderCustomizer bean to disable TLS peer verification:

@Configuration
class AppConfig {

    @Bean
    public LettuceClientConfigurationBuilderCustomizer lettuceClientConfigurationBuilderCustomizer() {
        return clientConfigurationBuilder -> {
            if (clientConfigurationBuilder.build().isUseSsl()) {
                clientConfigurationBuilder.useSsl().disablePeerVerification();
            }
        };
    }
}

Lettuce

This snippet will use the REDIS_URL environment variable to create a new connection to Redis via Lettuce. StatefulRedisConnection is thread-safe and can be safely used in a multithreaded environment.

 public static StatefulRedisConnection<String, String> connect() {
    RedisURI redisURI = RedisURI.create(System.getenv("REDIS_URL"));
    redisURI.setVerifyPeer(false);

    RedisClient redisClient = RedisClient.create(redisURI);
    return redisClient.connect();
}

Jedis

This snippet will use the REDIS_URL environment variable to create a new URI that will be used to create a connection to Redis via Jedis. In this example, we’re creating one connection to Redis.

private static Jedis getConnection() {
    try {
        TrustManager bogusTrustManager = new X509TrustManager() {
            public X509Certificate[] getAcceptedIssuers() {
                return null;
            }

            public void checkClientTrusted(X509Certificate[] certs, String authType) {
            }

            public void checkServerTrusted(X509Certificate[] certs, String authType) {
            }
        };

        SSLContext sslContext = SSLContext.getInstance("SSL");
        sslContext.init(null, new TrustManager[]{bogusTrustManager}, new java.security.SecureRandom());

        HostnameVerifier bogusHostnameVerifier = (hostname, session) -> true;

        return new Jedis(URI.create(System.getenv("REDIS_URL")),
                sslContext.getSocketFactory(),
                sslContext.getDefaultSSLParameters(),
                bogusHostnameVerifier);

    } catch (NoSuchAlgorithmException | KeyManagementException e) {
        throw new RuntimeException("Cannot obtain Redis connection!", e);
    }
}

If you’re running Jedis in a multithreaded environment, such as a web server, the same Jedis instance should not be used to interact with Redis. Instead, a Jedis Pool should be created so that the application code can checkout a Redis connection and return it to the pool when it’s done.

// The assumption with this method is that it's been called when the application
// is booting up so that a static pool has been created for all threads to use.
// e.g. pool = getPool()
public static JedisPool getPool() {
    try {
        TrustManager bogusTrustManager = new X509TrustManager() {
            public X509Certificate[] getAcceptedIssuers() {
                return null;
            }

            public void checkClientTrusted(X509Certificate[] certs, String authType) {
            }

            public void checkServerTrusted(X509Certificate[] certs, String authType) {
            }
        };

        SSLContext sslContext = SSLContext.getInstance("SSL");
        sslContext.init(null, new TrustManager[]{bogusTrustManager}, new java.security.SecureRandom());

        HostnameVerifier bogusHostnameVerifier = (hostname, session) -> true;

        JedisPoolConfig poolConfig = new JedisPoolConfig();
        poolConfig.setMaxTotal(10);
        poolConfig.setMaxIdle(5);
        poolConfig.setMinIdle(1);
        poolConfig.setTestOnBorrow(true);
        poolConfig.setTestOnReturn(true);
        poolConfig.setTestWhileIdle(true);

        return new JedisPool(poolConfig,
                URI.create(System.getenv("REDIS_URL")),
                sslContext.getSocketFactory(),
                sslContext.getDefaultSSLParameters(),
                bogusHostnameVerifier);

    } catch (NoSuchAlgorithmException | KeyManagementException e) {
        throw new RuntimeException("Cannot obtain Redis connection!", e);
    }
}

// In your multithreaded code this is where you'd checkout a connection
// and then return it to the pool
try (Jedis jedis = pool.getResource()){
  jedis.set("foo", "bar");
}

Connecting in Ruby

To use Redis in your Ruby application, you will need to include the redis gem in your Gemfile.

gem 'redis'

Run bundle install to download and resolve all dependencies.

Connecting in Rails

Create an initializer file named config/initializers/redis.rb containing:

$redis = Redis.new(url: ENV["REDIS_URL"], ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_NONE })

Connecting in Python

To use Redis in Python your application, you will need to use the redis package.

$ pip install redis
$ pip freeze > requirements.txt

And use this package to connect to REDIS_URL in your code:

import os
import redis

r = redis.from_url(os.environ.get("REDIS_URL"))

If your redis requires TLS

import os
from urllib.parse import urlparse
import redis

url = urlparse(os.environ.get("REDIS_URL"))
r = redis.Redis(host=url.hostname, port=url.port, username=url.username, password=url.password, ssl=True, ssl_cert_reqs=None)

Connecting in Django

To use Redis in your Django application, you will need to use the django-redis-cache.

$ pip install django-redis-cache
$ pip freeze > requirements.txt

In your settings.py, configure your CACHES as:

import os

CACHES = {
    "default": {
         "BACKEND": "redis_cache.RedisCache",
         "LOCATION": os.environ.get('REDIS_URL'),
    }
}

If your redis requires TLS

import os

CACHES = {
    "default": {
         "BACKEND": "redis_cache.RedisCache",
         "LOCATION": os.environ.get('REDIS_URL'),
         "OPTIONS": {
            "CONNECTION_POOL_KWARGS": {
                "ssl_cert_reqs": False
            }
        }
    }
}

Connecting in Node.js

redis module

Add the redis NPM module to your dependencies:

npm install redis

And use the module to connect to REDIS_URL:

const redis = require("redis");
const client = redis.createClient(process.env.REDIS_URL);

Additionally, you configure redis to use TLS:

const redis = require("redis");
const fs = require("fs");

const client = redis.createClient(process.env.REDIS_URL, {
    tls: {
        rejectUnauthorized: false
    }
});

ioredis module

Add ioredis NPM module to your dependencies:

npm install ioredis

And use the module to connect to REDIS_URL:

const Redis = require("ioredis");
const client = new Redis(process.env.REDIS_URL);

If you want to set up the client with TLS, you can use the following:

const Redis = require("ioredis");
const fs = require("fs");

const client = new Redis(process.env.REDIS_URL, {
    tls: {
        rejectUnauthorized: false
    }
});

Connecting in PHP

Add the predis package to your requirements in composer.json:

"require": {
  ...
  "predis/predis": "1.0.3",
  ...
}

Connect to Redis using the the REDIS_URL configuration variable:

$redis = new Predis\Client(getenv('REDIS_URL'));

Connecting in Go

Add the redigo package in your application:

$ go get github.com/gomodule/redigo/redis

Import the package:

import "github.com/gomodule/redigo/redis"

Connect to Redis using the REDIS_URL configuration variable:

c, err := redis.DialURL(os.Getenv("REDIS_URL"),  redis.DialTLSSkipVerify(true))
if err != nil {
    // Handle error
}
defer c.Close()

Connection permissions

All Heroku Redis users are granted access to all commands within Redis except CONFIG, SHUTDOWN, BGREWRITEAOF, BGSAVE, SAVE, MOVE, MIGRATE, SLAVEOF, DEBUG and OBJECT.

External connections

In addition to being available to the Heroku runtime, Heroku Redis instances can be accessed directly by clients running on your local computer or elsewhere.

You can retrieve the Redis connection string in one of two ways:

• With the heroku redis:credentials command, as explained earlier.
• By looking at your config vars. For example, with heroku config | grep REDIS.

Persistence

The hobby tier for Heroku Redis does not have any persistence. This means that, if the instance needs to reboot or a failure occurs, the data on instance will be lost. The production plans of Heroku Redis (Premium and Private) use AOF persistence to write to disk every second. The production plans have an HA standby for failover and takes a snapshot every hour. Heroku Redis does not expose a method or interface for downloading the snapshots that are taken. If a backup is desired, using the fork option via the CLI or external replication is a way to snapshot the Redis instance in its current state.

Removing the add-on

In order to destroy your Heroku Redis instance you will need to remove the add-on.

$ heroku addons:destroy heroku-redis:test
Destroying soaring-duly-3158 on sushi... done
Removing vars for REDIS from sushi and restarting... done, v75

If you have two instances of the same type you will need to remove the add-on using its config var name. View the Redis config vars by typing heroku config | grep REDIS. For example, if you had a config var named HEROKU_REDIS_GRAY_URL, to remove that instance you would run:

$ heroku addons:destroy HEROKU_REDIS_GRAY

If the removed instance was the same one used in REDIS_URL, that REDIS_URL config var will also be unset on the app.

Support

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