# SQL Server

> Connect SQL Server to sanda: what to prepare, the fields the connection form asks for, and how its data lands in your warehouse.

## Connect SQL Server

:::steps
1. **Open the catalogue.** In the console, go to **Data · Connections** and press **New connection**.
2. **Choose SQL Server.** It is listed under databases; you can also search for it by name.
3. **Fill in the form.** Enter the fields below. Credentials go straight to sanda’s sync engine and are never stored in sanda’s database.
4. **Choose what to sync.** Pick the tables you want, and a sync mode for each. See [choose what to sync](https://docs.sanda-os.com.au/connections/choose-tables).
5. **Run the first sync.** sanda tests the connection, then lands each table you chose in your warehouse.
:::

## Configuration fields

What the connection form asks for. Required fields are marked; the rest are optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Host** | string | Yes | The hostname of the database. |
| **Port** | integer | Yes | The port of the database. Default `1433`. |
| **Database** | string | Yes | The name of the database. |
| **Schemas** | array | No | The list of schemas to sync from. If not specified, all schemas will be discovered. Case sensitive. |
| **Username** | string | No | The username which is used to access the database. Not required if Microsoft Entra ID authentication is configured below. |
| **Password** | string, secret | No | The password associated with the username. Not required if Microsoft Entra ID authentication is configured below. |
| **JDBC URL Params** | string | No | Additional properties to pass to the JDBC URL string when connecting to the database formatted as 'key=value' pairs separated by the symbol '&'. (example: key1=value1&key2=value2&key3=value3). |
| **Entra ID Client ID** | string | No | Application (client) ID of a Microsoft Entra ID service principal. When provided together with Client Secret, Entra ID authentication is used instead of username and password. |
| **Entra ID Client Secret** | string, secret | No | Client secret for the Microsoft Entra ID service principal. When provided together with Client ID, Entra ID authentication is used instead of username and password. |
| **Encryption** | one of 3 options | No | The encryption method which is used when communicating with the database. |
| **SSH Tunnel Method** | one of 3 options | No | Whether to initiate an SSH tunnel before connecting to the database, and if so, which kind of authentication to use. |
| **Update Method** | one of 2 options | Yes | Configures how data is extracted from the database. |
| **Checkpoint Target Time Interval** | integer | No | How often (in seconds) a stream should checkpoint, when possible. Default `300`. |
| **Concurrency** | integer | No | Maximum number of concurrent queries to the database. |
| **Check Table and Column Access Privileges** | boolean | No | When this feature is enabled, during schema discovery the connector will query each table or view individually to check access privileges and inaccessible tables, views, or columns therein will be removed. In large schemas, this might cause schema discovery to take too long, in which case it might be advisable to disable this feature. Default `true`. |
| **AdditionalProperties** | object | No |  |

### Encryption

The encryption method which is used when communicating with the database.

Choose one of the following. Each asks for its own fields.

**Unencrypted**

No further fields.

**Encrypted (trust server certificate)**

No further fields.

**Encrypted (verify certificate)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Host Name In Certificate** | string | No | Specifies the host name of the server. The value of this property must match the subject property of the certificate. |
| **Certificate** | string, secret | No | Certificate of the server, or of the CA that signed the server certificate. |


### SSH Tunnel Method

Whether to initiate an SSH tunnel before connecting to the database, and if so, which kind of authentication to use.

Choose one of the following. Each asks for its own fields.

**No Tunnel**

No further fields.

**SSH Key Authentication**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **SSH Tunnel Jump Server Host** | string | Yes | Hostname of the jump server host that allows inbound ssh tunnel. |
| **SSH Connection Port** | integer | Yes | Port on the proxy/jump server that accepts inbound ssh connections. Default `22`. |
| **SSH Login Username** | string | Yes | OS-level username for logging into the jump server host. |
| **SSH Private Key** | string, secret | Yes | OS-level user account ssh key credentials in RSA PEM format ( created with ssh-keygen -t rsa -m PEM -f myuser_rsa ). |

**Password Authentication**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **SSH Tunnel Jump Server Host** | string | Yes | Hostname of the jump server host that allows inbound ssh tunnel. |
| **SSH Connection Port** | integer | Yes | Port on the proxy/jump server that accepts inbound ssh connections. Default `22`. |
| **SSH Login Username** | string | Yes | OS-level username for logging into the jump server host. |
| **Password** | string, secret | Yes | OS-level password for logging into the jump server host. |


### Update Method

Configures how data is extracted from the database.

Choose one of the following. Each asks for its own fields.

**Scan Changes with User Defined Cursor**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Exclude Today's Data** | boolean | No | When enabled incremental syncs using a cursor of a temporal type (date or datetime) will include cursor values only up until the previous midnight UTC. Default `false`. |

**Read Changes using Change Data Capture (CDC)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Initial Waiting Time in Seconds (Advanced)** | integer | No | The amount of time the connector will wait when it launches to determine if there is new data to sync or not. Defaults to 300 seconds. Valid range: 120 seconds to 3600 seconds. |
| **Invalid CDC Position Behavior (Advanced)** | string | No | Determines whether becca should fail or re-sync data in case of an stale/invalid cursor value in the mined logs. If 'Fail sync' is chosen, syncs fail until becca support resets the connection. If 'Re-sync data' is chosen, becca will automatically trigger a refresh but could lead to higher costs and data loss. One of `Fail sync`, `Re-sync data`. Default `Fail sync`. |
| **Initial Load Timeout in Hours (Advanced)** | integer | No | The amount of time an initial load is allowed to continue for before catching up on CDC logs. Default `8`. |
| **Poll Interval in Milliseconds (Advanced)** | integer | No | How often (in milliseconds) Debezium should poll for new data. Must be smaller than heartbeat interval (15000ms). Lower values provide more responsive data capture but may increase database load. Default `500`. |


## Related

:::links
- [Sync modes](https://docs.sanda-os.com.au/connections/sync-modes): How sanda reads each table on every run.
- [Sync schedules](https://docs.sanda-os.com.au/connections/schedules): How often a connection runs.
- [Allowlist sanda’s address](https://docs.sanda-os.com.au/connections/allowlist): For a system behind a firewall.
- [Troubleshoot connections](https://docs.sanda-os.com.au/connections/troubleshooting): What an error means and how to fix it.
:::