Heroku Data for Redis
Last updated October 03, 2024
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
- Persistence
- Deleting the Add-on
- Support
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
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) 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, production plans require TLS connections. You must enable TLS in your Redis client’s configuration in order to connect to a Redis 6 database. Mini plans support both TLS and unencrypted connections, but will require TLS connections on December 2, 2024. 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:asdfqwer1234asdf@ec2-111-1-1-1.compute-1.amazonaws.com:111
The REDIS_URL
and 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 promote
command:
$ 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 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 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 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 Redis add-ons and implementations.
Heroku Data for Redis 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:
Version | Status | End-Of-Life Date |
---|---|---|
6.2 | Deprecated | December 2, 2024 |
7.0 | Available | Q4 2025 |
7.2 | Available (default) | Q4 2026 |
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 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 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 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
:
$ 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 Data for Redis
You can populate a new Heroku Data for Redis instance using another Redis instance, using heroku addons:create
:
The addons:create
example follows the syntax for Heroku CLI v9.0.0 or later. If you’re on v8.11.5 or earlier, use the command:
$ 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
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
:
$ 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
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.
High Availability
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.
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 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.
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 Data for Redis 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
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 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.
Heroku Data for Redis doesn’t support tuning lfu-log-factor
or lfu-decay-time
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 *_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. Mini plans will require TLS connections on December 2, 2024. See this Help article for the changes you must make for REDIS_URL
.
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.
Persistence
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,
REDIS
,HEROKU_REDIS_BLUE
) - the name of the Heroku Data for Redis add-on (for example,
redis-fitted-65964
)
Support
All Heroku Data for Redis support and runtime issues must be submitted via one of the Heroku Support channels.