Skip to main content
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.

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.
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:

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.

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.

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.

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

TLS mode decides whether Bytebase encrypts the connection:
  • Disabled: Bytebase leaves encryption to the driver and the server. 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. The server’s identity isn’t checked either way.
  • TLS: Bytebase encrypts the whole session. To require TDS 8.0 strict encryption, add encrypt with the value strict under Extra Parameters.
  • Mutual TLS isn’t available for SQL Server.
Under Server identity, turn on Verify server certificate so that Bytebase checks the server’s certificate chain and confirms that Hostname is one of the names in it. CA certificate source sets which certificate authority (CA) the check trusts:
  • System trust: the CAs that the machine running Bytebase already trusts.
  • Paste PEM: a CA certificate you paste in PEM format, for a private CA or a self-signed certificate.
  • File path: a CA certificate file on the Bytebase server. Not available in Bytebase Cloud.
With verification off, the connection is encrypted, but Bytebase doesn’t check which server it reached. Use that only for testing.

Extra Parameters

Options that Bytebase passes to the driver as key-value pairs, using the driver’s parameter names such as encrypt, multisubnetfailover, and applicationintent. With TLS mode set to TLS, the TLS section is a floor that these parameters can raise but not lower: encrypt can be set to strict but not turned off, and TrustServerCertificate with the value false turns verification on even when Verify server certificate is off. With TLS mode set to Disabled, the parameters apply as given, with TrustServerCertificate defaulting to true.

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 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.

Troubleshooting

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

Read-only connection

A read-only connection has its own Extra Parameters. Set encrypt there too if the read-only connection should be encrypted.