Data Maintenance CLI Commands

Table of Contents [expand]

Commands

Last updated March 18, 2026

On March 18, 2026, we added the commands from the Data Maintenance CLI plugin into the Heroku CLI. These commands include and expand on the functionality of the pg:maintenance, pg:maintenance:run, pg:maintenance:window, and redis:maintenance commands, which are no longer available.

The data:maintenances CLI commands help you manage planned maintenance for Heroku Data add-ons. Using these maintenance-related commands is optional. Heroku schedules and performs maintenance on Heroku Data add-ons automatically without any intervention.

Heroku performs maintenance for Essential Heroku Postgres databases and Mini Heroku Key-Value Store instances as needed and without notice. The following commands are only relevant for add-ons on Standard, Premium, Private, and Shield plans for Heroku Postgres and Premium, Private, and Shield plans for Heroku Key-Value Store.

If you want more control over the maintenance process, use these commands to control when and how planned maintenance occurs. For Heroku Postgres and Heroku Key-Value Store, use these commands to:

Review maintenance windows
Change maintenance windows
Schedule to run a maintenance event
Reschedule an existing maintenance event
Trigger a maintenance event
View details of a planned maintenance event
Review history of planned maintenance events
Wait for a triggered maintenance event to complete
Test maintenance impact on a staging app

For more info on the maintenance process, see Heroku Key-Value Store Maintenance and Heroku Postgres Maintenance.

Data Maintenance Commands and Apache Kafka for Heroku

For Apache Kafka for Heroku, the commands provide limited support for viewing details about in-progress and historical maintenance on your clusters. Only the data:maintenances:info and data:maintenances:history commands are available for your Kafka add-ons. See the Apache Kafka on Heroku Maintenance FAQ for more information.

Commands

`heroku data:maintenances`

The heroku data:maintenances command lists the most recent maintenance event for each Heroku Data add-on for an app. This event is either pending maintenance if one exists, or the most recent completed maintenance event. pending maintenance events include a required by and a scheduled for timestamp.

$ heroku data:maintenances -a example-app

Fetching maintenances... done
Addon                    Attachments     Scheduling Window                    Status    Required by  Scheduled for
 ────────────────────── ───────────────── ─────────────────────────────────── ───────── ────────────── ───────────────────
redis-spherical-12345   REDIS_URL        Thursdays 20:30 to Fridays 00:30 UTC  completed  -            -
postgresql-cubed-56789  DATABASE_URL     Tuesdays 19:00 to 23:00 UTC           completed  -            -

`heroku data:maintenances:info`

The heroku data:maintenances:info command displays details of the most recent maintenance event for a single Heroku Data add-on. This event is either pending maintenance if one exists, or the most recent completed maintenance event. pending maintenance events include a required by and a scheduled for timestamp.

$ heroku data:maintenances:info DATABASE -a example-app

Fetching maintenance... done
addon_attachments: DATABASE_URL
addon_description: Standard Non-HA
addon_kind:        heroku-postgresql
addon_name:        postgresql-octagonal-1234
addon_plan:        standard-4
addon_window:      Tuesdays 14:30 to 18:30 UTC
app_name:          example-app
method:            changeover
reason:            routine_maintenance
required_by:       2026-01-31 21:00:00 +0000
scheduled_for:     2026-01-27 14:30:00 +0000
server_created_at: 2025-10-29 11:05:24 +0000
status:            preparing
window:            Tuesdays 14:30 to 18:30 UTC

`heroku data:maintenances:window`

The heroku data:maintenances:window command displays the configured maintenance window for a single Heroku Data add-on. The maintenance window is the day of the week and hours of the day in UTC when a maintenance event automatically triggers. You can change this value with the data:maintenances:window:update command. You can also trigger maintenance before the scheduled time using the data:maintenances:run command.

$ heroku data:maintenances:window DATABASE -a example-app

Fetching maintenance window for DATABASE... done
window:            Tuesdays 14:30 to 18:30 UTC

`heroku data:maintenances:window:update`

The heroku data:maintenances:window:update command changes the configured maintenance window for a single Heroku Data add-on.

If there’s a pending maintenance event scheduled for the add-on, changing the maintenance window changes the scheduled for maintenance time for that add-on.

The maintenance window arguments are in UTC. For example, if you want your maintenance event to run on Monday at 10:00 AM US Pacific time, set your window to “Monday 18:00”.

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

Setting maintenance window for postgresql-octagonal-1234 to Sunday 14:30... done
previous_window:          Tuesdays 14:30 to 18:30 UTC
window:                   Sundays 14:30 to 18:30 UTC

`heroku data:maintenances:wait`

If a pending maintenance is triggered, the heroku data:maintenances:wait command blocks it until the maintenance event completes.

$ heroku data:maintenances:wait DATABASE -a example-app

Waiting for maintenace on DATABASE to complete... maintenance completed

`heroku data:maintenances:schedule`

The heroku data:maintenances:schedule command creates a new pending maintenance event, or updates the scheduled for maintenance time for an existing pending maintenance event. The scheduled for maintenance time is always within a configured maintenance window.

$ heroku data:maintenances:schedule DATABASE -a example-app --weeks 2

Scheduling maintenance for DATABASE... maintenance scheduled
Maintenance for DATABASE scheduled for 2026-03-26 19:00:00 +0000

You can only reschedule the maintenance time within the configured window. You can’t reschedule outside of the deadline or before the current date.

note When using --weeks, a positive number delays the scheduled maintenance time by the specified number of weeks. A negative number advances the scheduled maintenance time by the specified number of weeks. For example, --weeks 3 postpones the scheduled maintenance time for 3 weeks,]. --weeks -2 moves up the scheduled maintenance time by 2 weeks.

`heroku data:maintenances:run`

The heroku data:maintenances:run command triggers a pending maintenance event for a single Heroku Data add-on.

$ heroku data:maintenances:run DATABASE -a example-app -c example-app

Triggering maintenance... maintenance triggered

`heroku data:maintenances:history`

The heroku data:maintenances:history command displays details about the most recent maintenance events for a single Heroku Data add-on.

$ heroku data:maintenances:history DATABASE -a example-app

Fetching maintenance history for DATABASE... done
 Scheduled For             Started At                Completed At              Duration (seconds) Reason              Status    Window
 ───────────────────────── ───────────────────────── ───────────────────────── ────────────────── ─────────────────── ───────── ──────────────────────────
 2026-02-17 20:00:00 +0000 2025-11-17 20:01:15 +0000 2025-11-17 20:03:31 +0000 136                routine_maintenance completed Mondays 20:00 to Tuesdays…
 2026-02-11 22:09:42 +0000 2025-08-11 22:09:43 +0000 2025-08-11 22:09:56 +0000 12                 customer_request    completed Mondays 20:00 to Tuesdays…
 2026-01-28 20:00:00 +0000 2025-07-28 20:00:21 +0000 2025-07-28 20:03:07 +0000 166                routine_maintenance completed Mondays 20:00 to Tuesdays…

Categories