Data Maintenance CLI Commands

Last updated December 11, 2020

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:

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

Feedback

Log in to submit feedback.