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

# Azure SQL

> Connect Azure SQL to ClarityQ

This connector works with Azure SQL Database and Azure SQL Managed Instance. For Azure Synapse or Microsoft Fabric, contact us.

## Setup

### Step 1: Create a dedicated user for ClarityQ

ClarityQ signs in with one of two methods. Pick the one your server allows: a server set to **Microsoft Entra-only authentication** accepts only the second.

#### Option 1: SQL login

On Azure SQL Database, connect to the database ClarityQ should read (not `master`) and create a user that lives in it:

```sql theme={null}
CREATE USER clarityq_user WITH PASSWORD = 'your_secure_password';
```

On Azure SQL Managed Instance, create a login on the instance, then a user in each database ClarityQ should read:

```sql theme={null}
-- In master
CREATE LOGIN clarityq_user WITH PASSWORD = 'your_secure_password';

-- In each database
CREATE USER clarityq_user FOR LOGIN clarityq_user;
```

#### Option 2: Microsoft Entra ID service principal

1. In the Azure portal, open **Microsoft Entra ID** → **App registrations** → **New registration** and register an app (e.g., `clarityq-user`).
2. From the app's **Overview** page, copy the **Directory (tenant) ID** and the **Application (client) ID**.
3. Under **Certificates & secrets**, create a **New client secret** and copy its **Value**. It is shown once.
4. Connect to the database as its Microsoft Entra admin and create a user for the app, using the app's name:

```sql theme={null}
CREATE USER [clarityq-user] FROM EXTERNAL PROVIDER;
```

### Step 2: Grant database permissions

Configure the required permissions for ClarityQ to discover schemas, query data, and cancel its own queries. Run these in each database ClarityQ should read. Replace `clarityq_user` with `[clarityq-user]` if you chose Option 2.

```sql theme={null}
-- Read access to every table in the database
ALTER ROLE db_datareader ADD MEMBER clarityq_user;

-- Or read access to specific schemas only
GRANT SELECT ON SCHEMA::sales TO clarityq_user;
```

Grant query cancellation, so stopping a question stops the work on your server.

On Azure SQL Database, in the database:

```sql theme={null}
GRANT KILL DATABASE CONNECTION TO clarityq_user;
GRANT VIEW DATABASE STATE TO clarityq_user;
```

On Azure SQL Managed Instance, in `master`:

```sql theme={null}
GRANT ALTER ANY CONNECTION TO clarityq_user;
GRANT VIEW SERVER STATE TO clarityq_user;
```

Without the cancellation grants everything else works, and a query still stops at its time limit.

### Step 3: Configure network access

Ensure your server allows connections from the following ClarityQ IP addresses:

* 44.218.213.75
* 54.161.37.107
* 54.208.212.67

On Azure SQL Database, open your SQL server in the Azure portal, go to **Security** → **Networking**, set **Public network access** to **Selected networks**, and add a firewall rule for each address.

On Azure SQL Managed Instance, enable the public endpoint and allow the addresses in the network security group. The public endpoint uses port `3342`.

### Step 4: Configure connection in ClarityQ

In the ClarityQ interface, choose **Azure SQL** and fill out the connection form with the following fields:

#### Required Fields

* **Connection Name**: Choose a name for this connection (e.g., "Production Azure SQL")
* **Host**: Your server hostname (e.g., `your-server.database.windows.net`)
* **Port**: `1433` (default, pre-filled)

#### Optional Fields

* **Database**: Required on Azure SQL Database, which connects to one database at a time. On Azure SQL Managed Instance, leave it empty to catalogue every database the user can read, or set it to confine ClarityQ to one database (e.g., `analytics`)

#### Authentication Type

Choose your authentication method using the toggle buttons:

**SQL Login Authentication (default):**

* **User**: `clarityq_user` (the user you created in Step 1)
* **Password**: Enter the password you set for `clarityq_user`

**Microsoft Entra ID Authentication:**

* **Tenant ID**: Paste the Directory (tenant) ID of the app registration
* **Client ID**: Paste the Application (client) ID of the app registration
* **Client Secret**: Paste the secret value you created in Step 1

### Step 5: Test the connection

Verify the connection in ClarityQ to ensure:

* Authentication succeeds
* The database is visible to `clarityq_user`
* Table metadata can be discovered
* Query execution works correctly

## How ClarityQ uses the connection

* Every connection is encrypted with TLS.
* ClarityQ runs `SELECT` statements only.
* Table discovery, cataloguing, and questions all run as the user you created, so its grants decide what ClarityQ can see.
* System databases (`master`, `model`, `msdb`, `tempdb`) and system schemas stay out of the catalog.

## Troubleshooting

### Common connection issues

**Connection times out**

* Add the ClarityQ IP addresses to the server firewall or network security group (see Step 3)
* Enter the hostname on its own, with the protocol and port left out of the field

**Login failed**

* On Azure SQL Database, fill in the **Database** field. Without it the server refuses the login even when the credentials are correct
* Check the spelling of the **Database** field. Azure SQL reports a database name that does not exist as a failed login
* Re-enter the password or client secret
* On a server set to **Microsoft Entra-only authentication**, use **Microsoft Entra ID** authentication

**Microsoft Entra ID sign-in fails**

* Check the **Tenant ID** and **Client ID** against the app registration's **Overview** page
* Create a new client secret if the previous one has expired, and paste its **Value**, not its **Secret ID**
* Create the database user for the app (see Step 1, Option 2)

**Certificate error**

* ClarityQ verifies the server certificate. Enter the full hostname Azure shows for your server (e.g., ending in `.database.windows.net`), not an IP address or an alias

**No tables are visible**

* Grant the user read access in the database (see Step 2)
* On Azure SQL Managed Instance, create the user in each database ClarityQ should read

**Tables missing after discovery**

* Clear the **Database** field (Azure SQL Managed Instance) to catalogue every database instead of the one you named
* Grant the user `SELECT` on the missing schemas

**Stopping a question leaves the query running**

* Add the cancellation grants for your platform (see Step 2)


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