Azure SQL Database¶

Connect Datahub to an Azure SQL Database or Managed Instance and query it with insight cards, metrics and flows — using an Entra ID service principal or SQL authentication.

ServerAzure SQL Database · Managed Instance

AuthEntra service principal · SQL authentication

TransportTDS 1433 · encrypted

PowersInsights · Metrics · Flows

What it powers¶

Use the Azure SQL integration when operational data lives in an Azure SQL database and you want to read it from inside Datahub without copying it anywhere first.

Insight cards & dashboards

Build cards that query the database directly, alongside your Databricks, Fabric and catalog-backed cards.
Metrics

Point a metric definition at a table and let the metric builder browse schemas, tables and columns to find it.
Flows

Read query results inside a flow step, so a process can branch on what the database says.
Schema & table browsing

Walk database → schema → table → column from the builders, so a query points at a real column rather than a guessed one.

What this connection does not do

No writes, ever. Every statement is checked before it leaves Datahub and anything that is not read-only is refused.
No alerts yet. The alert evaluator does not support this connection type. It will not appear in the alert builder.
No AI agent tools yet. Agents cannot query this connection over MCP.
One database per connection. Register a second integration to reach another database on the same server.

How the connection works¶

Datahub connects to one database over TDS on port 1433, authenticating either as an Entra ID service principal or as a database user. The same connection then backs every query surface.

flowchart LR
    A[Insight cards] --> D[Datahub connection]
    B[Metrics] --> D
    C[Flows] --> D
    D -->|TDS 1433, encrypted| E[(Azure SQL database)]

Choosing an authentication method¶

	Entra ID service principal	SQL authentication
Where the credential lives	Azure	Inside the database
Rotating it	In Azure, without touching the database	Change the password on the database
Best when	Your organisation uses Entra	Entra is not in use, or the database is standalone

Both connect over the same protocol and port, so the server firewall has to allow Datahub either way.

Prerequisites¶

The fully qualified server name, ending in .database.windows.net.
The name of the database to query.
Permission to create a database user, or someone who can.
For a service principal: permission to register an application in Entra ID.

Setup¶

1. Copy the server name¶

In the Azure portal, open SQL databases → your database. The overview page shows the server name. Copy it without a port number. The database name is on the same page.

2a. Entra ID service principal¶

Register the application and create a secret:

Microsoft Entra ID → App registrations → New registration. Give it a name and register it.
Copy the Application (client) ID and the Directory (tenant) ID from the overview page.
Certificates & secrets → New client secret. Choose an expiry and copy the value.

The secret value is shown once

Copy it before leaving the page. If you lose it, create another; you cannot read it back.

Then create the database user, connected to your database as an administrator:

CREATE USER [your-app-name] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [your-app-name];

2b. SQL authentication¶

Connected to your database as an administrator:

CREATE USER [datahub_ro] WITH PASSWORD = 'choose-a-strong-one';
ALTER ROLE db_datareader ADD MEMBER [datahub_ro];

db_datareader is enough

Datahub refuses any statement that is not a read before it leaves, so no write role is needed. Granting one adds risk and buys nothing.

3. Open the firewall¶

In the Azure portal, open the SQL server → Networking and add a rule for the address Datahub connects from. Without it the connection test times out even when every credential is correct.

4. Add the integration in Datahub¶

Go to Admin → Integrations, choose Azure SQL Database, and fill in:

Field	What to enter
Name	Anything you will recognise later
Server name	`yourserver.database.windows.net`, no port
Database	The database to query
Authentication method	Entra ID service principal, or SQL authentication
Tenant ID / Client ID / Client secret	Entra only — the three values from step 2a
Username / Password	SQL authentication only — the user from step 2b

5. Save, then test¶

Save the integration first. The connection test runs against the stored credentials, so it becomes available on the settings page once the integration exists.

A successful test names the login it authenticated as. If you own several service principals, that is how you confirm it connected as the one you meant.

Private-network servers¶

If the server sits behind a private endpoint, Datahub will not reach it unless you say so.

By default a connection is refused when the address resolves to a private, loopback or link-local network — on every path, not just the connection test. The refusal says so explicitly rather than reporting an unreachable host.

To allow it, open the integration and turn on Network access → Allow private-network hosts. It saves as soon as you switch it.

Supported features¶

Feature	Supported
Insight cards and dashboards
Metrics
Flows (read a query result)
Schema, table and column browsing
Alerts	not yet
AI agent tools (MCP)	not yet
Writing to the database	by design

Limitations¶

One database per connection. The database is part of the connection, not part of the query.
Read-only. Statements that are not reads are refused before they leave Datahub.
Results are capped at 10,000 rows.
Queries are stopped after 50 seconds. If one is cut off, narrow it with a filter or aggregate in the database.
Alerts and agents are not wired up yet. The connection will not appear in the alert builder or in agent tools.

Troubleshooting¶

What you see	What it usually means
Authentication failed (SQLSTATE 28000)	The server rejected these credentials. For a service principal, check the database user was created `FROM EXTERNAL PROVIDER`.
Connected, but the login lacks permission (SQLSTATE 42000)	It connected but cannot read. Add it to `db_datareader`.
Could not reach the server (SQLSTATE 08001 / HYT00)	The address, the port, or the server firewall. Start with step 3.
Entra ID service principal requires a tenant ID, client ID and secret	One of the three is missing. Nothing was contacted.
This query ran longer than the 50-second limit and was stopped	The statement exceeded the platform limit. Narrow it with a filter, aggregate in the database, or reduce the range.
This connection points at a host on a private network	Datahub declined on purpose. See Private-network servers. Your firewall is not the issue.