Skip to main content
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:
On Azure SQL Managed Instance, create a login on the instance, then a user in each database ClarityQ should read:

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:

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.
Grant query cancellation, so stopping a question stops the work on your server. On Azure SQL Database, in the database:
On Azure SQL Managed Instance, in master:
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)