Heroku Data for Redis
Last updated September 20, 2023
Table of Contents
- Provisioning the Add-on
- Version Support and Legacy Infrastructure
- Upgrading a Heroku Data for Redis Plan
- Migrating to Heroku Data for Redis
- Upgrading a Heroku Data for Redis Version
- High Availability
- Performance Analytics
- Configuring Your Instance
- Security and Compliance
- Using the CLI
- Connecting to Heroku Data for Redis
- Deleting the Add-on
Heroku Data for Redis is an in-memory key-value data store, run by Heroku, that is provisioned and managed as an add-on. Heroku Data for Redis is accessible from any language with a Redis driver, including all languages and frameworks supported by Heroku.
Where possible, noninclusive terms have changed to align with Salesforce’s company value of Equality. Noninclusive terms remain to document a third-party system, but Heroku encourages the developer community to embrace more inclusive language. Heroku updates noninclusive terms when they’re no longer required for technical accuracy.
Provisioning the Add-on
Check If a Redis Instance is Already Provisioned
heroku addons command to see if your application already has a Redis instance provisioned:
$ heroku addons | grep heroku-redis heroku-redis (cooking-peacefully-8526) mini $3/month
Create an Instance
Heroku Data for Redis can be attached 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 Data for Redis plans, see Heroku Data for Redis Plans and Pricing.
As of Redis version 6, Mini plans support both TLS and unencrypted connections. Production plans require TLS connections. You must enable TLS in your Redis client’s configuration in order to connect to a Redis 6 database. For more information, see Heroku Data for Redis Security and Compliance.
If you’ve manually created a
REDIS_URL config var on your app, it’s overwritten when you add your first heroku-redis add-on. To save it, copy the config var to a different config var key. You can also use the
--as option to
heroku addons:create to use a different URL for heroku-redis, as documented here.
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 Heroku Data for 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 Data for Redis instance. You can confirm the URL with the
heroku config command:
$ heroku config | grep REDIS REDIS_URL: redis://h:firstname.lastname@example.org:111
REDIS_TLS_URL config vars can change at any time. If you rely on the config var outside of your Heroku app and it changes, you must recopy the value.
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
$ heroku redis:promote HEROKU_REDIS_JADE Promoting maturing-deeply-2628 to REDIS_URL on example-app
Sharing Heroku Data for Redis between Applications
You can share one Heroku Data for Redis 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 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’s attached as
REDIS with the config var
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 no longer updates the security and functionality of add-ons on “EOL” or “Deprecated” versions. Customers might see an increased risk of security incidents if they don’t upgrade to the latest, supported versions of Heroku Data for Redis as required in their Main Services Agreement.
Heroku currently offers Redis version 7.0 as the default and continues to provide updates and support for versions 7.0 and 6.2.
Heroku Data for 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:
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 fixed 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 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.
Upgrading a Heroku Data for Redis Plan
You can upgrade your Heroku Data for Redis plan. To upgrade, first, find the resource name of the Heroku Data for 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 example-app === 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 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.
When upgrading an instance, Heroku Data for Redis copies data from one instance to another before doing the changeover. There’s a delay before the upgrade is complete.
You can follow this process using
$ heroku redis:info -a example-app ===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 Data for Redis
You can populate a new Heroku Data for Redis instance using another Redis instance, using
$ heroku addons:create heroku-redis:premium-0 --fork rediss://h:<password>@<hostname>:<port> -a example-app 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
The migration process creates a new instance, and will start to follow the given Redis URL, and will stop following it after all data has been transferred over.
You can follow this process using
$ heroku redis:info -a example-app ===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
External Redis instances must support the
SYNC for the fork functionality to work. An error is thrown if the external Redis instance doesn’t have the necessary support.
Heroku recommends using encryption and thus a
rediss:// URL instead of
redis://when creating a fork. Encrypted Heroku Data for Redis instances expose a
rediss:// service for Premium, Private, and Shield databases. For Mini databases, the ports are different, you can find the TLS url (including port) in the
TLS_URL config var. On versions older than 6, encrypted Heroku Data for Redis instances expose a
rediss:// service on port
6480 instead of the cleartext port
6479 for Premium, Private, and Shield databases.
The fork command doesn’t copy any customized settings, including eviction policy. For example, if you’ve customized the connection timeout using
heroku redis:timeout the timeout isn’t copied to the fork.
Upgrading a Heroku Data for Redis Version
See Upgrading a Heroku Data for Redis Version for instructions.
All premium Heroku Data for 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.
HA standbys are physically located in different availability zones to protect against availability-zone-wide failures.
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 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 is the visibility suite for Heroku Data for 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.
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 Data for Redis.
$ heroku logs -s redis -t
The format of output has the following pieces of information:
- Resource Name
2016-04-22T21:25:09Z redis[redis-clear-69157]: * The server is now ready to accept connections on port 7889
In order to have minimal impact on instance performance, logs are delivered on a best-effort basis.
Configuring Your Instance
Heroku Data for Redis allows you to change your instance
maxmemory-policy settings. These settings are kept across upgrades and HA failover.
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 setting sets the key eviction policy used when an instance reaches its storage limit. Available policies for key eviction include:
noevictionreturns errors when the memory limit is reached.
allkeys-lruremoves less recently used keys first.
volatile-lruremoves less recently used keys first that have an expiry set.
allkeys-randomevicts random keys.
volatile-randomevicts random keys that have an expiry set.
volatile-ttlevicts keys with an expiry set and a short TTL.
volatile-lfuevicts using approximated LFU among the keys with an expire set.
allkeys-lfuevicts any key using approximated LFU.
Heroku Data for Redis doesn’t support tuning
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.
You can also set these settings when provisioning a new plan:
heroku addons:create heroku-redis:premium-0 --timeout 60 --maxmemory_policy volatile-lru
Security and Compliance
Redis 6 and higher has native TLS support to encrypt traffic.
On production plans using Redis 6 and higher, connecting to Heroku Data for Redis requires TLS.
On Mini plans, Heroku Data for Redis accepts both TLS and non-TLS connections and exposes two different connection strings via the
*_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.
Heroku Data for Redis uses self-signed certificates, which can require you to configure the
verify_mode SSL setting of your Redis client. See Connecting to Heroku Data for Redis for examples on setting up TLS connections.
Using the CLI
For more information about managing Heroku Data for Redis using the CLI, see Managing Heroku Data for Redis Using the CLI.
Connecting to Heroku Data for Redis
For more information about connecting to Heroku Data for Redis, see Connecting to Heroku Data for Redis.
The Mini plan for Heroku Data for 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 Data for 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 Data for Redis.
Deleting the Add-on
You can delete the add-on using the Heroku dashboard or using the CLI.
Heroku Data for Redis instances can’t be recovered after being destroyed. Make a copy of your Redis data before you delete the instance.
Delete Using the Dashboard
To delete a Redis instance from the Heroku dashboard:
- From the Heroku Dashboard, navigate to your application and then select the Resources tab.
- On the Resources tab, on the Heroku Data for Redis resource, choose the selector on the right, and then select Delete Add-on.
- 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 Data for Redis add-on (for example,
- the name of the Heroku Data for Redis add-on (for example,
All Heroku Data for Redis support and runtime issues must be submitted via one of the Heroku Support channels.