From 32578df65f6d102eb637e059fc4f87aa23e94ce4 Mon Sep 17 00:00:00 2001 From: Joel Andrews Date: Mon, 15 Aug 2022 18:27:24 -0700 Subject: [PATCH] Preparation for 1.0.0 release Updates `package.json`, the README and the CHANGELOG in preparation for the release of v1.0.0 --- CHANGELOG.md | 2 +- README.md | 190 +++++++++++++++++++++++++++++++++++++++++---------- package.json | 2 +- 3 files changed, 157 insertions(+), 37 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 75a902b..08455e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # Change Log This project adheres to [Semantic Versioning](http://semver.org/). All notable changes will be documented in this file. -## [Unreleased](https://github.com/OldSneerJaw/borealis-pg-cli/compare/v0.9.0...HEAD) +## [1.0.0](https://github.com/OldSneerJaw/borealis-pg-cli/compare/v0.9.0...v1.0.0) - Adds the `borealis-pg:info` (alias: `borealis-pg`) command to retrieve details about an add-on DB - Adds the `borealis-pg:users` command to retrieve a list of active DB users for an add-on - The `--addon` option is no longer required when there is only one Borealis Isolated Postgres add-on attached to an app diff --git a/README.md b/README.md index 05656ab..958eb2b 100644 --- a/README.md +++ b/README.md @@ -22,12 +22,31 @@ $ heroku plugins:install borealis-pg-cli # Commands +* [`heroku borealis-pg`](#heroku-borealis-pg) * [`heroku borealis-pg:extensions`](#heroku-borealis-pgextensions) * [`heroku borealis-pg:extensions:install PG_EXTENSION`](#heroku-borealis-pgextensionsinstall-pg_extension) * [`heroku borealis-pg:extensions:remove PG_EXTENSION`](#heroku-borealis-pgextensionsremove-pg_extension) +* [`heroku borealis-pg:info`](#heroku-borealis-pginfo) * [`heroku borealis-pg:psql`](#heroku-borealis-pgpsql) * [`heroku borealis-pg:run`](#heroku-borealis-pgrun) * [`heroku borealis-pg:tunnel`](#heroku-borealis-pgtunnel) +* [`heroku borealis-pg:users`](#heroku-borealis-pgusers) +* [`heroku borealis-pg:users:reset`](#heroku-borealis-pgusersreset) + +## `heroku borealis-pg` + +shows information about a Borealis Isolated Postgres add-on database + +``` +USAGE + $ heroku borealis-pg + +OPTIONS + -a, --app=app app to which the add-on is attached + -o, --addon=addon name or ID of an add-on or one of its attachments +``` + +_See code: [src/commands/borealis-pg/index.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/index.ts)_ ## `heroku borealis-pg:extensions` @@ -39,14 +58,14 @@ USAGE OPTIONS -a, --app=app app to which the add-on is attached - -o, --addon=addon (required) name or ID of an add-on or one of its attachments + -o, --addon=addon name or ID of an add-on or one of its attachments ``` -_See code: [src/commands/borealis-pg/extensions/index.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v0.9.0/src/commands/borealis-pg/extensions/index.ts)_ +_See code: [src/commands/borealis-pg/extensions/index.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/extensions/index.ts)_ ## `heroku borealis-pg:extensions:install PG_EXTENSION` -installs a Postgres extension on a Borealis Isolated Postgres add-on +installs a Postgres extension on a Borealis Isolated Postgres add-on database ``` USAGE @@ -57,7 +76,7 @@ ARGUMENTS OPTIONS -a, --app=app app to which the add-on is attached - -o, --addon=addon (required) name or ID of an add-on or one of its attachments + -o, --addon=addon name or ID of an add-on or one of its attachments -r, --recursive automatically install Postgres extension dependencies recursively -s, --suppress-conflict suppress nonzero exit code when an extension is already installed @@ -71,13 +90,18 @@ DESCRIPTION Details of all supported extensions can be found here: https://www.borealis-data.com/pg-extensions-support.html + +EXAMPLES + $ heroku borealis-pg:extensions:install --recursive --app sushi hstore_plperl + $ heroku borealis-pg:extensions:install --app sushi --addon BOREALIS_PG_MAROON bloom + $ heroku borealis-pg:extensions:install --suppress-conflict --addon borealis-pg-hex-12345 pg_trgm ``` -_See code: [src/commands/borealis-pg/extensions/install.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v0.9.0/src/commands/borealis-pg/extensions/install.ts)_ +_See code: [src/commands/borealis-pg/extensions/install.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/extensions/install.ts)_ ## `heroku borealis-pg:extensions:remove PG_EXTENSION` -removes a Postgres extension from a Borealis Isolated Postgres add-on +removes a Postgres extension from a Borealis Isolated Postgres add-on database ``` USAGE @@ -89,11 +113,31 @@ ARGUMENTS OPTIONS -a, --app=app app to which the add-on is attached -c, --confirm=confirm bypass the prompt for confirmation by specifying the name of the extension - -o, --addon=addon (required) name or ID of an add-on or one of its attachments + -o, --addon=addon name or ID of an add-on or one of its attachments -s, --suppress-missing suppress nonzero exit code when an extension is not installed + +EXAMPLES + $ heroku borealis-pg:extensions:remove --suppress-missing --app sushi postgis + $ heroku borealis-pg:extensions:remove --app sushi --addon BOREALIS_PG_MAROON btree_gist + $ heroku borealis-pg:extensions:remove --confirm uuid-ossp --addon borealis-pg-hex-12345 uuid-ossp ``` -_See code: [src/commands/borealis-pg/extensions/remove.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v0.9.0/src/commands/borealis-pg/extensions/remove.ts)_ +_See code: [src/commands/borealis-pg/extensions/remove.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/extensions/remove.ts)_ + +## `heroku borealis-pg:info` + +shows information about a Borealis Isolated Postgres add-on database + +``` +USAGE + $ heroku borealis-pg:info + +OPTIONS + -a, --app=app app to which the add-on is attached + -o, --addon=addon name or ID of an add-on or one of its attachments +``` + +_See code: [src/commands/borealis-pg/info.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/info.ts)_ ## `heroku borealis-pg:psql` @@ -106,7 +150,7 @@ USAGE OPTIONS -a, --app=app app to which the add-on is attached -b, --binary-path=binary-path custom path to a psql binary - -o, --addon=addon (required) name or ID of an add-on or one of its attachments + -o, --addon=addon name or ID of an add-on or one of its attachments -p, --port=port [default: 5432] local port number for the secure tunnel to the add-on Postgres server -w, --write-access allow write access to the add-on Postgres database @@ -116,8 +160,15 @@ DESCRIPTION installed on the local machine; generally, psql is installed along with PostgreSQL (https://www.postgresql.org/download/). - By default, read-only user credentials are used to connect to the add-on - database; to enable read and write access, supply the --write-access option. + The psql session will be initiated as a database user role that is + specifically tied to the current Heroku user account. By default the user role + allows read-only access to the add-on database; to enable read and write + access, supply the --write-access option. + + Note that any tables, indexes, views or other objects that are created when + connected as a personal user role will be owned by that user role rather than + the application database user role unless ownership is explicitly reassigned + afterward (for example, by using the REASSIGN OWNED command). To override the path to the psql binary, supply the --binary-path option. @@ -127,12 +178,12 @@ DESCRIPTION pgAdmin). EXAMPLES + $ heroku borealis-pg:psql --app sushi --binary-path /path/to/psql + $ heroku borealis-pg:psql --app sushi --addon BOREALIS_PG_MAROON --write-access $ heroku borealis-pg:psql --addon borealis-pg-hex-12345 - $ heroku borealis-pg:psql --app sushi --addon DATABASE --binary-path /path/to/psql - $ heroku borealis-pg:psql --app sushi --addon DATABASE_URL --write-access ``` -_See code: [src/commands/borealis-pg/psql.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v0.9.0/src/commands/borealis-pg/psql.ts)_ +_See code: [src/commands/borealis-pg/psql.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/psql.ts)_ ## `heroku borealis-pg:run` @@ -148,7 +199,7 @@ OPTIONS -e, --shell-cmd=shell-cmd shell command to execute when the secure tunnel is established -f, --format=(table|csv|json|yaml) [default: table] output format for database command results -i, --db-cmd-file=db-cmd-file UTF-8 file containing database command(s) to execute over the secure tunnel - -o, --addon=addon (required) name or ID of an add-on or one of its attachments + -o, --addon=addon name or ID of an add-on or one of its attachments -p, --port=port [default: 5432] local port number for the secure tunnel to the add-on Postgres server @@ -164,16 +215,18 @@ DESCRIPTION immediately closes the tunnel. A command can take the form of a database command or a shell command. In either - case, it is executed using the Heroku application's dedicated database user by - default, but it can be made to execute as a database user that is specifically - tied to the current Heroku user account via the --personal-user option instead. - Note that any tables, indexes, views or other objects that are created when - connected as a personal user will be owned by that user rather than the - application database user unless ownership is explicitly reassigned. - - By default, the user credentials that are provided allow read-only access to - the add-on database; to enable read and write access, supply the --write-access - option. + case, it is executed using the Heroku application's dedicated database user + role by default, but it can be made to execute as a database user role that is + specifically tied to the current Heroku user account via the --personal-user + option instead. Note that any tables, indexes, views or other objects that are + created when connected as a personal user role will be owned by that user role + rather than the Heroku application user role unless ownership is explicitly + reassigned afterward (for example, by using the REASSIGN OWNED command). + + Regardless of whether running as the Heroku application's database user role + or as a personal user role, the command will have read-only access to the + add-on database by default; to enable read and write access, supply the + --write-access option. Database commands are raw statements (e.g. SQL, PL/pgSQL) that are sent over the secure tunnel to the add-on Postgres database to be executed verbatim, with @@ -197,12 +250,12 @@ DESCRIPTION like pgAdmin). EXAMPLES + $ heroku borealis-pg:run --app sushi --db-cmd 'SELECT * FROM hello_greeting' --format csv + $ heroku borealis-pg:run --app sushi --addon BOREALIS_PG_MAROON --db-cmd-file ~/scripts/example.sql --personal-user $ heroku borealis-pg:run --addon borealis-pg-hex-12345 --shell-cmd './manage.py migrate' --write-access - $ heroku borealis-pg:run --app sushi --addon DATABASE --db-cmd 'SELECT * FROM hello_greeting' --format csv - $ heroku borealis-pg:run --app sushi --addon DATABASE_URL --db-cmd-file ~/scripts/example.sql --personal-user ``` -_See code: [src/commands/borealis-pg/run.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v0.9.0/src/commands/borealis-pg/run.ts)_ +_See code: [src/commands/borealis-pg/run.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/run.ts)_ ## `heroku borealis-pg:tunnel` @@ -214,7 +267,7 @@ USAGE OPTIONS -a, --app=app app to which the add-on is attached - -o, --addon=addon (required) name or ID of an add-on or one of its attachments + -o, --addon=addon name or ID of an add-on or one of its attachments -p, --port=port [default: 5432] local port number for the secure tunnel to the add-on Postgres server -w, --write-access allow write access to the add-on Postgres database @@ -223,18 +276,85 @@ DESCRIPTION Postgres database that is, by design, otherwise inaccessible from outside of its virtual private cloud. Once a tunnel is established, use a tool such as psql or pgAdmin and the provided user credentials to interact with the add-on - database. By default, the user credentials that are provided allow read-only - access to the add-on database; to enable read and write access, supply the - --write-access option. + database. + + The credentials that will be provided belong to a database user role that is + specifically tied to the current Heroku user account. By default the user role + allows read-only access to the add-on database; to enable read and write + access, supply the --write-access option. + + Note that any tables, indexes, views or other objects that are created when + connected as a personal user role will be owned by that user role rather than + the application database user role unless ownership is explicitly reassigned + afterward (for example, by using the REASSIGN OWNED command). See also the borealis-pg:run command to execute a noninteractive script or the borealis-pg:psql command to launch an interactive psql session directly. EXAMPLES + $ heroku borealis-pg:tunnel --app sushi --port 54321 + $ heroku borealis-pg:tunnel --app sushi --addon BOREALIS_PG_MAROON $ heroku borealis-pg:tunnel --addon borealis-pg-hex-12345 --write-access - $ heroku borealis-pg:tunnel --app sushi --addon DATABASE --port 54321 - $ heroku borealis-pg:tunnel --app sushi --addon DATABASE_URL ``` -_See code: [src/commands/borealis-pg/tunnel.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v0.9.0/src/commands/borealis-pg/tunnel.ts)_ +_See code: [src/commands/borealis-pg/tunnel.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/tunnel.ts)_ + +## `heroku borealis-pg:users` + +lists database user roles for a Borealis Isolated Postgres add-on + +``` +USAGE + $ heroku borealis-pg:users + +OPTIONS + -a, --app=app app to which the add-on is attached + -o, --addon=addon name or ID of an add-on or one of its attachments + +DESCRIPTION + Note that this command's output only includes active add-on database user + roles. The Heroku application's database user roles are always present. + Personal read-only and read/write database user roles are automatically + created or reactivated for any user that has permission to access any app the + add-on is attached to when that user runs one of the borealis-pg:psql or + borealis-pg:tunnel commands (or borealis-pg:run with the --personal-user + option). All personal database user roles are automatically deactivated when + the add-on's database user credentials are reset (for example, via the + borealis-pg:users:reset command). +``` + +_See code: [src/commands/borealis-pg/users/index.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/users/index.ts)_ + +## `heroku borealis-pg:users:reset` + +resets all database credentials for a Borealis Isolated Postgres add-on + +``` +USAGE + $ heroku borealis-pg:users:reset + +OPTIONS + -a, --app=app app to which the add-on is attached + -o, --addon=addon name or ID of an add-on or one of its attachments + +DESCRIPTION + The Heroku application's database user roles will be assigned new, random + usernames and passwords and the application's config vars will be updated + imminently with the new credentials. To ensure there is no application + downtime, the old application database credentials will continue to remain + valid for a short time after this operation is completed, after which they + will be disabled. + + Any active personal database user roles will also be deactivated by this + operation, which means that anyone that is currently connected to the database + with a personal user role will be immediately disconnected. Rest assured that + any tables, indexes, views or other objects that are are owned by a personal + user role will not be affected (the user roles and the objects they own will + continue to exist). A personal user role that has been deactivated will be + automatically reactivated when the affected user runs one of the + borealis-pg:psql or borealis-pg:tunnel commands (or borealis-pg:run with the + --personal-user option). +``` + +_See code: [src/commands/borealis-pg/users/reset.ts](https://github.com/OldSneerJaw/borealis-pg-cli/blob/v1.0.0/src/commands/borealis-pg/users/reset.ts)_ diff --git a/package.json b/package.json index e019de2..84de8a6 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "borealis-pg-cli", "description": "CLI for advanced interactions with Borealis Isolated Postgres add-ons", - "version": "0.9.0", + "version": "1.0.0", "author": "Borealis Data Solutions", "bugs": "https://github.com/OldSneerJaw/borealis-pg-cli/issues", "dependencies": {