Feat: Create pg:upgrade:prepare command

[nilamuthu]

Work item

This PR creates the pg:upgrade:prepare command. It also moves the pg:upgrade command to be under the upgrade folder in packages/cli/test/unit/commands/pg/upgrade as index.ts.

Please refer to this doc for more information related to pg:upgrade:prepare.

Testing

Check out this branch and run yarn && yarn build

1. Run ./bin/run pg:upgrade:prepare on a Standard-Tier leader DB

nmuthu@nmuthu-ltm8kcc cli % ./bin/run pg:upgrade:prepare DATABASE_URL -a pg-upgrade-test-app
 ›   Warning: Destructive action
 ›   This command prepares the upgrade for postgresql-spherical-07906 to the latest supported PostgreSQL version and schedules to upgrade it during the next available maintenance window.
 ›

To proceed, type pg-upgrade-test-app or re-run this command with --confirm pg-upgrade-test-app: pg-upgrade-test-app
Preparing upgrade on postgresql-spherical-07906... done
Your database is scheduled for upgrade during your next available maintenance window.
Run heroku pg:upgrade:wait to track its status.
You can also run this upgrade manually before the maintenance window with heroku pg:upgrade:wait. You can only run the upgrade after it's fully prepared, which can take up to a day.

2. Run ./bin/run pg:upgrade:prepare on a Standard-Tier DB with version flag

nmuthu@nmuthu-ltm8kcc cli % ./bin/run pg:upgrade:prepare DATABASE_URL -a pg-upgrade-test-app --version 15
 ›   Warning: Destructive action
 ›   This command prepares the upgrade for postgresql-spherical-07906 to PostgreSQL version 15 and schedules to upgrade it during the next available maintenance window.
 ›

To proceed, type pg-upgrade-test-app or re-run this command with --confirm pg-upgrade-test-app: pg-upgrade-test-app
Preparing upgrade on postgresql-spherical-07906... done
Your database is scheduled for upgrade during your next available maintenance window.
Run heroku pg:upgrade:wait to track its status.
You can also run this upgrade manually before the maintenance window with heroku pg:upgrade:wait. You can only run the upgrade after it's fully prepared, which can take up to a day.

3. Run ./bin/run pg:upgrade:prepare on a follower DB

nmuthu@nmuthu-ltm8kcc cli % ./bin/run pg:upgrade:prepare HEROKU_POSTGRESQL_TEAL_URL -a pg-upgrade-test-app
 ›   Error: You can only use heroku pg:upgrade:prepare on Standard-tier and higher leader databases. For follower databases, use heroku pg:upgrade:run instead.

4. Run ./bin/run pg:upgrade:prepare on an Essential tier DB

 nmuthu@nmuthu-ltm8kcc cli % ./bin/run pg:upgrade:prepare HEROKU_POSTGRESQL_IVORY_URL -a pg-upgrade-test-app --version 15
 ›   Error: You can only use heroku pg:upgrade:prepare on Standard-tier and higher leader databases. For Essential-tier databases, use heroku pg:upgrade:run instead.

5. Run ./bin/run pg:upgrade:prepare on a Standard-Tier DB that has an upgrade already scheduled

nmuthu@nmuthu-ltm8kcc cli % ./bin/run pg:upgrade:prepare DATABASE_URL -a pg-upgrade-test-app
 ›   Warning: Destructive action
 ›   This command prepares the upgrade for postgresql-spherical-07906 to PostgreSQL version and schedules to upgrade it during the next available maintenance window.
 ›

To proceed, type pg-upgrade-test-app or re-run this command with --confirm pg-upgrade-test-app: pg-upgrade-test-app
Preparing upgrade on postgresql-spherical-07906... !
 ›   Error: database has an upgrade already scheduled, please check `pg:upgrade:wait` for more information on the status of your upgrade.
 ›
 ›   Error ID: unprocessable_entity

6. heroku help pg:upgrade:prepare

nmuthu@nmuthu-ltm8kcc cli % ./bin/run help pg:upgrade:prepare
Prepares the upgrade for Standard-tier and higher leader databases and schedules it for the next available maintenance window. Use heroku pg:upgrade:run for Essential-tier or follower databases instead.

USAGE
  $ heroku pg:upgrade:prepare [DATABASE] -a <value> [-c <value>] [-v <value>]

ARGUMENTS
  DATABASE  config var containing the connection string, unique name, ID, or alias of the database. To access another app's database, prepend the app name to the config var or alias with
            `APP_NAME::` . If omitted, we use DATABASE_URL.

