Data Maintenance CLI Plugin Commands

Last updated October 11, 2024

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 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, these commands enable you to:

For more info on the maintenance process, see Heroku Key-Value Store 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 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.

Installation

You must install the Heroku CLI before adding the Data Maintenance CLI plugin.

After you’ve installed the Heroku CLI, install the 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 pending maintenance if one exists, or the most recent completed maintenance event. 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 pending maintenance if one exists, or the most recent completed maintenance event. 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 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.

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 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”.

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 is triggered, this command blocks it until the maintenance event 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 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.

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

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

Triggers a pending maintenance event 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
  -c, --confirm app-name         confirms running maintenance on the app 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 --confirm example-app
  $ 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.