Merge pull request #61 from OldSneerJaw/release-1.0.0

Preparation for 1.0.0 release
OldSneerJaw · Aug 16, 2022 · 00f0e59 · 00f0e59
2 parents 944b4f9 + 32578df
commit 00f0e59
Show file tree

Hide file tree

Showing 3 changed files with 157 additions and 37 deletions.
diff --git 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
@@ -22,12 +22,31 @@ $ heroku plugins:install borealis-pg-cli
 
 # Commands
 <!-- 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)_
 <!-- commandsstop -->
diff --git 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": {