Skip to content

Commit

Permalink
Standardizing and enhancing Database connector documentation (#610)
Browse files Browse the repository at this point in the history 
* Enhancing MSSQL documentation

* Standardizing and enhancing MySQL connector docs

* Standardizing and enhancing Postgres docs

* Standardizing ODBC documentation

* Updating secrets section

* Update spiceaidocs/docs/components/data-connectors/mssql.md

Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>

* Update spiceaidocs/docs/components/data-connectors/mssql.md

Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>

* Update spiceaidocs/docs/components/data-connectors/mssql.md

Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>

* Update spiceaidocs/docs/components/data-connectors/odbc.md

Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>

* Update spiceaidocs/docs/components/data-connectors/mysql.md

Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>

* Update spiceaidocs/docs/components/data-connectors/odbc.md

Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>

* Update spiceaidocs/docs/components/data-connectors/postgres/index.md

Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>

* Update spiceaidocs/docs/components/data-connectors/postgres/index.md

Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>

* Updating postgres based on suggestions

* Fixing MSSQL `from` section

* Fixing MySQL `from` section

* Updating Postgres `from` section with clearer table names

* Adding Postgres example to ODBC

* Re-adding ODBC docker section

* Improving information about the default database

---------

Co-authored-by: Phillip LeBlanc <phillip@spiceai.io>
  • Loading branch information
@slyons @phillipleblanc
slyons and phillipleblanc authored Nov 16, 2024
1 parent cb0338a commit e203b1b
Show file tree
Hide file tree
Showing 4 changed files with 414 additions and 157 deletions.
72 changes: 54 additions & 18 deletions spiceaidocs/docs/components/data-connectors/mssql.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,16 @@ sidebar_label: 'Microsoft SQL Server'
description: 'Microsoft SQL Server Data Connector'
---

The Microsoft SQL Server Data Connector enables federated SQL queries on data stored in [Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server) databases.
[Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server) is a relational database management system developed by Microsoft.

The Microsoft SQL Server Data Connector enables federated/accelerated SQL queries on data stored in MSSQL databases.

:::warning[Limitations]

1. The connector supports SQL Server authentication (SQL Login and Password) only.
1. Spatial types (`geography`) are not supported, and columns with these types will be ignored.

:::

```yaml
datasets:
Expand All @@ -16,21 +25,51 @@ datasets:
## Configuration
### `from`

The `from` field takes the form `mssql:database.schema.table` where `database.schema.table` is the fully-qualified table name in the SQL server.

### `name`

The dataset name. This will be used as the table name within Spice.

Example:
```yaml
datasets:
- from: mssql:path.to.my_dataset
name: cool_dataset
params:
...
```

```sql
SELECT COUNT(*) FROM cool_dataset;
```

```shell
+----------+
| count(*) |
+----------+
| 6001215 |
+----------+
```

### `params`

The data connector supports the following `params`. Use the [secret replacement syntax](../secret-stores/index.md) to load the secret from a secret store, e.g. `${secrets:my_mssql_conn_string}`.

- `mssql_connection_string`: The ADO connection string to use to connect to the server. This can be used instead of providing individual connection parameters.
- `mssql_host`: The hostname or IP address of the Microsoft SQL Server instance.
- `mssql_port`: (Optional) The port of the Microsoft SQL Server instance. Default value is 1433.
- `mssql_database`: (Optional) The name of the database to connect to. The default database will be used if not specified.
- `mssql_username`: The username for the SQL Server authentication.
- `mssql_password`: The password for the SQL Server authentication.
- `mssql_encrypt`: (Optional) Specifies whether encryption is required for the connection.
- `true`: (default) This mode requires an SSL connection. If a secure connection cannot be established, server will not connect.
- `false`: This mode will not attempt to use an SSL connection, even if the server supports it. Only the login procedure is encrypted
- `mssql_trust_server_certificate`: Optional parameter to specify whether the server certificate should be trusted without validation when encryption is enabled
- `true`: The server certificate will not be validated and it is accepted as-is
- `false`: (default) Server certificate will be validated against system's certificate storage
| Parameter Name | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mssql_connection_string` | The ADO connection string to use to connect to the server. This can be used instead of providing individual connection parameters. |
| `mssql_host` | The hostname or IP address of the Microsoft SQL Server instance. |
| `mssql_port` | (Optional) The port of the Microsoft SQL Server instance. Default value is 1433. |
| `mssql_database` | (Optional) The name of the database to connect to. The default database (`master`) will be used if not specified. |
| `mssql_username` | The username for the SQL Server authentication. |
| `mssql_password` | The password for the SQL Server authentication. |
| `mssql_encrypt` | (Optional) Specifies whether encryption is required for the connection.<br /> <ul><li>`true`: (default) This mode requires an SSL connection. If a secure connection cannot be established, server will not connect.</li><li>`false`: This mode will not attempt to use an SSL connection, even if the server supports it. Only the login procedure is encrypted.</li></ul> |
| `mssql_trust_server_certificate` | (Optional) Specifies whether the server certificate should be trusted without validation when encryption is enabled.<br /> <ul><li>`true`: The server certificate will not be validated and it is accepted as-is.</li><li>`false`: (default) Server certificate will be validated against system's certificate storage.</li></ul> |

### Example

```yaml
datasets:
Expand All @@ -45,9 +84,6 @@ datasets:
mssql_trust_server_certificate: true
```

:::warning[Limitations]
## Secrets

1. The connector supports SQL Server authentication (SQL Login and Password) only.
1. Spatial types (`geography`) are not supported, and columns with these types will be ignored.

:::
Spice integrates with multiple secret stores to help manage sensitive data securely. For detailed information on supported secret stores, refer to the [secret stores documentation](/components/secret-stores). Additionally, learn how to use referenced secrets in component parameters by visiting the [using referenced secrets guide](/components/secret-stores#using-secrets).
Loading

0 comments on commit e203b1b

Please sign in to comment.