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

turbot · Oct 21, 2024 · af7c845 · af7c845
1 parent 2dd3a35
commit af7c845
Show file tree

Hide file tree

Showing 4 changed files with 75 additions and 89 deletions.
diff --git a/docs/reference/config-files/connection/duckdb.md b/docs/reference/config-files/connection/duckdb.md
@@ -9,45 +9,31 @@ The `duckdb` connection can be used to access a [DuckDB](https://duckdb.org/) da
 
 ```hcl
 connection "duckdb" "duckdb_connection" {
-   connection_string = "duckdb://my_ducks.db"
+   file = "my_ducks.db"
 }
 ```
 
 ## Arguments
 
-| Name                | Type    | Required?| Description
-|---------------------|---------|----------|-------------------
-| `connection_string` |  String | Optional | DuckDB connection string
+| Name       | Type    | Required?| Description
+|------------|---------|----------|-------------------
+| `filename` |  String | Optional | Path to a DuckDB database file to open. The filename is relative to the [mod location](/docs/run#mod-location)
 
 
+## Attributes (Read-Only)
 
-### Connection String
+| Attribute           | Type   | Description
+| --------------------| ------ |------------------------------------------------------------------------------
+| `connection_string` | String | The connection string built from the arguments to this connection, in the format `duckdb://path/to/file`
 
-The DuckDB connection string is the path to a DuckDB database file:
 
-```bash
-duckdb:path/to/file
-```
-
-The path is relative to the [mod location](/docs/run#mod-location), and `//` is optional after the scheme, thus the following are equivalent relative paths:
 
-```hcl
-duckdb:./my_ducks.db
-duckdb://./my_ducks.db
-duckdb://my_ducks.db
-```
+## Default Connection
 
-and these are equivalent absolute paths:
+The `duckdb` connection type includes an implicit, default connection (`connection.duckdb.default`), however there is no file defined for this connection; you must override the default connection and supply a `filename` if you wish to use the DuckDB default connection:
 
 ```hcl
-duckdb:/var/db/my_ducks.db
-duckdb:///var/db/my_ducks.db
+connection "duckcb" "default" {
+   file = "./myfile.db"
+}
 ```
-
-All arguments are optional, and a `duckdb` connection with no arguments will behave the same as the [default connection](#default-connection).
-
-
-## Default Connection
-
-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
@@ -21,7 +21,6 @@ connection "postgres" "my_connection" {
 
 | Name                | Type    | Required?| Description
 |---------------------|---------|----------|-------------------
-| `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`
@@ -39,41 +38,15 @@ All arguments are optional, and a `postgres` connection with no arguments will b
 
 -->
 
+## Attributes (Read-Only)
 
+| Attribute           | Type   | Description
+| --------------------| ------ |------------------------------------------------------------------------------
+| `connection_string` | String | The connection string built from the arguments to this connection, in the format `postgresql://[username[:password]@][host][:port][/db]`
+| `env`               | Map    | A map of the resolved [libpq environment variables](https://www.postgresql.org/docs/current/libpq-envars.html) (`PGHOST`, `PGDATABASE`, `PGUSER`, `PGPASSWORD`, `PGPORT`, `PGSSLNEGOTIATION`)
 
-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"
-}
-```
 
 
-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 [libpq environment variables](https://www.postgresql.org/docs/current/libpq-envars.html).

diff --git a/docs/reference/config-files/connection/sqlite.md b/docs/reference/config-files/connection/sqlite.md
@@ -4,6 +4,51 @@ sidebar_label: sqlite
 ---
 
 
+# sqlite
+
+The `sqlite` connection can be used to access a [SQLite](https://www.sqlite.org/) database.
+
+```hcl
+connection "sqlite" "sqlite_connection" {
+   filename = "./my_sqlite_db.db"
+}
+```
+
+
+## Arguments
+
+| Name       | Type    | Required?| Description
+|------------|---------|----------|-------------------
+| `filename` |  String | Optional | Path to a SQLite database file to open. The filename is relative to the [mod location](/docs/run#mod-location)
+
+
+## Attributes (Read-Only)
+
+| Attribute           | Type   | Description
+| --------------------| ------ |------------------------------------------------------------------------------
+| `connection_string` | String | The connection string built from the arguments to this connection, in the format `sqlite://path/to/file`
+
+
+
+## Default Connection
+
+The `sqlite` connection type includes an implicit, default connection (`connection.sqlite.default`), however there is no file defined for this connection; you must override the default connection and supply a `filename` if you wish to use the DuckDB default connection:
+
+```hcl
+connection "sqlite" "default" {
+   file = "./myfile.db"
+}
+```
+
+<!--
+
+
+---
+title:  sqlite
+sidebar_label: sqlite
+---
+
+
 # sqlite
 
 The `sqlite` connection can be used to access a [SQLite](https://www.sqlite.org/) database.
@@ -56,3 +101,6 @@ connection "sqlite" "default" {
 
 }
 ```
+
+
+-->
diff --git a/docs/reference/config-files/connection/steampipe.md b/docs/reference/config-files/connection/steampipe.md
@@ -21,7 +21,6 @@ connection "steampipe" "steampipe_connection" {
 
 | Name                | Type    | Required?| Description
 |---------------------|---------|----------|-------------------
-| `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.
@@ -34,43 +33,23 @@ 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 supply the `host`, `port`, `db`, `username`, and `password`:
 
-```hcl
-connection "steampipe" "steampipe_connection" {
-   host     = "localhost"
-   port     = 9193
-   db       = "steampipe"
-   username = "steampipe"
-   password = "mypassword123"
-}
-```
+## Attributes (Read-Only)
 
-but you may specify a `connection_string` instead:
+| Attribute           | Type   | Description
+| --------------------| ------ |------------------------------------------------------------------------------
+| `connection_string` | String | The connection string built from the arguments to this connection, in the format `postgresql://[username[:password]@][host][:port][/db]`
+| `env`               | Map    | A map of the resolved [libpq environment variables](https://www.postgresql.org/docs/current/libpq-envars.html) (`PGHOST`, `PGDATABASE`, `PGUSER`, `PGPASSWORD`, `PGPORT`, `PGSSLNEGOTIATION`)
 
-```hcl
-connection "steampipe" "steampipe_connection" {
-  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
-pipeline "example" {
-   output "connection_string" {
-      value = connection.steampipe.default.connection_string
-   }
-}
-```
 
 ## Default Connection
 
 The `steampipe` connection type includes an implicit, default connection (`connection.steampipe.default`) that will be configured to use the local Steampipe instance, eg:
 
 ```hcl
-connection "steampipe" "default" {
-  connection_string = "postgres://[email protected]:9193/steampipe"
-}
+   host     = "localhost"
+   port     = 9193
+   db       = "steampipe"
+   username = "steampipe"
 ```