Skip to content

Commit

Permalink
update reference docs for config file and caching changes in .20
Browse files Browse the repository at this point in the history
  • Loading branch information
@johnsmyth
johnsmyth committed May 16, 2023
1 parent d5ac43d commit a8cf9cb
Show file tree
Hide file tree
Showing 8 changed files with 139 additions and 120 deletions.
6 changes: 0 additions & 6 deletions docs/reference/config-files/connection.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,6 @@ Most `connection` arguments are plugin-specific, and they are used to specify cr
| `type` | `plugin` | `plugin`, `aggregator` | The type of connection - [plugin connection](/docs/managing/plugins#installing-plugins) or [aggregator](/docs/managing/connections#using-aggregators).
| `{plugin argument}`| varies | varies| Additional options are defined in each plugin - refer to the documentation for your plugin on the [Steampipe Hub](https://hub.steampipe.io/plugins).

<!--
deprecated in 0.20
| `options` | none | `options "connection"` block | An optional `options` block to set [connection options](reference/config-files/options#connection-options) for this connection. Only `connection` options are supported.
-->

### Plugin Version Strings

Expand Down
180 changes: 86 additions & 94 deletions docs/reference/config-files/options.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,171 +18,163 @@ The following `options` are currently supported:

| Option Type | Description
|-|-
| [connection](#connection-options) | Options that apply to connections.
| [database](#database-options) | Database options.
| [dashboard](#database-options) | Dashboard options.
| [general](#general-options) | General CLI options, such as auto-update options.
| [terminal](#terminal-options) | Terminal options, which generally map to .meta-commands


<!--
| [check](#check-options) | Options that apply to `steampipe check`.
| [query](#query-options) | Options that apply to `steampipe query`.
-->
---


<!--
## Check Options
**Check** options can be used to change query output formats and other `steampipe check` options. The options and values correspond to the [command line arguments](docs/reference/cli/check) of the same name.
### Supported options
| Argument | Default | Values | Description
|-|-|-|-
| `header` | `true` | `true`, `false` | Enable or disable column headers.
| `output` | `table` | `brief`,`csv`,`html`,`json`,`md`,`text`,`none` | Set output format.
| `separator` | `,` | Any single character | Set csv output separator.
### Example: Check Options
Deprecated...
| [terminal](#terminal-options) | Terminal options, which generally map to .meta-commands
| [connection](#connection-options) | Options that apply to connections.
-->
---

```hcl
options "query" {
output = "csv"
header = true
separator = ","
}
```

---
-->

## Connection Options
**Connection** options are options that can be set on a per-connection basis. Connection options may be set at 2 scopes:
- Defined in a top-level `options "connection"`, these apply to ALL connections that do not explicitly override them.
- Defined in an `options` block under a `connection`, these apply only to that connection. Per-connection options always override top-level connection options, and their arguments are identical.
## Database Options

**Database** options are used to control database options, such as the IP address and port on which the database listens.

### Supported options
| Argument | Default | Values | Description
|-|-|-|-
| `cache` | `true` | `true`, `false` | Enable or disabled caching.
| `cache_ttl` | `300` | an integer | The length of time to cache results, in seconds.
| `cache` | `true` | `true`, `false` | Enable or disable query caching. This can also be set via the [STEAMPIPE_CACHE](/docs/reference/env-vars/steampipe_cache) environment variable.
| `cache_max_size_mb` | unlimited | an integer | The maximum total size of the query cache across all plugins. This can also be set via the [STEAMPIPE_CACHE_MAX_SIZE_MB](/docs/reference/env-vars/steampipe_cache_max_size_mb) environment variable.
| `cache_max_ttl` | `300` | an integer | The maximum length of time to cache query results, in seconds. This can also be set via the [STEAMPIPE_CACHE_MAX_TTL](/docs/reference/env-vars/steampipe_cache_max_ttl) environment variable.
| `listen` | `network` | `local`, `network`| The network listen mode when steampipe is started in [service mode](/docs/managing/service#starting-the-database-in-service-mode). Use `network` to listen on all IP addresses, or `local` to restrict to localhost.
| `port` | `9193` | any valid, open port number | The TCP port that Postgres will listen on.
| `search_path` | All connections, alphabetically | Comma separated string | Set an exact [search path](managing/connections#setting-the-search-path). Note that setting the search path in the database options sets it in the database; this setting will also be in effect when connecting to Steampipe from 3rd party tools. See also: [Using search_path to target connections and aggregators](https://steampipe.io/docs/guides/search-path).
| `search_path_prefix` | none | Comma separated string | Move one or more connections or aggregators to the front of the [search path](managing/connections#setting-the-search-path). Note that setting the search path prefix in the database options sets in the database; this setting will also be in effect when connecting to Steampipe from 3rd party tools. See also: [Using search_path to target connections and aggregators](https://steampipe.io/docs/guides/search-path).
| `start_timeout` | `30` | an integer | The maximum time (in seconds) to wait for the Postgres process to start accepting queries after it has been started. This can also be set via the [STEAMPIPE_DATABASE_START_TIMEOUT](/docs/reference/env-vars/steampipe_database_start_timeout) environment variable.


### Example: Top-Level Connection Options
Top-Level connection options apply to ALL connections (unless overridden in an `options` block within a `connection`).
### Example: Database Options

```hcl
options "connection" {
cache = true # true, false
cache_ttl = 300 # expiration (TTL) in seconds
options "database" {
cache = true # true, false
cache_max_ttl = 900 # max expiration (TTL) in seconds
cache_max_size_mb = 1024 # max total size of cache across all plugins
port = 9193 # any valid, open port number
listen = "local" # local, network
search_path_prefix = "aws,aws2,gcp,gcp2" # comma-separated string; an exact search_path
start_timeout = 30 # maximum time (in seconds) to wait for the database to start up
}
```

### Example: Per-Connection Options
```hcl
connection "aws_account1" {
plugin = "aws"
profile = "account1"
regions = ["us-east-1", "us-east-2", "us-west-1", "us-west-2", "eu-west-1", "eu-west-2"]

options "connection" {
cache = true # true, false
cache_ttl = 300 # expiration (TTL) in seconds
}
}
```

---
## Dashboard Options

## Database Options

**Database** options are used to control database options, such as the IP address and port on which the database listens.
**Dashboard** options are used to set dashboard service options, such as the IP address and port on which the dashboard web server listens.

### Supported options
| Argument | Default | Values | Description
|-|-|-|-
| `port` | `9193` | any valid, open port number | The TCP port that Postgres will listen on
| `listen` | `network` | `local`, `network`| The network listen mode when steampipe is started in [service mode](/docs/managing/service#starting-the-database-in-service-mode). Use `network` to listen on all IP addresses, or `local` to restrict to localhost.
| `search_path` | All connections, alphabetically | Comma separated string | Set an exact [search path](managing/connections#setting-the-search-path). Note that setting the search path in the database options sets it in the database; this setting will also be in effect when connecting to Steampipe from 3rd party tools. See also: [Using search_path to target connections and aggregators](https://steampipe.io/docs/guides/search-path).
| `port` | `9193` | any valid, open port number | The TCP port that Postgres will listen on


### Example: Database Options
### Example: Dashboard Options

```hcl
options "database" {
port = 9193 # any valid, open port number
options "dashboard" {
port = 9194 # any valid, open port number
listen = "local" # local, network
search_path = "aws,aws2,gcp,gcp2" # comma-separated string; an exact search_path
start_timeout = 30 # maximum time (in seconds) to wait for the database to start up
}
```

---



----
## General options
**General** options apply generally to the Steampipe CLI.
**General** options apply generally to the Steampipe CLI.

### Supported options
| Argument | Default | Values | Description
| Argument | Default | Values | Description
|-|-|-|-
| `max_parallel` | `10` | an integer| Set the maximum number of parallel executions. When running `steampipe check`, Steampipe will attempt to run up to this many controls in parallel. This can also be set via the `STEAMPIPE_MAX_PARALLEL` environment variable.
| `telemetry` | `none` | `none`, `info` | Set the telemetry level in Steampipe. This can also be set via the [STEAMPIPE_TELEMETRY](reference/env-vars/steampipe_telemetry) environment variable. See also: [Telemetry](https://steampipe.io/blog/release-0-15-0#telemetry).
| `log_level` | `warn` | `trace`, `debug`, `info`, `warn`, `error` | Sets the output logging level. Standard log levels are supported. This can also be set via the [STEAMPIPE_LOG_LEVEL](reference/env-vars/steampipe_log) environment variable.
| `telemetry` | `none` | `none`, `info` | Set the telemetry level in Steampipe. This can also be set via the [STEAMPIPE_TELEMETRY](reference/env-vars/steampipe_telemetry) environment variable. See also: [Telemetry](https://steampipe.io/blog/release-0-15-0#telemetry).
| `update_check` | `true` | `true`, `false` | Enable or disable automatic update checking. This can also be set via the [STEAMPIPE_UPDATE_CHECK](reference/env-vars/steampipe_update_check) environment variable.


<!-- Deprecated
| `max_parallel` | `10` | an integer| Set the maximum number of parallel executions. When running `steampipe check`, Steampipe will attempt to run up to this many controls in parallel. This can also be set via the `STEAMPIPE_MAX_PARALLEL` environment variable.
-->
### Example: General Options

```hcl
options "general" {
update_check = true # true, false
max_parallel = 3
telemetry = "info" # info, none
}
log_level = "warn" # trace, debug, info, warn, error
telemetry = "info" # info, none
update_check = true # true, false
}
```

---


<!--

## Query Options
## Connection Options

**Query** options can be used to change query output formats and other `steampipe query` options. Typically, these can also be set via [meta-commands](/docs/reference/dot-commands/overview) or [command line arguments](/docs/reference/cli/query) of the same name.
***The `options "connection"` block has been deprecated in steampipe 0.20.***
- You can set server query cache options in the [database options. →](#database-options)
- You can set client query cache options for each [workspaces. →](/docs/reference/config-files/workspace)


<!--
## Connection Options
**Connection** options are options that can be set on a per-connection basis. Connection options may be set at 2 scopes:
- Defined in a top-level `options "connection"`, these apply to ALL connections that do not explicitly override them.
- Defined in an `options` block under a `connection`, these apply only to that connection. Per-connection options always override top-level connection options, and their arguments are identical.
### Supported options
| Argument | Default | Values | Description
|-|-|-|-
| `header` | `true` | `true`, `false` | Enable or disable column headers.
| `multi` | `false` | `true`, `false` | Enable or disable multiline mode.
| `output` | `table` | `json`, `csv`, `table`, `line` | Set output format.
| `separator` | `,` | Any single character | Set csv output separator.
| `timing` | `false` | `true`, `false` | Enable or disable query execution timing.
| `autocomplete` | `true` | `true`, `false` | Enable or disable autocomplete in interactive mode.
| `cache` | `true` | `true`, `false` | Enable or disabled caching.
| `cache_ttl` | `300` | an integer | The length of time to cache results, in seconds.
### Example: Query Options
### Example: Top-Level Connection Options
Top-Level connection options apply to ALL connections (unless overridden in an `options` block within a `connection`).
```hcl
options "query" {
multi = false # true, false
output = "table" # json, csv, table, line
header = true # true, false
separator = "," # any single char
timing = true # true, false
autocomplete = true
}
options "connection" {
cache = true # true, false
cache_ttl = 300 # expiration (TTL) in seconds
}
```
---
-->
### Example: Per-Connection Options
```hcl
connection "aws_account1" {
plugin = "aws"
profile = "account1"
regions = ["us-east-1", "us-east-2", "us-west-1", "us-west-2", "eu-west-1", "eu-west-2"]
options "connection" {
cache = true # true, false
cache_ttl = 300 # expiration (TTL) in seconds
}
}
```
-->

## Terminal Options
***The `options "terminal"` block has been deprecated in steampipe 0.20.***
- you can set these options for each [workspace. →](/docs/reference/config-files/workspace)


<!--
***`terminal` options have been deprecated - please use `query` and `check` options instead***
-->
**Terminal** options can be used to change query output formats and other terminal options. Typically, these can also be set via [meta-commands](/docs/reference/dot-commands/overview) or [command line arguments](/docs/reference/cli/overview) of the same name.
Expand Down Expand Up @@ -215,7 +207,7 @@ options "terminal" {
watch = true # true, false
}
```

-->



Expand Down
Loading

0 comments on commit a8cf9cb

Please sign in to comment.