Data Maintenance CLI Plugin Commands
Last updated May 25, 2023
Table of Contents
These commands aren’t part of the base Heroku CLI. See Installation for details.
Overview
The plugin’s CLI commands help you manage planned maintenance for Heroku Data add-ons. Using these maintenance-related commands is optional. Heroku schedules and runs maintenances on Heroku Data add-ons automatically without any intervention.
Maintenances for Essential-tier databases are performed as needed and without notice. The following commands are relevant only for add-ons on Standard, Premium, Private, and Shield plans for Heroku Postgres and Heroku Data for Redis.
If you want more control over the maintenance process, use these commands to exercise some control over when and how planned maintenances are run.
For Heroku Postgres and Heroku Data for Redis, these commands enable you to:
- Review maintenance windows
- Change maintenance windows
- Schedule a maintenance to be run
- Reschedule an existing maintenance
- Trigger a maintenance
- View details of a planned maintenances
- Review history of planned maintenances
- Wait for a triggered maintenance to complete
- Test maintenance impact on a staging app
For more info on maintenances, see Heroku Data for Redis Maintenance and Heroku Postgres Maintenance. For info on CLI plugins in general, see Using CLI Plugins.
These commands include and expand on the functionality of the older pg:maintenance
and redis:maintenance
commands. Heroku plans to deprecate those commands in favor of the commands in this plugin.
Data Maintenance CLI Plugin and Apache Kafka for Heroku
For Apache Kafka for Heroku, the CLI plugin provides limited support for viewing details about in-progress and historical maintenances on your clusters. The data:maintenances:info and data:maintenances:history commands are available for your Kafka add-ons. See Robust Kafka for more info about Kafka maintenances.
Installation
You must have the Heroku CLI installed before adding the Data Maintenance CLI plugin. See Heroku CLI for instructions.
If you have the Heroku CLI installed, install the Data Maintenance CLI plugin with:
# Install the plugin
heroku plugins:install @heroku-cli/plugin-data-maintenance
# List arguments and sub-commands
heroku help data:maintenances
Commands
heroku data:maintenances
Lists the most recent maintenance event for each Heroku Data add-on for an app. This event is either a pending maintenance if one exists, or the most recent completed maintenance. Pending maintenance events include a “required by” and a “scheduled for” timestamp.
USAGE
$ heroku data:maintenances
OPTIONS
-a, --app=app (required) app to list add-on maintenances for
-j, --json output result in json
-r, --remote=remote git remote of app to use
-x, --extended show extra columns
--columns=columns only show provided columns (comma-separated)
--csv output is csv format
--filter=filter filter property by partial string matching, ex: name=foo
--no-header hide table header from output
--no-truncate do not truncate output to fit screen
--sort=sort property to sort by (prepend '-' for descending)
EXAMPLES
$ heroku data:maintenances --app example-app
$ heroku data:maintenances --app example-app --json
heroku data:maintenances:info
Displays details of the most recent maintenance event for a single Heroku Data add-on. This event is either a pending maintenance if one exists, or the most recent completed maintenance. Pending maintenance events include a “required by” and a “scheduled for” timestamp.
USAGE
$ heroku data:maintenances:info ADDON
ARGUMENTS
ADDON data add-on to show maintenance for
OPTIONS
-a, --app=app app to list addon maintenances for
-j, --json output result in json
-r, --remote=remote git remote of app to use
EXAMPLES
$ heroku data:maintenances:info postgresql-sinuous-83720
$ heroku data:maintenances:info postgresql-sinuous-83720 --json
$ heroku data:maintenances:info DATABASE --app example-app
heroku data:maintenances:window
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 during which a maintenance procedure automatically triggers. You can change this value with the data:maintenances:window:update
command. You can also trigger the maintenance procedure before the scheduled time using the data:maintenances:run
command.
USAGE
$ heroku data:maintenances:window ADDON
ARGUMENTS
ADDON add-on to show window for
OPTIONS
-a, --app=app app to run command against
-j, --json output result in json
-r, --remote=remote git remote of app to use
EXAMPLES
$ heroku data:maintenances:window postgresql-sinuous-92834
$ heroku data:maintenances:window DATABASE --app example-app
heroku data:maintenances:window:update
Changes the configured maintenance window for a single Heroku Data add-on.
If there’s a pending maintenance scheduled for the add-on, changing the maintenance window changes the scheduled maintenance time for that add-on.
The maintenance window arguments are in UTC. For example, if you want your maintenance to run on Monday at 10:00 AM US Pacific time, set your window to “Monday 18:00”.
USAGE
$ heroku data:maintenances:window:update ADDON DAY_OF_WEEK TIME_OF_DAY
ARGUMENTS
ADDON add-on to change window for
DAY_OF_WEEK UTC maintenance window day of the week
TIME_OF_DAY UTC maintenance window time of day
OPTIONS
-a, --app=app app to run command against
-j, --json output result in json
-r, --remote=remote git remote of app to use
EXAMPLES
$ heroku data:maintenances:window:update postgresql-sinuous-92834 sunday 13:30
$ heroku data:maintenances:window:update postgresql-sinuous-92834 sunday 1:30PM
$ heroku data:maintenances:window:update DATABASE sunday 1:30PM --app example-app
heroku data:maintenances:wait
If a pending maintenance triggered, this command blocks until the maintenance completes.
USAGE
$ heroku data:maintenances:wait ADDON
ARGUMENTS
ADDON data add-on
OPTIONS
-a, --app=app app to run command against
-r, --remote=remote git remote of app to use
EXAMPLES
$ heroku data:maintenances:wait postgresql-sinuous-83720
$ heroku data:maintenances:wait DATABASE --app example-app
heroku data:maintenances:schedule
Creates a new pending maintenance, or updates the scheduled maintenance time for an existing pending maintenance. The scheduled maintenance time is always within a configured maintenance window.
USAGE
$ heroku data:maintenances:schedule ADDON
ARGUMENTS
ADDON addon to schedule or re-schedule maintenance for
OPTIONS
-a, --app=app app to run command against
-r, --remote=remote git remote of app to use
--weeks=weeks [default: 2] the number of weeks to delay maintenance for
EXAMPLES
$ heroku data:maintenances:schedule postgresql-sinuous-83910
$ heroku data:maintenances:schedule postgresql-sinuous-83910 --weeks 3
$ heroku data:maintenances:schedule postgresql-sinuous-83910 --weeks -2
$ heroku data:maintenances:schedule HEROKU_POSTGRESQL_RED --app example-app
heroku data:maintenances:run
Triggers a pending maintenance for a single Heroku Data add-on.
USAGE
$ heroku data:maintenances:run ADDON
ARGUMENTS
ADDON data add-on
OPTIONS
-a, --app=app app to run command against
-f, --force start maintenance without entering application maintenance mode
-r, --remote=remote git remote of app to use
-w, --wait wait for maintenance to complete before exiting
EXAMPLES
$ heroku data:maintenances:run postgresql-sinuous-92834
$ heroku data:maintenances:run postgresql-sinuous-92834 --force
$ heroku data:maintenances:run postgresql-sinuous-92834 --wait
$ heroku data:maintenances:run DATABASE --app example-app
heroku data:maintenances:history
Displays details about the most recent maintenance events for a single Heroku Data add-on.
USAGE
$ heroku data:maintenances:history ADDON
ARGUMENTS
ADDON data add-on
OPTIONS
-a, --app=app app to run command against
-j, --json show result formatted in json
-n, --num=num [default: 5] number of maintenances to show (maximum is 20)
-r, --remote=remote git remote of app to use
-x, --extended show extra columns
--columns=columns only show provided columns (comma-separated)
--csv output is csv format
--filter=filter filter property by partial string matching, ex: name=foo
--no-header hide table header from output
--no-truncate do not truncate output to fit screen
--sort=sort property to sort by (prepend '-' for descending)
EXAMPLES
$ heroku data:maintenances:history postgresql-sinuous-92834
$ heroku data:maintenances:history postgresql-sinuous-92834 --num 10
$ heroku data:maintenances:history postgresql-sinuous-92834 --json
$ heroku data:maintenances:history DATABASE --app example-app