Updates v0.23 (#193)

* updated docs for semver constraint plugin install/updates (#184)

* updated docs for semver constraint plugin install/updates

* reworked text around when you need to create connection/connection file

* add docs for verbose timing option

* update docs for verbose timing

---------

Co-authored-by: Graza <[email protected]>

docs/managing/plugins.md

@@ -16,42 +16,69 @@ For example, to install the latest `aws` plugin:
 $ steampipe plugin install aws
 ```
 
-This will download the latest aws plugin (the one with the `latest` tag) from the hub registry, and will set up a default connection named `aws`. 
+This will download the latest aws plugin from the hub registry, and will set up a default connection named `aws`.
 
+> Note: If you install multiple versions of a plugin only the first installation will create a connection automatically for you, you will need to create/edit a [connection](/docs/managing/connections) configuration file in order to use the additional versions of the plugin. 
 
 ### Installing a Specific Version
 To install a specific version, simply specify the version tag after the plugin name, separated by `@` or `:`
 
-For example, to install the 0.0.1 version of the aws plugin:
+For example, to install the 0.118.0 version of the aws plugin:
 ```
-$ steampipe plugin install aws@0.0.1
+$ steampipe plugin install aws@0.118.0
 ```
 
-This will download the aws plugin version 0.0.1 (the one with the `0.0.1` tag) from the hub registry.  Note that installing a specific version will NOT create a connection for you - you must create/edit a [connection](/docs/managing/connections) configuration file in order to use the plugin. 
+This will download the aws plugin version 0.118.0 (the one with the `0.118.0` tag) from the hub registry. 
 
+### Installing from a SemVer Constraint
 
-### Installing from a Release Stream
+Plugins should follow [semantic versioning](https://semver.org/) guidelines, and they are tagged in the registry with a **version tag** that specifies their *exact version* in the `major.minor.patch` format (e.g. `1.0.1`).
 
-Plugins should follow semantic versioning guidelines, and they are tagged in the registry with a **version tag** that specifies their *exact version* (e.g. `1.0.1`).  
+The intent of the version tag is that it is immutable - while it is technically possible to move the version tag to a different image version, this should not be done.
 
-In addition, **release stream** tags are used to allow you to limit updates to specific *major or minor release families*.  
+Installing with a semver constraint allows you to "lock" (or pin) to a specific set of releases which match the contraints. 
 
-The intent of the version tag is that is immutable - while it is technically possible to move the version tag to a different image version, this should not be done.  Unlike the version tag, the release stream tags are intentionally moved as new versions are released.  For example `steampipe plugin install aws@1.0` will install the latest version in the `1.0` minor release stream.  If versions `1.0.0` and `1.0.1` both exist, then `[email protected]` will point to `1.0.1`.  When `1.0.2` is added to the registry, the `1.0` tag will be moved to point to `1.0.2`. 
+If you install via `steampipe plugin install aws@^1`, for example, `steampipe plugin update` (and auto-updates) will only update to versions greater than `1.0.0` but less than `2.0.0`.
 
-Installing a release stream tag allows you to "lock" to a specific major or minor release.  If you install `aws@1`, for example, `steampipe plugin update` (and auto-updates) will only update to the latest 1.x version - you will not be updated to version 2.x.
+Supported semver constraint types:
 
-Because these are just tags, the install command uses the same `imagename@tag` syntax:
-- To install the latest version in major release stream:
-```
-$ steampipe plugin install aws@2
-```
+**Wildcard Constraint**: This matches any version for a particular segment (Major, Minor, or Patch).
+- `1.x.x` would match any version with major segment of `1`.
+- `1.2.x` would match any version with the major segment of `1` and a minor segment of `2`.
 
-- To install the latest version in minor release stream:
-```
-$ steampipe plugin install [email protected]
+**Caret Constraint (^)**: This matches versions that do not modify the left-most non-zero digit.
+- `^1.2.3` is the latest version equal or greater than `1.2.3`, but less than `2.0.0`.
+- `^0.1.2` is the latest version equal or greater than `0.1.2`, but less than `0.2.0`.
+
+**Tilde Constraint (~)**: This matches versions based on expression, if minor segment is expressed, locks to it, else locks to major.
+- `~1` is the latest version greater than or equal to `1.0.0`, but less than `2.0.0` (same as `1.x.x`).
+- `~1.2` is the latest version greater than or equal to `1.2.0`, but less than `1.3.0` (same as `1.2.x`).
+- `~1.2.3` is the latest version greater than or equal to `1.2.3`, but less than `1.3.0`.
+
+**Range Constraint**: This specifies a range of versions using a hyphen.
+- `1.2.3-1.2.5` would limit to latest available version of `1.2.3`,`1.2.4` or `1.2.5`.
+
+**Other Constraints**:
+- `>1.1.1` would match any version greater than `1.1.1`.
+- `>=1.2.0` would match any version greater than or equal to `1.2.0`.
+
+You can use the install command in the same way as a specific version with these constraints (`imagename@constraint`) syntax:
+
+> Note: For some constraints using special characters `>`, `<`, `*` you may need to escape the characters `\>` or quote the string `steampipe plugin install "aws@>0.118.0"` depending on your terminal.
+
+- To install the latest version locked to a specific major version:
+```bash
+$ steampipe plugin install aws@^2
+# or
+$ steampipe plugin install [email protected]
 ```
 
-Note that installing a tagged release will NOT create a connection for you - you must create/edit a [connection](managing/connections) configuration file in order to use the plugin. 
+- To install the latest version locked to a specific minor version:
+```bash 
+$ steampipe plugin install aws@~2.1
+# or
+$ steampipe plugin install [email protected]
+```
 
 ### Installing from another registry
 Steampipe plugins are packaged in OCI format and can be hosted and installed from any artifact repository or container registry that supports OCI V2 images. To install a plugin from a repository, specify the full path in the install command:

docs/reference/cli/check.md

@@ -167,8 +167,8 @@ steampipe check list
   </tr>
 
   <tr> 
-    <td nowrap="true"> <inlineCode>--timing  </inlineCode>  </td> 
-    <td>Turn on the query timer. </td>
+    <td nowrap="true"> <inlineCode>--timing=string </inlineCode>  </td>
+    <td>Enable or disable query execution timing: <inlineCode>off</inlineCode> (default) or <inlineCode>on</inlineCode> </td>
   </tr>
 
   <tr> 

docs/reference/cli/plugin.md

@@ -58,6 +58,16 @@ Install a specific version of a plugin:
 steampipe plugin install [email protected]
 ```
 
+Install the latest version of a plugin matching a semver constraint:
+```bash
+steampipe plugin install aws@^0.107
+```
+
+Note: if your semver constraint contain special characters you may need to quote it:
+```bash
+steampipe plugin install "aws@>=0.100"
+```
+
 Install all missing plugins that specified in configuration files. Do not download their default configuration files:
 
 ```bash
@@ -79,9 +89,9 @@ Update all plugins to the latest in the installed stream:
 steampipe plugin update --all
 ```
 
-Update the aws plugin to the latest in the 0.1 minor stream:
+Update the aws plugin to the latest version meeting the constraint:
 ```bash
-steampipe plugin update aws@0.1
+steampipe plugin update aws@^0.107
 ```
 
 Update all plugins to the latest and hide the progress bar:

docs/reference/cli/query.md

@@ -8,9 +8,9 @@ Execute SQL queries interactively, or by a query argument.
 
 To open the interactive query shell, run `steampipe query` with no arguments.  The query shell provides a way to explore your data and run multiple queries. 
 
-If a query string is passed on the command line then it will be run immediately and the command will exit.  Alternatively, you may specify one or more files containing SQL statements.  You can run multiple SQL files by passing a glob or a space separated list of file names.
+If a query string is passed on the command line then it will be run immediately and the command will exit.  Alternatively, you may specify one or more files containing SQL statements.  You can run multiple SQL files by passing a glob or a space-separated list of file names.
 
-If the Steampipe service was previously started by `steampipe service start`, steampipe will connect to the service instance - otherwise, the query command will start the `service`. At the end of the query command or session, if other sessions have not connected to the `service` already, the `service` will be shutdown. If other session have already connected to the `service`, then the last session to exit will shutdown the `service`.
+If the Steampipe service was previously started by `steampipe service start`, steampipe will connect to the service instance - otherwise, the query command will start the `service`. At the end of the query command or session, if other sessions have not connected to the `service` already, the `service` will be shutdown. If other sessions have already connected to the `service`, then the last session to exit will shutdown the `service`.
 
 ## Usage
 Run Steampipe [interactive query shell](/docs/query/query-shell):
@@ -148,8 +148,8 @@ steampipe query list
 
 
   <tr> 
-    <td nowrap="true"> <inlineCode>--timing  </inlineCode>  </td> 
-    <td>Turn on the query timer.  </td>
+    <td nowrap="true"> <inlineCode>--timing=string </inlineCode> </td>
+    <td>Enable or disable query execution timing: <inlineCode>off</inlineCode> (default), <inlineCode>on</inlineCode>, or <inlineCode>verbose</inlineCode>  </td>
   </tr>
 
 
@@ -229,6 +229,12 @@ Run a specific query directly and report the query execution time:
 steampipe query "select * from aws_s3_bucket" --timing
 ```
 
+Run a specific query directly and report the query execution time and details for each scan:
+```bash
+steampipe query "select * from aws_s3_bucket" --timing=verbose
+```
+
+
 Run a specific query directly and return output in json format:
 ```bash
 steampipe query "select * from aws_s3_bucket" --output json

docs/reference/config-files/plugin.md

@@ -177,7 +177,7 @@ plugin "aws_latest" {
 }
 
 plugin "aws_0_117_0" {
-  source = "[email protected]"
+  source = "[email protected].0"
 }
 
 

docs/reference/config-files/workspace.md

@@ -78,7 +78,7 @@ Any unset arguments will assume the default values.
 
 ### Steampipe Query Options 
 
-A `workspace` may include a `options "query"` block to specify values specific to the `steampipe query` command.  
+A `workspace` may include an `options "query"` block to specify values specific to the `steampipe query` command.  
 
 These options often correspond to CLI flags.
 
@@ -118,17 +118,17 @@ These options often correspond to CLI flags.
     </tr>
     <tr>
       <td><inlineCode>timing</inlineCode></td>
-      <td><inlineCode>false</inlineCode></td>
-      <td>Enable or disable query execution timing. <br /> <br /> CLI: <inlineCode>--timing</inlineCode></td>
+      <td><inlineCode>off</inlineCode></td>
+      <td>Enable or disable query execution timing: <inlineCode>off</inlineCode>, <inlineCode>on</inlineCode>, or <inlineCode>verbose</inlineCode> <br /> <br /> CLI: <inlineCode>--timing</inlineCode></td>
     </tr>
   </tbody>
 </table>
 
 
 ### Steampipe Check Options 
-A `workspace` may include a `options "check"` block to specify values specific to the `steampipe check` command.  
+A `workspace` may include an `options "check"` block to specify values specific to the `steampipe check` command.  
 
-These option often correspond to CLI flags.
+These options often correspond to CLI flags.
 
 <table>
   <thead>
@@ -157,7 +157,7 @@ These option often correspond to CLI flags.
     <tr>
       <td><inlineCode>timing</inlineCode></td>
       <td><inlineCode>false</inlineCode></td>
-      <td>Enable or disable query execution timing. <br /> <br /> CLI: <inlineCode>--timing</inlineCode></td>
+      <td>Enable or disable query execution timing: <inlineCode>false</inlineCode> or <inlineCode>true</inlineCode> <br /> <br /> CLI: <inlineCode>--timing</inlineCode></td>
     </tr>
   </tbody>
 </table>
@@ -167,7 +167,7 @@ These option often correspond to CLI flags.
 ### Steampipe Dashboard Options 
 A `workspace` may include a `options "dashboard"` block to specify values specific to the `steampipe dashboard` command.  
 
-These option often correspond to CLI flags.
+These options often correspond to CLI flags.
 
 <table>
   <thead>
@@ -227,7 +227,7 @@ workspace "all_options" {
     multi               = false   # true, false
     output              = "table" # json, csv, table, line
     separator           = ","     # any single char
-    timing              = true   # true, false
+    timing              = "on"    # on, off, verbose
   }
 
   options "check" {

docs/reference/dot-commands/timing.md

@@ -3,13 +3,21 @@ title: .timing
 sidebar_label: .timing
 ---
 
-
 # .timing
-Turn query execution timing on or off. 
+
+Enable or disable query execution timing:
+
+
+| Level     | Description
+|-----------|-------------------------
+| `off`     | Turn off query timer (default)
+| `on`      | Display time elapsed after every query
+| `verbose` | Display time elapsed and details of each scan
+
 
 ## Usage
 ```
-.timing [on | off]
+.timing [on | off | verbose]
 ```
 
 ## Examples
@@ -22,4 +30,9 @@ Turn off query timing:
 Turn on query timing:
 ```
 .timing on
+```
+
+Turn on verbose query timing:
+```
+.timing verbose
 ```