refactor: first pass at adding pg commands from pg-extras plugin to cli PR 1 of 3

[jdodson]

Summary

We need to move the commands from the pg-extras plugin to the core CLI, which will require us to update the commands to use oclif/core v4 and heroku-cli-command v12.

This is PR 1 of 3 to accomplish this task and we will be merging these PRs in feature/migrate_pg_extras_to_cli

Things done:

• Add postgres words to cspell dictionary

This work item covers migrating the following 6 pg-extras commands to the core CLI:

• pg/cache-hit.ts
• pg/calls.ts
• pg/extensions.ts
• pg/fdwsql.ts
• pg/index-size.ts
• pg/index-usage.ts

ALSO did:

• AGENTS.md requires usage examples to the migrated pg-extras commands so I added those

Type of Change

Breaking Changes (major semver update)

• Add a ! after your change type to denote a change that breaks current behavior

Feature Additions (minor semver update)

• feat: Introduces a new feature to the codebase

Patch Updates (patch semver update)

• fix: Bug fix
• deps: Dependency upgrade
• revert: Revert a previous commit
• chore: Change that does not affect production code
• refactor: Refactoring existing code without changing behavior
• test: Add/update/remove tests

Testing

Notes:

The --help changes (should be limited to --prompt and GLOBAL FLAGS additions that came with cli upgrades) ALSO examples as the cli requires:

diff <(./bin/run pg:cache-hit --help) <(heroku pg:cache-hit --help)
diff <(./bin/run pg:calls --help) <(heroku pg:calls --help)
diff <(./bin/run pg:extensions --help) <(heroku pg:extensions --help)
diff <(./bin/run pg:fdwsql --help) <(heroku pg:fdwsql --help)
diff <(./bin/run pg:index-size --help) <(heroku pg:index-size --help)
diff <(./bin/run pg:index-usage --help) <(heroku pg:index-usage --help)

New Command Testing Steps:

1. Show index and table hit rate (two rows: index hit rate and table hit rate, each with a
   ratio)

./bin/run pg:cache-hit -a $APP

2. Confirm the hidden underscore alias produces identical output to step 1

./bin/run pg:cache_hit -a $APP

3. Show index usage (relname | percent_of_times_index_used | rows_in_table, ordered by rows
   descending; tables with no scans show Insufficient data)

./bin/run pg:index-usage -a $APP

4. Confirm the hidden underscore alias produces identical output to step 3

./bin/run pg:index_usage -a $APP

5. Show index sizes (name | size for each index, descending by size, e.g. 5196 MB)

./bin/run pg:index-size -a $APP

6. Confirm the hidden underscore alias produces identical output to step 5

./bin/run pg:index_size -a $APP

7. List available and installed extensions (name | version | schema | description, e.g. a
   plpgsql row)

./bin/run pg:extensions -a $APP

8. Show the 10 highest-frequency queries (total_exec_time | prop_exec_time | ncalls | sync_io_time | query, ordered by calls DESC; requires pg_stat_statements) - THIS SEEMS BUGGED

./bin/run pg:calls -a $APP

9. Same as step 8 but with the query column truncated to 40 characters (look for … at the cut point) - THIS SEEMS BUGGED

./bin/run pg:calls --truncate -a $APP

10. Generate foreign data wrapper SQL (output starts with CREATE EXTENSION IF NOT EXISTS postgres_fdw;, DROP SERVER IF EXISTS example_prefix_db;, CREATE SERVER example_prefix_db…, CREATE USER MAPPING…, then one CREATE FOREIGN TABLE… line per table/view; psql noise like (N rows) is filtered out)

./bin/run pg:fdwsql example_prefix -a $APP

11. Confirm the optional database arg resolves a specific database instead of the default

./bin/run pg:cache-hit DATABASE_URL -a $APP
./bin/run pg:fdwsql example_prefix DATABASE_URL -a $APP

Screenshots (if applicable)

Related Issues

GUS work item: https://gus.lightning.force.com/lightning/r/ADM_Work__c/a07EE00002Yzk1lYAB/view