updates for connection docs for duckdb, postgres, sqlite, steampipe

turbot · Oct 21, 2024 · 8a251af · 8a251af
1 parent 8ce0a1f
commit 8a251af
Show file tree

Hide file tree

Showing 4 changed files with 74 additions and 43 deletions.
diff --git a/docs/reference/config-files/connection/duckdb.md b/docs/reference/config-files/connection/duckdb.md
@@ -46,19 +46,8 @@ duckdb:///var/db/my_ducks.db
 
 All arguments are optional, and a `duckdb` connection with no arguments will behave the same as the [default connection](#default-connection).
 
-<!--
-## Attributes (Read-Only)
-
-| Attribute       | Type   | Description
-| --------------- | ------ |------------------------------------
-| `???`           | String | blah
--->
 
 ## Default Connection
 
-The `duckdb` connection type includes an implicit, default connection (`connection.duckdb.default`) that will be configured using the environment variables ???
-```hcl
-connection "duckdb" "default" {
+The `duckdb` connection type includes an implicit, default connection (`connection.duckdb.default`), however 
 
-}
-```
diff --git a/docs/reference/config-files/connection/postgres.md b/docs/reference/config-files/connection/postgres.md
@@ -8,41 +8,85 @@ sidebar_label: postgres
 The `postgres` connection can be used to access a PostgreSQL database.
 
 ```hcl
-connection "postgres" "postgres_connection" {
-   
+connection "postgres" "my_connection" {
+   host     = "localhost"
+   port     = 5432
+   db       = "mydb"
+   username = "myuser"
+   password = "mypassword123"
 }
 ```
 
 ## Arguments
 
 | Name                | Type    | Required?| Description
 |---------------------|---------|----------|-------------------
-| `connection_string` |  String | Optional |  SQL connection string
+| `connection_string` |  String | Optional | Full PostgreSQL connection string.
+| `db`                |  String | Optional | Database name.  Defaults to `$PGDATABASE`.
+| `host`              |  String | Optional | Database hostname.  Defaults to `$PGHOST`.
+| `password`          |  String | Optional | Database password. Defaults to `$PGPASSWORD`
+| `port`              |  Number | Optional | Database port.  Defaults to `$PGPORT`.
+| `ssl_mode`          |  String | Optional | PostgreSQL [SSL Mode](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION), one of 
+`disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`.  The defaults to `$PGSSLNEGOTIATION`.
+| `username`          |  String | Optional |  Database username. Defaults to `$PGUSER`.
+
 
 All arguments are optional, and a `postgres` connection with no arguments will behave the same as the [default connection](#default-connection).
 
-connection_string
-username
-host
-port
-password
-ssl_mode
+<!--
+
+| `search_path`       |  String | Optional | Database search path.
+| `search_path_prefix`|  String | Optional | Database search path prefix.
+
+-->
+
+
+
+All arguments are optional, and a `postgres` connection with no arguments will behave the same as the [default connection](#default-connection).
+
+Typically, you supply the `host`, `port`, `db`, `username`, and `password`:
+
+```hcl
+connection "postgres" "my_connection" {
+   host     = "localhost"
+   port     = 5432
+   db       = "mydb"
+   username = "myuser"
+   password = "mypassword123"
+}
+```
 
+but you may specify a `connection_string` instead:
 
+```hcl
+connection "postgres" "postgres_connection" {
+  connection_string = "postgres://myuser:mypassword123@localhost:5432/mydb"
+}
+```
 
-## Attributes (Read-Only)
 
-| Attribute       | Type   | Description
-| --------------- | ------ |------------------------------------
-| `???`           | String | blah
+In either case, the `connection_string` is returned as an attribute.  Regardless of the syntax used to define the connection, you can get its connection_string at run time:
 
+```hcl
+pipeline "example" {
+   output "connection_string" {
+      value = connection.postgres.default.connection_string
+   }
+}
+```
 
 ## Default Connection
 
-The `postgres` connection type includes an implicit, default connection (`connection.postgres.default`) that will be configured using the environment variables ....
+The `postgres` connection type includes an implicit, default connection (`connection.postgres.default`) that will be configured using the [libpq environment variables](https://www.postgresql.org/docs/current/libpq-envars.html).
+
 
 ```hcl
 connection "postgres" "default" {
-
+  db       = env("PGDATABASE")
+  host     = env("PGHOST")
+  password = env("PGPASSWORD")
+  port     = env("PGPORT")
+  ssl_mode = env("PGSSLNEGOTIATION")
+  username = env("PGUSER")
 }
 ```
diff --git a/docs/reference/config-files/connection/sqlite.md b/docs/reference/config-files/connection/sqlite.md
@@ -47,13 +47,6 @@ sqlite:///var/db/my_sqlite_db.db
 
 All arguments are optional, and a `sqlite` connection with no arguments will behave the same as the [default connection](#default-connection).
 
-<!--
-## Attributes (Read-Only)
-
-| Attribute       | Type   | Description
-| --------------- | ------ |------------------------------------
-| `???`           | String | blah
--->
 
 ## Default Connection
 

diff --git a/docs/reference/config-files/connection/steampipe.md b/docs/reference/config-files/connection/steampipe.md
@@ -11,15 +11,18 @@ The `steampipe` connection can be used to access a [Steampipe](https://steampipe
 connection "steampipe" "steampipe_connection" {
    host     = "localhost"
    port     = 9193
+   db       = "steampipe"
    username = "steampipe"
+   password = "mypassword123"
 }
 ```
 
 ## Arguments
 
 | Name                | Type    | Required?| Description
 |---------------------|---------|----------|-------------------
-| `connection_string` |  String | Optional | Full PostreSQL connection string.  Defaults to `postgres://[email protected]:9193/steampipe`
+| `connection_string` |  String | Optional | Full PostgreSQL connection string.  Defaults to `postgres://[email protected]:9193/steampipe`
+| `db`                |  String | Optional | Database name.  Defaults to `steampipe`.
 | `host`              |  String | Optional | Database hostname.  Defaults to `127.0.0.1`.
 | `password`          |  String | Optional | Database password.
 | `port`              |  Number | Optional | Database port.  Defaults to `9193`.
@@ -32,29 +35,31 @@ connection "steampipe" "steampipe_connection" {
 
 All arguments are optional, and a `steampipe` connection with no arguments will behave the same as the [default connection](#default-connection).
 
-Typically, you either supply a `connection_string`:
+Typically, you supply the `host`, `port`, `db`, `username`, and `password`:
 
 ```hcl
 connection "steampipe" "steampipe_connection" {
-  connection_string = "postgres://steampipe:[email protected]:9193/steampipe"
+   host     = "localhost"
+   port     = 9193
+   db       = "steampipe"
+   username = "steampipe"
+   password = "mypassword123"
 }
 ```
 
-Or the `host`, `username`, `password`, etc:
+but you may specify a `connection_string` instead:
 
 ```hcl
 connection "steampipe" "steampipe_connection" {
-   host     = "localhost"
-   port     = 9193
-   username = "steampipe"
-   password = "mypassword123"
+  connection_string = "postgres://steampipe:[email protected]:9193/steampipe"
 }
 ```
 
+
 In either case, the `connection_string` is returned as an attribute.  Regardless of the syntax used to define the connection, you can get its connection_string at run time:
 
 ```hcl
-pipeeline "example" {
+pipeline "example" {
    output "connection_string" {
       value = connection.steampipe.default.connection_string
    }