Data Maintenance CLI Plugin Commands

Last updated May 25, 2023

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:

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

Feedback

Log in to submit feedback.