> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SQL Server

> Connect Bytebase to Microsoft SQL Server, including Availability Groups and encryption.

To add a SQL Server database, go to **Instances**, click **Connect instance**, and choose **MSSQL**.

Bytebase lists every database on the server except `master`, `model`, `msdb`, and `tempdb` as a Bytebase database. On Amazon RDS, it also skips `rdscore`. See [Database](/concepts/database).

## Supported versions

Bytebase supports Microsoft SQL Server 2019 and later. It connects through a built-in driver, so there is nothing to install.

## Create a user for Bytebase

On a self-managed server, create a login for Bytebase and add it to `sysadmin`. The examples name the login `bytebase`.

```sql theme={null}
CREATE LOGIN bytebase WITH PASSWORD = '<password>';
ALTER SERVER ROLE sysadmin ADD MEMBER bytebase;
```

On Amazon RDS for SQL Server, the master user isn't a member of `sysadmin` and can't add other logins to it. Create the login as the master user instead, and make it `db_owner` in each database Bytebase manages:

```sql theme={null}
CREATE LOGIN bytebase WITH PASSWORD = '<password>';
-- Repeat in each database that Bytebase manages.
USE <database>;
CREATE USER bytebase FOR LOGIN bytebase;
ALTER ROLE db_owner ADD MEMBER bytebase;
```

## Connection details

### Authentication

How Bytebase signs in:

* **Plain Password**: the **Username** and **Password** below.
* **Azure IAM**: a Microsoft Entra identity, for Azure SQL. See [Azure](/get-started/connect/azure).

### Hostname

The host name or IP address of the SQL Server instance, such as `db.example.com`. For an Availability Group, use the listener, as described in [Availability Groups](#availability-groups).

### Port

The server port. SQL Server's default is `1433`.

### Username

The SQL Server login Bytebase connects as.

### Password

The login's password. You can also read it from a [secret manager](/get-started/connect/overview#secret-manager-integration).

### Connection database

The database Bytebase connects to when it isn't working in a specific database, such as when it tests the connection or lists databases. If you leave it empty, SQL Server uses the login's default database.

### TLS

<Warning>
  Bytebase doesn't verify the SQL Server certificate yet. It trusts whatever certificate the server presents, the same as `TrustServerCertificate=true`, and the **TLS** settings in the form don't change that. This is a known issue, and a fix is in progress.
</Warning>

By default, only the login is encrypted. To encrypt the whole session, add `encrypt` with the value `true` under **Extra Parameters**, or have the server force encryption. In both cases the session is encrypted, but the server's identity isn't checked. Client certificates aren't available for SQL Server.

### Extra Parameters

Options that Bytebase passes to the driver as key-value pairs, using the [driver's parameter names](https://github.com/microsoft/go-mssqldb#connection-parameters-and-dsn) such as `encrypt`, `multisubnetfailover`, and `applicationintent`. Bytebase sets `TrustServerCertificate` itself, so adding it here fails.

## Availability Groups

Set **Hostname** to the Availability Group listener, not a server name. The listener follows the primary across failovers. Bytebase syncs every database on the server behind the listener, including secondaries of other Availability Groups, so use [Sync Databases](/get-started/connect/overview#sync-databases) to limit the instance to this group's databases.

Under **Extra Parameters**, add `multisubnetfailover` with the value `true` if the group spans subnets. To serve reads from a readable secondary, add `applicationintent` with the value `ReadOnly` on the [read-only connection](/get-started/connect/overview#read-only-connections).

## Troubleshooting

**Test Connection** shows the error from the server or the driver:

| Error | Cause | Fix |
| - | - | - |
| `mssql: login error: Login failed for user '…'.` | The username or password is wrong. | Check the login and its password. |
| `mssql: login error: Cannot open database "…" that was requested by the login.` | **Connection database** doesn't exist, or the login can't open it. | Correct the name, or leave the field empty to use the login's default database. |
| `key TrustServerCertificate provided more than once` | **Extra Parameters** sets `TrustServerCertificate`, which Bytebase already sets. | Remove `TrustServerCertificate` from **Extra Parameters**. |
| `TLS Handshake failed: EOF` | `encrypt` is set to `strict`, and the server doesn't accept strict encryption. | Use `encrypt` with the value `true`. |

## Read-only connection

A [read-only connection](/get-started/connect/overview#read-only-connections) has its own **Extra Parameters**. Set `encrypt` there too if the read-only connection should be encrypted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.