Heroku Postgres Maintenance Windows

Last updated 02 May 2018

From time to time, Heroku must take your database offline to perform maintenance tasks. Typical tasks include updating the underlying infrastructure of the database (for example, patching the operating system or required libraries) or upgrading Postgres itself. This maintenance is handled automatically by Heroku.

Checking if maintenance is required for your database

You can check if maintenance is required on a database by using pg:info.

$ heroku pg:info
=== DATABASE_URL
Plan:           Standard 4
Status:         Available
Data Size:      26.1 MB
...
Maintenance:    required by 2018-05-04 21:00:00 +0000
Maintenance:    scheduled for 2018-05-01 14:30:00 +0000, required by 2018-05-04 21:00:00 +0000, replacement currently being prepared
Maintenance window:    Tuesdays 14:30 to 18:30 UTC

You can also check with the pg:maintenance command:

$ heroku pg:maintenance DATABASE
Maintenance scheduled for 2018-05-01 14:30:00 +0000, required by 2018-05-04 21:00:00 +0000, replacement currently being prepared, window is Tuesdays 14:30 to 18:30 UTC

Maintenance types

There are several types of maintenances with Heroku Postgres, such as restart, changeover, and failover. Depending on the nature of the maintenance, as well as the database plans, we pick up the best maintenance option for the database.

For example, for HA plans (premium, private, and shield), we try to use failover whenever we can, unless it’s a follower of another database already. For non-HA plans (standard) and followers regardless of plan, we mainly use changeover.

For the changeover type, you’ll see the progress of the maintenance in pg:info or pg:maintenance, like the following:

$ heroku pg:maintenance DATABASE
Maintenance scheduled for 2018-05-01 14:30:00 +0000, required by 2018-05-04 21:00:00 +0000, replacement currently being prepared, window is Tuesdays 14:30 to 18:30 UTC

With changeover, we start creating a replacement when we schedule the maintenance. Creating a replacement can take time, depending on the size of the database. Once the replacement is ready, you’ll see the following:

$ heroku pg:maintenance DATABASE
Maintenance scheduled for 2018-05-01 14:30:00 +0000, required by 2018-05-04 21:00:00 +0000, replacement ready, window is Tuesdays 14:30 to 18:30 UTC

You will not see this info when the maintenance type is failover or restart. Once the replacement becomes ready, you can manually trigger the maintenance using heroku pg:maintenance:run.

Setting a maintenance window

Some database plans support maintenance windows that can be set. Users can specify the day-of-week and time (UTC) at which the maintenance will occur:

$ heroku pg:maintenance:window DATABASE "Sunday 14:30"

Setting a maintenance window allows you to minimize the impact on your application and users. We recommend selecting a time during which maintenance would have the least impact on your business. Maintenance windows are 4 hours long starting at the time you specify. The actual time required for maintenance depends on exactly what’s taking place, but it will usually require your database to be offline for only a few minutes.

Changing the scheduled maintenance time by modifying a maintenance window

Sometimes, you realize that the scheduled maintenance time is not ideal after the maintenance is scheduled and would like to move it. You can do it by changing the maintenance window. For example, you have the following schedule currently:

$ heroku pg:maintenance DATABASE
Maintenance scheduled for 2018-05-01 14:30:00 +0000, required by 2018-05-04 21:00:00 +0000, replacement currently being prepared, window is Tuesdays 14:30 to 18:30 UTC

Let’s say you want to run it on Wednesday 00:00 UTC, instead. You can change this by setting the maintenance window again:

$ heroku pg:maintenance:window DATABASE "Wednesday 00:00"
Setting maintenance window for postgresql-clean-29349 to Wednesday 00:00... done

Now the maintenance has a new scheduled time:

$ heroku pg:maintenance DATABASE
Maintenance scheduled for 2018-04-25 00:00:00 +0000, required by 2018-05-04 21:00:00 +0000, replacement currently being prepared, window is Wednesdays 00:00 to 04:00 UTC

Running a maintenance

For databases that support a maintenance window and have a maintenance that needs to occur, that maintenance can be run prior to the maintenance window. This will allow for the maintenance to occur on a time frame that you prefer if it happens to be outside the maintenance window.

Putting application in maintenance mode

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

$ heroku pg:maintenance:run DATABASE -a sushi
Starting maintenance for postgresql-clean-29349... done

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

Forcing a maintenance

Forcing a maintenance is an action that should be used with extreme caution. If the maintenance were to require some downtime, your application could see errors from being unable to connect to the database.

$ heroku pg:maintenance:run DATABASE --force -a sushi

Limitations

Maintenance windows that can be set and manual maintenance runs are only available on production plans (standard, premium, private and shield).

Heroku will make the best effort to honor your maintenance window request but it is not guaranteed. If there is an emergency where the security or integrity of your data is threatened, we may perform the maintenance outside of your regular window at our discretion.