FLAGS
  -a, --app=<value>      (required) app to run command against
  -c, --confirm=<value>
  -v, --version=<value>  PostgreSQL version to upgrade to

DESCRIPTION
  Prepares the upgrade for Standard-tier and higher leader databases and schedules it for the next available maintenance window. Use heroku pg:upgrade:run for Essential-tier or follower
  databases instead.

[zwhitfield3]

This is great work @nilamuthu! I have a few comments, but this is a strong first pass!

I'll organize my feedback based on the numbering from your testing sections so it's easier to follow along.

Test 1 - Command works with versions lower than latest. I received a 500 status code reading:

❯ ./bin/run pg:upgrade:prepare HEROKU_POSTGRESQL_AQUA_URL -a pg-upgrade-test-ap
p
 ›   Warning: Destructive action
 ›   This command prepares the upgrade for postgresql-concentric-29006 to the
 ›   latest supported PostgreSQL version and schedules to upgrade it during
 ›   the next available maintenance window.
 ›

To proceed, type pg-upgrade-test-app or re-run this command with --confirm pg-upgrade-test-app: pg-upgrade-test-app
Preparing upgrade on postgresql-concentric-29006... !
 ›   Error: Internal server error.
 ›
 ›   Error ID: internal_server_error

I don't know if that's because the version provisioned is already on latest, but we should surface better error messaging here if it is in fact due to the version conflict.

• On successful command executions, there is a typo with which command to run to manually upgrade after the db is prepared/ready. We want to change heroku pg:upgrade:wait to heroku pg:upgrade:run.

❯ ./bin/run pg:upgrade:prepare HEROKU_POSTGRESQL_OLIVE -a pg-upgrade-test-app --version 15
›   Warning: Destructive action
›   This command prepares the upgrade for postgresql-curly-47326 to
›   PostgreSQL version 15 and schedules to upgrade it during the next
›   available maintenance window.
›

To proceed, type pg-upgrade-test-app or re-run this command with --confirm pg-upgrade-test-app: pg-upgrade-test-app
Preparing upgrade on postgresql-curly-47326... done
Your database is scheduled for upgrade during your next available maintenance window.
Run heroku pg:upgrade:wait to track its status.
You can also run this upgrade manually before the maintenance window with heroku pg:upgrade:wait. You can only run the upgrade after it's fully prepared, which can take up to a day.

Test 2 - Same comments as Test 1
Test 3 - We should update the error message command color for heroku pg:upgrade:run to the blue cmd color. Currently, it's fragmented between white and blue. See below:

Test 4 - Same comments as Test 3
Test 5 - The command successfully errors based on business logic, but only for commands that don't include the --version flag. When using the --version flag, it persists the expected message of successful queuing of the db for preparation.

• We should add the color.cmd() util to pg:upgrade:wait in the error messaging instead of backticks. See current output below:

❯ ./bin/run pg:upgrade:prepare DATABASE -a pg-upgrade-test-app
 ›   Warning: Destructive action
 ›   This command prepares the upgrade for postgresql-spherical-07906 to the
 ›   latest supported PostgreSQL version and schedules to upgrade it during
 ›   the next available maintenance window.
 ›

To proceed, type pg-upgrade-test-app or re-run this command with --confirm pg-upgrade-test-app: pg-upgrade-test-app
Preparing upgrade on postgresql-spherical-07906... !
 ›   Error: database has an upgrade already scheduled, please check
 ›   `pg:upgrade:wait` for more information on the status of your upgrade.
 ›
 ›   Error ID: unprocessable_entity

Test 6 - ✅

[zwhitfield3]

We also want to make sure this branch is pointed to the pg-upgrade-enhancements feature branch.

[nilamuthu]

Thanks @zwhitfield3 for the helpful feedback! For Test 1/2 we actually identified that issue on our end. We have a PR almost ready to merge that will fix this error!

For test 5, this may because there is some time between the customer running this command and the upgrade being scheduled. Until the actual upgrade is scheduled the customer is actually allowed to re-run pg:upgrade:prepare as many times they like. Only after the upgrade is scheduled as a maintenance will the error surface. But let me try again and make sure its not specifically because of the version flag!

I'll make sure to address the rest of your comments in this PR and make this branch point to the feature branch! Thanks again!

[zwhitfield3]

Fantastic work here @nilamuthu!