Last updated November 12, 2024

From time to time, Heroku performs maintenance tasks on your Heroku Key-Value Store instance. Typical tasks include updating the underlying infrastructure. For example, patching the operating system or required libraries, or upgrading Redis itself. Heroku handles these maintenance tasks automatically.

You can also manage your planned maintenance with the Data Maintenance CLI Plugin commands. Install the plugin before running the data:maintenances:* commands in this article.

There are three ways to perform maintenance:

• Heroku automatically performs maintenance for you.
• You perform maintenance manually with maintenance mode.
• You perform maintenance manually without maintenance mode.

Checking for Required Maintenance

You can check if maintenance is required on your instance by using redis:info:

$ heroku redis:info
=== redis-softly-4514 (REDIS_URL)
Plan:               Premium 7
Status:             available
...
Maintenance:        required by 2016-02-01 00:00:00 +0000

You can also check with the data:maintenances:info command:

$ heroku data:maintenances:info REDIS_URL -a example-app
Fetching maintenance... done
addon_attachments:    REDIS_URL
addon_description:    premium HA
addon_kind:           heroku-redis
addon_name:           redis-lively-12345
addon_plan:           premium-0
addon_window:         Fridays 18:00 to 22:00 UTC
app_name:             example-app
completed_at:         2023-04-28T18:04:21.141+00:00
duration_approximate: ~ 3 minutes
duration_seconds:     186
method:               failover
reason:               routine_maintenance
required_by:          2023-05-03T08:54:02.518+00:00
scheduled_for:        2023-04-28T18:00:00.000+00:00
server_created_at:    2022-12-26T08:30:37.872+00:00
started_at:           2023-04-28T18:01:14.191+00:00
status:               completed
window:               Fridays 18:00 to 22:00 UTC

Heroku Key-Value Store instances are updated regularly to maintain important security patches in Redis and the underlying software and hardware. Maintenance tasks occur at least once every 90 days.

Setting a Maintenance Window

When you provision an instance, the default maintenance window is set to a time between Monday to Friday and 18:00 to 23:00 UTC (10:00 to 15:00 PT). You can specify a maintenance window for instances on Premium, Private, and Shield Heroku Key-Value Store plans. You can specify the day of the week and time in UTC when the window begins:

$ heroku data:maintenances:window:update REDIS_URL Sunday 14:30 -a example-app

Setting a maintenance window minimizes the impact of the maintenance on your application and users. Heroku recommends selecting a time when a maintenance event has the smallest impact on your business.

You receive an email letting you know the time of your upcoming maintenance window. You can verify when the time with the heroku data:maintenances:info command. This command indicates when your maintenance event is scheduled and if it’s ready to run.

Maintenance windows are 4 hours long. Heroku attempts to begin the maintenance as close to the beginning of the specified window as possible. The actual time required for the maintenance event depends on exactly what’s taking place, but usually, your KVS instance is offline for only a few minutes. If you don’t specify a window, one is selected randomly.

Rescheduling the Maintenance Window

You can change your instance’s maintenance window by running the data:maintenances:window:update command again and providing a different start time for the window.

Performing Maintenance Manually

There are three ways to perform maintenance:

• Heroku automatically performs maintenance for you.
• You perform maintenance manually with maintenance mode.
• You perform maintenance manually without maintenance mode.

Automatically

The most common way to perform maintenance is to let Heroku do it for you. We use your instance’s maintenance window to determine the best time to perform maintenance automatically.

With Maintenance Mode Enabled

The following commands demonstrate putting an app in maintenance mode and then manually performing maintenance on its associated instance:

$ heroku maintenance:on -a example-app
Enabling maintenance mode for ⬢ example-app... done

$ heroku data:maintenances:run REDIS_URLL -a example-app
Starting maintenance for redis-clean-29349... done

$ heroku maintenance:off -a example-app
Disabling maintenance mode for ⬢ example-app... done

This method can have benefits such as providing a clean landing page for your users, but total downtime can be longer as it’s a manual process to enable and disable maintenance mode.

Without Maintenance Mode Enabled

Performing maintenance manually without first enabling maintenance mode requires the --confirm flag with the app name:

$ heroku data:maintenances:run REDIS_URL -a example-app --confirm example-app

This command immediately fails over to your HA Standby or the hidden Standby if it’s caught up. Your application immediately restarts and points to the new Primary, which was the former Standby. The impact of this option is similar to when Heroku performs maintenance for you.

Limitations

You can only set maintenance windows and manually perform maintenance on Premium, Private, and Shield plans.

Heroku makes the best effort to honor your maintenance window request but it isn’t guaranteed. If there’s an emergency where the security or integrity of your data is threatened, we can perform maintenance outside of your regular window at our discretion.