> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tablepro.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Microsoft SQL Server
> Connect to SQL Server and Azure SQL Database with the FreeTDS-based driver plugin
# Microsoft SQL Server Connections
TablePro connects over TDS 7.4 via FreeTDS, which SQL Server 2012 and later speak. This covers instances on Windows, Linux, and Docker, plus Azure SQL Database. FreeTDS is statically linked into the plugin, so there is nothing to build or install besides the plugin itself.
## Install Plugin
The SQL Server driver is a downloadable plugin. When you select SQL Server in the connection form, TablePro prompts to install it. To install manually:
1. Open **Settings** > **Plugins** > **Browse**
2. Find **MSSQL Driver** and click **Install**
3. The plugin downloads and loads immediately, no restart needed
See [Plugins](/features/plugins) for how plugin installs and updates work.
## Connection Settings
Click **New Connection**, select **SQL Server**, fill in the fields, and click **Save & Connect**.
| Field | Default | Notes |
| ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Host** | `localhost` | Named instances are not supported; use the host and TCP port |
| **Port** | `1433` | |
| **Authentication** | `SQL Server Authentication` | Or **Windows Authentication (Kerberos)** on macOS. See [Windows Authentication](#windows-authentication-kerberos) below |
| **Username** | - | SQL Server login name. Hidden when Windows Authentication is selected |
| **Database** | - | Optional. Sent during login when set, which is required for logins scoped to one database, such as Azure SQL contained users |
| **Schema** | `dbo` | Active schema after connecting. Clear it to use the login's default schema, which the driver reads with `SELECT SCHEMA_NAME()` |
For Azure SQL Database, set the host to `yourserver.database.windows.net` and pick SSL mode **Required** or stricter.
## Windows Authentication (Kerberos)
Available on macOS. Set **Authentication** to **Windows Authentication (Kerberos)** to sign in with your domain identity instead of a SQL Server login. On macOS, Windows Authentication means Kerberos; NTLM is not supported.
There are two ways to sign in:
* **Use your existing ticket (single sign-on).** Leave the Kerberos principal and password blank. TablePro uses the ticket already in your credential cache. Get one first with `kinit`:
```bash theme={null}
kinit user@REALM.COM
klist # confirm a krbtgt/REALM.COM@REALM.COM ticket exists
```
* **Sign in with a principal and password.** Enter the Kerberos principal (`user@REALM.COM`) and your domain password. TablePro requests a ticket for that principal, then connects.
Requirements:
* **Connect by hostname, not IP address.** Kerberos targets the service principal name `MSSQLSvc/host.domain.com:1433`, which is registered against the host name.
* **Uppercase realm.** The realm is usually the DNS domain in uppercase, for example `CONTOSO.COM`.
* **Realm resolution.** Your Mac must be able to find the domain's KDC, either through DNS SRV records or an `/etc/krb5.conf` entry.
* **A registered SPN.** The SQL Server service account must have an SPN such as `MSSQLSvc/host.domain.com:1433`. Ask your administrator if connections fail with an SSPI or service-principal error.
### Servers in another realm
If the SQL Server lives in a different Kerberos realm than your Mac's `default_realm`, map its DNS domain to that realm in `/etc/krb5.conf`:
```ini theme={null}
[domain_realm]
.sql.example.com = RESOURCE.REALM.COM
```
TablePro reads that mapping and asks the KDC for a ticket in `RESOURCE.REALM.COM`, so a cross-realm trust works without changing `default_realm`. This is the same mapping the JDBC driver uses, so a server that already works in DataGrip works here.
With no `[domain_realm]` entry for the host, TablePro falls back to `default_realm`, which is what a single-realm domain needs.
TablePro does not run `kinit` or edit `/etc/krb5.conf` for you; those are set up once per machine.
## Connection URL
```text theme={null}
sqlserver://user:password@host:1433/database
mssql://user:password@host:1433/database
```
See [Connection URL Reference](/databases/connection-urls) for all parameters.
## Databases and Schemas
The sidebar groups tables by schema and hides the built-in role schemas (`db_owner`, `guest`, and the rest). Switch the active database with **Cmd+K**; switches happen in place, no reconnect. Pick the active schema from the schema menu in the sidebar. `master`, `tempdb`, `model`, and `msdb` are marked as system databases.
## Features
* **Table structure**: columns, indexes, foreign keys, triggers, and generated CREATE TABLE DDL.
* **IDENTITY columns**: INSERTs generated by the data grid omit IDENTITY columns, so the server assigns the value.
* **Pagination**: browse queries use `OFFSET ... FETCH`.
* **Large text**: `TEXTSIZE` is raised at connect, so `nvarchar(max)` and `text` values are not truncated to the 2048-byte FreeTDS default.
* **Query control**: running queries can be cancelled; the query timeout maps to `SET LOCK_TIMEOUT`.
* **View templates**: use `CREATE OR ALTER VIEW` on SQL Server 2016 and later, plain `CREATE VIEW` (drop first when editing) on older versions.
## SSL/TLS
TablePro maps the SSL mode to FreeTDS `DBSETENCRYPT`. New connections default to **Preferred**.
| Mode | FreeTDS value | Behavior |
| ------------------- | ------------- | ---------------------------------------------------------------- |
| **Disabled** | `off` | Plain TCP |
| **Preferred** | `request` | Try TLS, fall back to plain if the server cannot |
| **Required** | `require` | TLS required |
| **Verify CA** | `require` | Same as Required; dblib does not accept a CA path per connection |
| **Verify Identity** | `require` | Same as Required |
Certificate verification beyond the system trust store is configured machine-wide in `freetds.conf`, not per connection. See [SSL/TLS](/features/ssl) for concepts.
## Google Cloud SQL
SQL Server connections can run through the Cloud SQL Auth Proxy; TablePro starts and stops the proxy for you. See [Cloud SQL Auth Proxy](/databases/cloud-sql-proxy).
## Troubleshooting
**Connection refused**: enable TCP/IP in SQL Server Configuration Manager, confirm the service is running, check firewall port 1433, and if using Docker confirm the container is up.
**Login failed**: verify credentials, then check the server allows SQL Server Authentication: `SELECT SERVERPROPERTY('IsIntegratedSecurityOnly')` returns `1` when only Windows Authentication is allowed. Enable mixed mode in SSMS under Server Properties > Security, then restart the service. If the login only has access to one database (an Azure SQL contained user), set the **Database** field; TablePro sends it during login. Without it the server authenticates against `master` and rejects the login.
**Windows Authentication fails**: run `klist` to confirm you have a ticket, and `kinit user@REALM.COM` if you do not. Connect by hostname, not IP address. An SSPI or "server not found in Kerberos database" error means the server's SPN is not registered, or it is registered in a realm your Mac does not map the host to; ask your administrator to register `MSSQLSvc/host.domain.com:1433`, and if the server is in another realm add a `[domain_realm]` entry as shown in [Servers in another realm](#servers-in-another-realm). A clock-skew error means this Mac's clock is too far from the domain controller; turn on **Set time automatically** in System Settings.
**Limitations**: no Microsoft Entra ID (Azure AD) authentication, Windows Authentication (Kerberos) is macOS only, named instances unsupported (use host and port), Verify CA and Verify Identity behave like Required.