Skip to main content

Special cases

TL;DR

On-premises SQL Server via the self-deployed runtime, Windows/NTLM and Entra ID authentication quirks, Azure SQL Managed Instance failover listeners, and estates with many environments and ports.

Connect

On-premises servers behind strict firewalls, Windows/NTLM and Entra ID authentication quirks, Azure SQL Managed Instance failover listeners, and estates with many environments and ports. All of these come from real support history.

On-premises SQL Server - self-deployed runtime​

When the server is reachable only from inside your network (or a partner's network) and no cloud private link is possible, run the extraction inside the network with Atlan's self-deployed runtime (SDR) - a Kubernetes-based agent:

  • Outbound only: the agent opens HTTPS/gRPC connections (port 443) to your Atlan tenant; no inbound firewall hole is needed.
  • Credentials stay home: database credentials live in your secret store (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, ...); Atlan never holds them.
  • Local reach: the agent connects to SQL Server over your LAN on port 1433 (or your custom port), so private DNS names work.
Pitfalls to know before you adopt SDR for SQL Server

Three recurring traps from support history: (1) secret configuration - the workflow form expects bare secret key names (no bracket syntax), the secret store name (not a full ARN), and multi-key secrets require a Dapr setting plus a container recreate (not restart) to take effect; (2) agent build version - if an SDR run hangs for many hours instead of failing fast, ask support whether your agent build is on the current connector framework for SQL Server before debugging your own network; (3) there is currently no SQL Server-specific SDR worked example in the docs - if you get stuck on secret syntax, cite this page on a support ticket.

Also for on-prem: SQL Server may redirect the client to a different host/port (listener, named instance). Firewalls between the agent and the database must allow the redirect target - a real support case saw the initial host allowed and the redirect target blocked, timing out mid-connection.

Windows (NTLM) authentication​

  • Fill the Windows Domain field with the Active Directory domain name (e.g. CORP) - its absence is a recurring cause of "Login failed" with otherwise perfect credentials.
  • NTLM failures and network failures produce similar-looking errors. To separate them, test once with a throwaway SQL-auth login: if SQL auth connects and NTLM doesn't, the network is fine and the problem is domain/credential formatting.
  • NTLM works over direct, private link, and SDR alike - the auth handshake rides inside the TDS connection.

Entra ID service principals against Azure SQL​

Three parts must all exist, and the third is routinely missed:

  1. The app registration in Entra ID (client ID + secret + tenant ID).
  2. Network path - an app registration does not bypass the firewall; Atlan's IPs/CIDR must still be allowlisted.
  3. A database user for the principal: CREATE USER [app-name] FROM EXTERNAL PROVIDER plus GRANT VIEW DEFINITION, per database - see Phase 3 of the direct guide.

Azure SQL Managed Instance and failover groups​

  • Each Managed Instance needs its own private endpoint - including each member of a failover group. Provide all Resource IDs and the failover-group listener FQDN in your intake ticket.
  • The MI private endpoint targets a specific subresource; if the first connection through a fresh endpoint fails, ask support to verify the endpoint's target group ID and the DNS record on Atlan's side - both have been root causes in real multi-call support cases.
  • IP allowlisting does not apply to MI private-endpoint traffic - don't wait on firewall changes that can't help.

Many hosts, many environments, many ports​

  • Each SQL Server host is its own Atlan connection - batch your intake: one support ticket listing every host, port, environment, and hostname, clearly labeled. Piecemeal tickets multiply round-trips.
  • Verify hostnames character-by-character against what the DBA publishes; several "unreachable server" cases ended as typos in supplied hostnames.
  • Expect the failure pattern to be per-environment: hosts behind one firewall all work, hosts behind another all fail. That pattern itself tells you which firewall to fix.

Cross-region and cross-cloud​

Your Atlan tenant does not need to share a region or cloud with SQL Server - but private link components generally must be in compatible regions/AZs, and cross-region security-group rules are on you. State both regions in your intake ticket so Atlan builds its endpoint in the right place. And remember: a second tenant in a different region has different egress IPs - the same database can crawl from one tenant and fail from another for exactly this reason.

SQL Server on Google Cloud​

There is no documented Private Service Connect path for Cloud SQL for SQL Server today. The supported private option is the self-deployed runtime (above); if the database has a public endpoint, the direct guide applies.