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 (notmaster) and create a user that lives in it:
Option 2: Microsoft Entra ID service principal
- In the Azure portal, open Microsoft Entra ID → App registrations → New registration and register an app (e.g.,
clarityq-user). - From the app’s Overview page, copy the Directory (tenant) ID and the Application (client) ID.
- Under Certificates & secrets, create a New client secret and copy its Value. It is shown once.
- 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. Replaceclarityq_user with [clarityq-user] if you chose Option 2.
master:
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
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
- 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
SELECTstatements 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
- 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
- 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)
- 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
- 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
- Clear the Database field (Azure SQL Managed Instance) to catalogue every database instead of the one you named
- Grant the user
SELECTon the missing schemas
- Add the cancellation grants for your platform (see Step 2)