---
title: "MSSQL"
slug: "mssql"
updated: 2026-07-28T15:53:33Z
published: 2026-07-28T15:53:33Z
canonical: "help.hyperscience.ai/mssql"
---

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

# MSSQL

Hyperscience supports the following implementations of MSSQL:

- **On premise**
  - For a list of supported MSSQL versions, see [Infrastructure Requirements (Production)](/deployment/docs/infrastructure-requirements).
- **Azure SQL Managed Instance**
  - Supported in Hyperscience v28 and later
  - To learn more, see Microsoft’s [What is Azure SQL Managed Instance?](https://docs.microsoft.com/en-us/azure/azure-sql/managed-instance/sql-managed-instance-paas-overview)
  - For information on how to create a managed instance, see Microsoft’s [Quickstart: Create an Azure SQL Managed Instance](https://docs.microsoft.com/en-us/azure/azure-sql/managed-instance/instance-create-quickstart).
    - Because Azure SQL Database does not support Servicer Broker, Hyperscience **does not support Azure SQL Database**.

## Configuring MSSQL

To configure MSSQL for your Hyperscience instance, follow these steps.

<editor360-custom-block data-preprocessing="true" data-sanitizationtags="a"><h3 data-block-id="06f96569-2b4c-429a-8244-120cb39f72b8"><a name="step1" display="false"></a><span type="spanMark">1. Create your database with case-sensitive collation.</span></h3></editor360-custom-block>

Microsoft SQL Server defaults to case-insensitive collation. Hyperscience requires the MSSQL database (*FORMS_DB_NAME* in the example configuration below) to be created with case-sensitive collation.

```sql
CREATE DATABASE [<FORMS_DB_NAME>] COLLATE SQL_Latin1_General_CP1_CS_AS
```

<editor360-custom-block data-preprocessing="true" data-sanitizationtags="a"><h3 data-block-id="08ff93f3-0d56-4f52-9f63-d6e652606e9d"><a name="step2" display="false"></a><span type="spanMark">2. Configure the isolation level.</span></h3></editor360-custom-block>

The isolation level of the database should be set to *READ_COMMITTED_SNAPSHOT* with the following command:

```sql
ALTER DATABASE [<FORMS_DB_NAME>] SET READ_COMMITTED_SNAPSHOT ON WITH ROLLBACK IMMEDIATE
```

<editor360-custom-block data-preprocessing="true" data-sanitizationtags="a"><h3 data-block-id="13d0457e-f9b5-4423-a600-282d3a209682"><a name="step3" display="false"></a><span type="spanMark">3. Enable Service Broker.</span></h3></editor360-custom-block>

> [!NOTE]
> **Does not apply to Azure SQL Managed Instance**
> 
> If you are using Azure SQL Managed Instance, Service Broker is enabled by default and cannot be disabled.

If you are using MSSQL on premise, enable Service Broker with the following command:

```sql
ALTER DATABASE [<FORMS_DB_NAME>] SET ENABLE_BROKER WITH ROLLBACK IMMEDIATE
```

To automatically apply the *ALTER* statement for both the isolation level and Service Broker, add the following to the “.env” file:

```sql
SQLSERVER_SKIP_DB_INITIALIZATION=false
```

However, please note that doing so may cause deployment failure in some cases.

<editor360-custom-block data-preprocessing="true" data-sanitizationtags="a"><h3 data-block-id="7e48a5a7-cd8a-4b1b-80f2-bbef7bcd3532"><a name="step4" display="false"></a><span type="spanMark">4. Create a SQL Server user for Hyperscience.</span></h3></editor360-custom-block>

You can connect Hyperscience to SQL Server in one of the following ways:

- Using SQL Server login credentials.
- In v32.0.4 and later, using an Azure Active Directory (Azure AD) domain user and password to connect to Azure SQL Server Managed Instance service.
- In v32.0.4 and later, using an Azure Directory Federation Services (ADFS) domain user and password to connect to Azure SQL Server Managed Instance service.

The user you create for Hyperscience must have the following permissions:

- *ALTER DATABASE* permissions
- *VIEW SERVER STATE* permissions
- *ALTER ANY CONNECTION* permissions

Adding the *VIEW SERVER STATE* and *ALTER ANY CONNECTION* permissions allows us to monitor and periodically clean up any unnecessary database sessions that may be preventing submissions in Hyperscience from processing in a timely manner.

<editor360-custom-block data-preprocessing="true" data-sanitizationtags="a"><h3 data-block-id="f171e848-8edd-41b6-8cb2-dcea3cdca14e"><a name="step5" display="false"></a><span type="spanMark">5. Configure <em>SQLSERVER_OPTIONS_EXTRA_PARAMS </em>parameter<em>.</em></span></h3></editor360-custom-block>

The *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter allows you to configure the following options:

- Enable Always On availability groups:

```plaintext
MultiSubnetFailover=Yes
```
- Use a domain user for authentication:

```plaintext
Authentication=ActiveDirectoryPassword
```
- [v41 and earlier] Configure TLS

```plaintext
Encrypt=Yes
```
- [v42 and later] Disable TLS

```plaintext
Encrypt=No
```
- Add certificate information:

```plaintext
TrustServerCertificate=Yes
```

You need to add the *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter to the “.env” file. You can delimit multiple options by using a semicolon. The options’ order does not matter.

Here is an example of defining multiple options:

```plaintext
SQLSERVER_OPTIONS_EXTRA_PARAMS=Authentication=ActiveDirectoryPassword;MultiSubnetFailover=Yes
```

In the sections below, you can find more information about each of the above-mentioned options.

#### a. Enable Always On availability groups.

If using Always On availability groups, ensure Service Broker is enabled, and add the *MultiSubnetFailover=Yes* option to the *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter.

Here is an example of adding the *MultiSubnetFailover=Yes* option to the *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter:

```plaintext
SQLSERVER_OPTIONS_EXTRA_PARAMS=MultiSubnetFailover=Yes
```

#### b. Use a domain user for authentication.

To use a domain user for authentication, you need to add the *Authentication=ActiveDirectoryPassword* option to the *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter.

Here is an example of adding the *Authentication=ActiveDirectoryPassword* option to the *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter:

```plaintext
SQLSERVER_OPTIONS_EXTRA_PARAMS=Authentication=ActiveDirectoryPassword
```

Azure AD users are created and managed directly within the Azure Active Directory cloud service, whereas ADFS federates an on-premise Active Directory instance to Azure Active Directory.

> [!NOTE]
> Note that Azure Active Directory federation through PingFederate is not supported. To learn more about PingFederate, see Microsoft’s [Configuring federation with PingFederate](https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-install-custom#configuring-federation-with-pingfederate).

#### c. [v41 and earlier] Configure TLS.

In order to enable TLS in v41 and earlier, TLS must be configured for your server. You also need to add the *Encrypt=Yes* option to the *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter.

Here is an example of adding the *Encrypt=Yes* option to the *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter:

```plaintext
SQLSERVER_OPTIONS_EXTRA_PARAMS=Encrypt=Yes
```

#### d. [v42 and later] Disable TLS.

In v42 and later, the database connection uses TLS encryption by default. This change is due to the upgrade of the ODBC driver to v18. For more information, see Microsoft’s [ODBC DSN and Connection String Keywords and Attributes](https://learn.microsoft.com/en-us/sql/connect/odbc/dsn-connection-string-attribute?view=sql-server-ver16#encrypt).

To disable TLS, do **one** of the following:

- Have a server certificate signed and issued by a trusted Certificate Authority (CA) in your database server.
- Have a self-signed server certificate in your database server and set the *TrustServerCertificate* parameter in *SQLSERVER_OPTIONS_EXTRA_PARAMS* to *Yes* (see [e. Add certificate information](/deployment/docs/mssql#e-add-certificate-information)). (Not recommended due to reduced security)
- Set the *Encrypt* parameter in *SQLSERVER_OPTIONS_EXTRA_PARAMS* to *No* (Not recommended due to reduced security):

```plaintext
SQLSERVER_OPTIONS_EXTRA_PARAMS=Encrypt=No
```

#### e. Add certificate information.

If you're using a self-signed certificate, you can configure your authentication process to trust the certificate without validating it. To do so, add the *TrustServerCertificate=Yes* option to the *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter.

Here is an example of adding the *TrustServerCertificate=Yes* option to the *SQLSERVER_OPTIONS_EXTRA_PARAMS* parameter:

```plaintext
SQLSERVER_OPTIONS_EXTRA_PARAMS=Encrypt=Yes;TrustServerCertificate=Yes
```

<editor360-custom-block data-preprocessing="true" data-sanitizationtags="a"><h3 data-block-id="fd568a80-a509-400a-9bb8-ce2b4bd01d96"><a name="step6" display="false"></a><span type="spanMark">6. Add MSSQL variables.</span></h3></editor360-custom-block>

The following variables should also be included in the “.env” file:

```bash
FORMS_DB_TYPE=mssql
FORMS_DB_NAME=<name_of_database_from_Step_1>
FORMS_DB_USER=<username_of_user_created_in_Step_5> <<If you’re using an Azure AD or 
ADFS user, you need to include the user’s domain after the username. (e.g., james@example.com)>>
FORMS_DB_PASS=<password_of_user_created_in_Step_5>
FORMS_DB_HOST=<host_URL>
FORMS_DB_PORT=<port>
```

> [!NOTE]
> In v32 and later, you can choose to store your system-level credentials in a secrets manager. To learn more about our secrets-management integration, see [Secrets Management](/deployment/docs/secrets-management).

Proactively set up transaction logs and monitor the amount of disk space the logs are using. If you've configured your SQL Server's recovery model with *recovery_model=full* (see Microsoft's [Recovery Models (SQL Server)](https://docs.microsoft.com/en-us/sql/relational-databases/backup-restore/recovery-models-sql-server?view=sql-server-ver15)), the size of the transaction logs can grow indefinitely unless you take action to periodically shrink them. To learn more about shrinking the log file's size, see Microsoft's [Manage the size of the transaction log file](https://docs.microsoft.com/en-us/sql/relational-databases/logs/manage-the-size-of-the-transaction-log-file?view=sql-server-ver15).