Docs
Connections

SQL Server

Connect SQL Server 2017+, Azure SQL Database or Azure SQL Managed Instance over verified TLS, with a SQL login or a Microsoft Entra ID service principal.

A SQL Server connection works like PostgreSQL. It connects through a pinned address over verified TLS, reads inside a transaction that is always rolled back, and streams bounded reads. It supports SQL Server 2017 and later, Azure SQL Database, and Azure SQL Managed Instance on its public endpoint.

Availability

SQL Server is not yet generally available on xentropy.ai. Contact support@xentropy.ai to request access. Until it is enabled for your account, it does not appear in the engine list and its reads fail with PROVIDER_DISABLED.

Before you start

  • The server must be reachable on a public hostname (for Azure SQL, <server>.database.windows.net), with a certificate that names that hostname. For a private CA, have the CA certificate ready. Xentropy requires TLS 1.2 or later.
  • Allow the egress IP addresses shown in the form in your firewall. On Azure SQL, add them as server firewall rules.
  • Choose how Xentropy signs in: a SQL login (user and password), or a Microsoft Entra ID (service principal). Windows, NTLM and Kerberos authentication are not supported.

The form shows SQL for a read-only login, filled in with your database name. Replace … with a strong password. For a SQL login:

-- SQL Server, or Azure SQL in the master database: a server login.
CREATE LOGIN xentropy_reader WITH PASSWORD = '…';
-- Then in your database:
CREATE USER xentropy_reader FOR LOGIN xentropy_reader;
GRANT SELECT ON SCHEMA::dbo TO xentropy_reader;
-- VIEW DEFINITION: JSON columns are detected from ISJSON check constraints, which are hidden without this grant.
GRANT VIEW DEFINITION ON SCHEMA::dbo TO xentropy_reader;

On Azure SQL you can use a contained user instead, with no server login. Run it in your database:

CREATE USER xentropy_reader WITH PASSWORD = '…';
GRANT SELECT ON SCHEMA::dbo TO xentropy_reader;
GRANT VIEW DEFINITION ON SCHEMA::dbo TO xentropy_reader;

Repeat both grants for every schema you want to read. VIEW DEFINITION lets Xentropy see the text of ISJSON check constraints. Without it, JSON columns stored as text are read as plain strings instead of being flattened. Do not add the login to db_owner or db_datawriter.

Microsoft Entra ID (service principal)

  1. In the Azure portal, register an app (Microsoft Entra ID → App registrations → New registration), and create a client secret for it. Note the tenant ID, the client ID and the secret.
  2. Make sure the server has a Microsoft Entra administrator. As that administrator, create a user for the app in your database. Use the app registration's display name:
CREATE USER [xentropy-reader-app] FROM EXTERNAL PROVIDER;
GRANT SELECT ON SCHEMA::dbo TO [xentropy-reader-app];
GRANT VIEW DEFINITION ON SCHEMA::dbo TO [xentropy-reader-app];

Xentropy requests a token for https://database.windows.net/.default from login.microsoftonline.com with the client credentials. It sends that token to the server, so the server never sees the secret. Tokens are cached until five minutes before they expire. A rotated secret gets a new token.

Set up the connection

Open Connections, choose New connection, then Database, and choose SQL Server as the engine.
Name the connection. Optionally paste an ADO.NET or JDBC connection string, or a sqlserver:// URL, and choose Fill fields. Pasting a SQL Server string selects the engine for you.
Enter the host, port (default 1433) and database. Choose SQL authentication and enter the username and password, or choose Microsoft Entra ID (service principal) and enter the tenant ID, client ID and client secret. If you use a private CA, paste its certificate.
Set the time zone that your datetime, datetime2 and smalldatetime values are written in (default UTC).
Choose Test and list relations, select the relations to read (up to 100), then choose Save connection.

Relations are listed as schema.table. Discovery lists the tables and views the login can SELECT, excluding sys and INFORMATION_SCHEMA, up to 500. When you save, Xentropy probes every selected relation with SELECT TOP (0). Schema and table names can have up to 128 characters, including dots, spaces and other punctuation, but not ] or a control character. Every name is quoted in brackets in the SQL Xentropy sends. When you type a name with other characters than letters, digits and _, put it in double quotes, for example dbo."sales.2024".

TLS

Every connection is encrypted and the certificate is always verified against the host you entered. Xentropy uses TDS 8.0 strict encryption when the server supports it, and otherwise TLS inside the TDS login. There is no "trust server certificate" option. If Azure SQL redirects the connection to another host, that host is checked against the same network policy before Xentropy connects.

How reads stay read-only

SQL Server has no read-only transaction, so each session runs:

  1. SET TRANSACTION ISOLATION LEVEL READ COMMITTED; SET LOCK_TIMEOUT 5000; SET XACT_ABORT ON; BEGIN TRANSACTION
  2. the generated SELECT TOP (50001) … statements, with bound parameters
  3. IF @@TRANCOUNT > 0 ROLLBACK TRANSACTION, always

Only Xentropy's own SELECT statements and catalog queries are sent. Your read-only grants are the second line of defence.

Type mapping

SQL Server typeDataset type
bitboolean
tinyint, smallint, int, real, floatnumber
bigint, decimal, numeric, money, smallmoneydecimal (exact, as text)
datedate
datetimeoffsetdatetime (UTC)
datetime, datetime2, smalldatetimedatetime, read in the connection's time zone and returned in UTC
json (SQL Server 2025, Azure SQL), or text with an ISJSON([col]) = 1 checkFlattened. A column whose values are all objects becomes dotted fields (up to 4 levels). Text that is not JSON stays a string
time, uniqueidentifier, char, varchar, nchar, nvarchar, text, xml, sql_variantstring
binary, varbinary, image, geography, geometry, hierarchyid, rowversionexcluded

Primary keys and unique indexes on non-null columns become the grain. Foreign keys to other selected relations become relationships. Filters are pushed down for plain columns; an in filter with more than 1,000 values is applied after the read.

Limits

LimitValue
Rows per read50,000
Data per read5 MiB
Readable fields100, including flattened JSON fields
Statement budget25 s (the client cancels the statement)
Read deadline30 s
Connect timeout10 s
Metadata and verification statements10 s
Relations listed / selected500 / 100

An agent reads a SQL Server connection with connections:read or sqlserver:read.

Errors

Test reports the first stage that fails, in this order. The form labels the stage, for example Authentication check failed.

CodeCauseWhat to do
SQLSERVER_DNSThe host does not resolveCheck the spelling, and use the public hostname
SQLSERVER_NETWORK_POLICYThe host, or the host Azure redirected to, resolves to a private or reserved address (403)Use the public endpoint, or ask your administrator to allow it
SQLSERVER_TCPNo connection, or the connection was lost (503)Check the port and firewall rules, and allow the egress IPs
SQLSERVER_TLSThe certificate does not verify for the hostPaste the CA, and check that the certificate names the host
SQLSERVER_AUTHWrong user or password; the database is unknown or not allowed; the login is disabled; or Entra rejected the tenant, client ID or secretCheck the credentials, the database name and the Entra app
SQLSERVER_PERMISSIONA selected table cannot be read, or does not existGrant SELECT, or deselect it
INCOMPLETE_DATAThe relation has more than 50,000 rows, or exceeds 5 MiBSelect a bounded view
LIMIT_EXCEEDEDMore than 100 readable fieldsSelect a view with fewer columns
BUDGET_EXCEEDEDThe query ran past its 25 s statement budgetSelect a smaller or indexed view
PROVIDER_UNAVAILABLEThe metadata read or the read failed for another reasonRetry later, then check connection health

On this page