Data Maintenance CLI Commands
Last updated 11 December 2020
Table of Contents
Data Maintenance CLI Commands
Overview
The CLI commands provided by the plugin help you to manage planned maintenance for Heroku Data add-ons. For Heroku Postgres and Heroku Redis, these commands enable you to:
- Review maintenance windows
- Change maintenance windows
- Schedule a maintenance to be run
- Re-schedule 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
The usage of these maintenance-related commands is optional. Maintenances on Heroku Data add-ons will be scheduled and run automatically without any intervention. If maintenance impacts your application negatively, or you’d simply like more control over the process, these commands can be used to exercise some control over when and how planned maintenances are run.
For more information, see these related Dev Center articles:
These commands include and expand on the functionality of the older pg:maintenance
and redis:maintenance
commands. Those commands will eventually be deprecated in favor of the commands in this plugin.
Maintenances for hobby add-ons are performed as-needed and without notice. The commands below are relevant only for add-ons on standard, premium, private, and shield plans for Heroku Postgres and Heroku Redis.
For Heroku Kafka, we provide limited support for viewing details about in-progress and historical maintenances on your clusters via data:maintenances:info and data:maintenances:history
Installation
These commands are not yet part of the core Heroku CLI. To use these commands you will need to install the plugin first:
# Install the plugin
heroku plugins:install data-maintenance
# List arguments and sub-commands
heroku help data:maintenances
Commands
heroku data:maintenances
Lists the most recent maintenance event in our system for each Heroku Data add-on for an app. This will either be a pending maintenance if one exists, or the most recent completed maintenance. Pending maintenance events will include a “required by” and a “scheduled for” timestamp.
list maintenances for an app's data add-ons
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 production-app
$ heroku data:maintenances --app production-app --json
heroku data:maintenances:info
Displays details of the most recent maintenance event in our system for a single Heroku Data add-on. This will either be a pending maintenance if one exists, or the most recent completed maintenance. Pending maintenance events will include a “required by” and a “scheduled for” timestamp.
display details of the most recent maintenance for an add-on
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 test-app
heroku data:maintenances:window
Displays the configured maintenance window for a single Heroku Data add-on. The maintenance window is the day of week and hours of the day in which we will automatically trigger a maintenance procedure. You can change this value with the data:maintenances:window:update
command. You may also trigger the maintenance procedure before the scheduled time using the data:maintenances:run
command.
describe the maintenance window on an add-on
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 production-app
COMMANDS
data:maintenances:window:update update maintenance window on an add-on
heroku data:maintenances:window:update
Changes the configured maintenance window for a single Heroku Data add-on.
If there is a pending maintenance scheduled for the add-on, changing the maintenance window will change the scheduled maintenance time for that add-on.
The maintenance window arguments are always assumed to be in UTC. E.g., if you want your maintenance to run on Monday at 10:00AM US Pacific time, you would set your window to “Monday 18:00”.
update maintenance window on an add-on
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 production-app
heroku data:maintenances:wait
If a pending maintenance has been triggered, this command will block until the maintenance has been completed.
blocks until the maintenance process has completed
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 production-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 will always be within a configured maintenance window.
schedule or re-schedule maintenance for an add-on
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 test-app
heroku data:maintenances:run
Triggers a pending maintenance for a single Heroku Data add-on.
triggers a scheduled maintenance for a 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 production-app
heroku data:maintenances:history
Displays information about the most recent maintenance events for a single Heroku Data add-on.
show details of the most recent maintenances for an 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 production-app