Skip to main content

ArpeMSSQL — Connection guide

Everything you can put in front of ArpeMSSQL to point it at a SQL Server, in one place: the three ways to supply connection details, every option the driver accepts, and the SQL Server-specific rules (named instances, Azure SQL / Fabric, Entra ID).

For integrated authentication (Windows SSPI or Kerberos on Linux), see Authentication. For the licence, see Licensing.


Three ways to connect​

Every driver in the Arpeio family accepts the same three connection forms. They can be mixed; a discrete option always wins over the same field taken from a connection_string or a uri, regardless of the order they are set.

FormOption keyGrammarBest for
Discrete optionsadbc.arpemssql.<field>one option per fieldprogrammatic clients, secrets kept out of a single string
Connection stringadbc.arpemssql.connection_string (alias connection_string)ADO.NET Key=Value;…pasting an existing SQL Server / SqlClient string
Connection URIurisqlserver://… URLportable tooling, copy-paste from go-mssqldb/ADBC tools
Python
import adbc_driver_manager.dbapi as dbapi

# Discrete options
conn = dbapi.connect(driver="arpemssql", db_kwargs={
"adbc.arpemssql.server": "localhost",
"adbc.arpemssql.database": "tpch",
"adbc.arpemssql.username": "sa",
"adbc.arpemssql.password": "<password>",
"adbc.arpemssql.encrypt": "true",
"adbc.arpemssql.trust_server_cert": "true",
})

# Connection string
conn = dbapi.connect(driver="arpemssql", db_kwargs={
"adbc.arpemssql.connection_string":
"Server=localhost;Database=tpch;User ID=sa;Password=<password>;"
"Encrypt=true;TrustServerCertificate=true",
})

# Connection URI
conn = dbapi.connect(driver="arpemssql", db_kwargs={
"uri": "sqlserver://sa:<password>@localhost:1433/"
"?database=tpch&encrypt=true&TrustServerCertificate=true",
})

Precedence: a field parsed from connection_string/uri is applied only if no discrete adbc.arpemssql.* option already set it.


Option reference​

All options are string-typed and live under the adbc.arpemssql.* namespace (a few also accept a short bare alias, noted below). Set them as ADBC database options before the connection is opened. Statement/ingest options are set on the statement — see Statement & ingest options.

Every boolean option, at database, connection or statement level, takes true/false, yes/no or 1/0 in any case, and refuses any other value with INVALID_ARGUMENT (the option keeps its previous value). Keywords in a connection_string are parsed case-insensitively (see Connection string).

Version

Since ArpeMSSQL v0.7.2. Before, database options were case-sensitive, and some connection and statement booleans read an unknown value as false without an error.

Target — where to connect​

OptionAliasDefaultMeaning
adbc.arpemssql.serverhostname—Host, host,port / host:port / [::1]:port, ./(local) (→ localhost), or a named instance host\INSTANCE. See Named instances.
adbc.arpemssql.portport1433TCP port, 1..65535. Ignored for a named instance unless given explicitly.
adbc.arpemssql.databasedatabaseserver defaultInitial database.
adbc.arpemssql.app_nameapp_namedriver defaultProgram name reported to the server (sys.dm_exec_sessions.program_name).
adbc.arpemssql.application_intent—ReadWriteReadOnly / ReadWrite (any case; anything else → INVALID_ARGUMENT). Since v0.6.7. ReadOnly declares a read-only workload at login, so an Availability Group listener with read-only routing sends the connection to a readable secondary. See Read-only routing.

Authentication​

Full method-by-method detail is in Authentication; the cloud/Entra options are described under Azure SQL, Microsoft Fabric & Entra ID.

OptionValuesMeaning
adbc.arpemssql.username / .passwordstringSQL-authentication credentials (aliases username / password).
adbc.arpemssql.trusteda boolean, or sspi (= true), any caseIntegrated auth: Windows SSPI, or Kerberos on Linux, no username/password. Alias trusted.
adbc.arpemssql.auth_typesql/SqlPassword, integrated/sspi/trusted, ActiveDirectoryDefault/defaultSelects the auth mode explicitly. Other ActiveDirectory* values return NOT_IMPLEMENTED with a pointer to the supported options. Setting access_token, client_secret or managed_identity selects Entra auth on its own.
adbc.arpemssql.krb5.keytabpathKerberos (Linux): keytab for integrated auth.
adbc.arpemssql.krb5.ccachepathKerberos (Linux): credential cache.
adbc.arpemssql.krb5.principalnameKerberos (Linux): client principal.
adbc.arpemssql.krb5.passwordstringKerberos (Linux): password used to obtain a ticket (password-based Kerberos).
adbc.arpemssql.krb5.spnSPNIntegrated auth: override the derived service principal name (MSSQLSvc/host:port). See SPN.
adbc.arpemssql.require_kerberosa boolean (default false)Since v0.7.6. Windows integrated auth: refuse a login that falls back to NTLM, so only Kerberos (which also authenticates the server) is accepted. No effect on Linux. See NTLM fallback.
Version

Kerberos integrated authentication on Linux, and the krb5.keytab, krb5.ccache, krb5.principal and krb5.password options, since ArpeMSSQL v0.7.5. The Linux driver loads the system's MIT Kerberos libraries at the first Kerberos login; on a host without them only a Kerberos login fails, with a message naming the package to install (krb5-libs or libgssapi-krb5-2).

Encryption / TLS​

OptionDefaultMeaning
adbc.arpemssql.encryptlogin-onlytrue/false (also 1/0, yes/no, SqlClient's Mandatory/Optional). true encrypts the whole session (TLS 1.2+, SNI, cert + hostname verification). Azure SQL requires true. Strict = tds_version=8.0.
adbc.arpemssql.tds_version7.48.0 (or 8): TDS 8.0 strict encryption, see Strict encryption (TDS 8.0).
adbc.arpemssql.trust_server_certfalsetrue skips server-certificate/hostname verification (self-signed dev servers). Leave false in production.
adbc.arpemssql.tls_ca_file—Path of a PEM file of CA certificates trusted in addition to the system store: a private CA, or the server's own self-signed certificate.
adbc.arpemssql.host_name_in_certificatethe server hostName (or IP address) the server certificate must carry, when it differs from the host you connect to (an alias, a load balancer, a self-signed SSL_Self_Signed_Fallback certificate).
adbc.arpemssql.allow_cleartext_loginfalsePermit the credentials-in-cleartext login exchange when encryption is off.
Version

tls_ca_file and host_name_in_certificate since ArpeMSSQL v0.7.0; tds_version, Encrypt=Strict and Mandatory/Optional since ArpeMSSQL v0.7.5.

With encrypt=true and trust_server_cert=false the server certificate and hostname are verified by default; an IP-literal host is checked against the certificate's iPAddress SAN.

The certificates trusted are the operating system's: on Windows, the machine's trusted root store; on Linux, the distribution's CA bundle (the first found of /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem, /etc/pki/tls/certs/ca-bundle.crt, /etc/ssl/certs/ca-certificates.crt, /etc/ssl/ca-bundle.pem, /etc/ssl/cert.pem). On Linux, setting SSL_CERT_FILE or SSL_CERT_DIR replaces that bundle. The same store verifies the Entra ID sign-in service (login.microsoftonline.com) when the driver fetches a token. To verify a server whose certificate is not publicly trusted, rather than turning verification off, trust its CA (or the certificate itself) with tls_ca_file, and set host_name_in_certificate if the certificate names a different host:

Encrypt=true;ServerCertificate=/etc/ssl/corp-ca.pem;HostNameInCertificate=sql.corp.example
Version

The operating system's trusted CAs are used since ArpeMSSQL v0.7.3. Before, on RHEL / Rocky 8, encrypt=true needed trust_server_cert=true and Entra ID sign-in failed with "unable to get local issuer certificate".

See Authentication → TLS for what is encrypted in each mode and the TLS version floor.

Strict encryption (TDS 8.0)​

Version

Since ArpeMSSQL v0.7.5.

A server with Force Strict Encryption on (SQL Server 2022+ and Azure SQL; network.forcestrict on Linux) refuses the TDS 7.4 login, where TLS is negotiated inside the cleartext PRELOGIN. tds_version=8.0 (or Encrypt=Strict, the SqlClient / ODBC 18 / JDBC spelling) connects to it:

  • the TLS handshake comes first, on the TCP connection, offering ALPN tds/8.0 and SNI; PRELOGIN and LOGIN7 then travel inside TLS (1.2 or 1.3);
  • the server certificate is always verified: trust_server_cert=true is refused, as Microsoft's drivers ignore TrustServerCertificate there. For a private CA or a self-signed certificate, trust it with tls_ca_file (ServerCertificate), and set host_name_in_certificate if it names another host;
  • encryption is implied, so encrypt does not apply.

A server that does not enforce strict encryption accepts it too, if its certificate verifies. With the default 7.4, a failed PRELOGIN points to tds_version=8.0.

Server=sql.corp.example;Database=mydb;Encrypt=Strict;ServerCertificate=/etc/ssl/corp-ca.pem
SpellingValues
adbc.arpemssql.tds_version7.4 (default), 8.0 / 8
Connection string TDS Version, TDSVersionsame
Connection string / option Encrypt=Strict= 8.0 (conflicts with TDS Version=7.4)
URI ?tds_version=8.0, ?encrypt=strictsame

GetOption("adbc.arpemssql.tds_version") reads back 7.4 or 8.0, and the uri read-back carries tds_version=8.0 when set.

Cloud / Entra ID (Azure SQL & Microsoft Fabric)​

OptionMeaning
adbc.arpemssql.access_tokenCaller-supplied Entra ID bearer token (passthrough).
adbc.arpemssql.tenant_id / .client_id / .client_secretService principal; the driver acquires a token via OAuth2 client credentials at connect.
adbc.arpemssql.managed_identitytrue/system (system-assigned) or a user-assigned identity's client id; the driver acquires the token from the Azure host, no secret.

See Azure SQL, Microsoft Fabric & Entra ID.

Timeouts & performance​

OptionDefaultMeaning
adbc.arpemssql.login_timeout30TCP connect budget in seconds (0 = the default, 30). When a host resolves to several addresses they share this budget, so one dead address cannot stall the connect.
adbc.arpemssql.query_timeout0Longest a read or write waits on a silent server, in seconds (0 = no limit). It applies to each wait, not to the whole query, so a long result that keeps streaming never times out. On expiry the driver cancels the query with ATTENTION, as Cancel does, and the call fails with ADBC_STATUS_TIMEOUT (a result stream with ETIMEDOUT); the connection keeps its session, open transaction and #temp tables. If the server then stays silent for 5 s (or query_timeout, if shorter), or the wait is outside a query (login, bulk load), the connection is reset on next use instead, which loses an open transaction. Can also be changed on an open connection, as adbc.arpemssql.query_timeout (string) or query_timeout (string or integer).
adbc.arpemssql.buffer_size32000Rows per streamed Arrow batch (per connection); also the default statement batch_size. Capped at 10,000,000 (larger values are clamped with a warning). The driver auto-flushes early if a wide utf8/binary column would cross Arrow's 2 GiB offset limit, so large values are safe.
adbc.arpemssql.packet_size8192TDS network packet size requested at login (the server may answer with its own). 0 = the driver default (8192); otherwise 512..32767 (MS-TDS spec maximum). Bulk ingest on its own session (autocommit on, non-#temp target) requests 32767 instead when no size is set; a size set here or as Packet Size in the connection string applies to ingest too.
Version

query_timeout cancels the query with ATTENTION, keeping the connection, since ArpeMSSQL v0.7.2 (it has applied to queries since v0.7.0). The 32767-byte ingest packet size is the default since ArpeMSSQL v0.7.2.

Type rendering (read path)​

OptionValuesMeaning
adbc.arpemssql.uuid_casinglower (default) / upper (also lowercase / uppercase)Hex case of uniqueidentifier/GUID values rendered to Arrow utf8. lower matches RFC 4122 and the mssql connection type.
adbc.arpemssql.geospatialgeoarrow (default) / wkb / varbinaryHow geometry/geography (CLR UDT) columns are read. See Geospatial types.
adbc.arpemssql.timestamp_precisionmicrosecond (default, also micro / us) / nanosecond (also nano / ns)Since v0.6.2. Max Arrow precision for scale-7 DATETIME2/DATETIMEOFFSET/TIME. microsecond caps at µs (Parquet TIMESTAMP_MICROS, Spark-friendly); nanosecond keeps full 100 ns resolution. Scales 0–6 unaffected. See Temporal types.

Ingest SRID (write path)​

Version

Since ArpeMSSQL v0.5.25.

OptionDefaultMeaning
adbc.arpemssql.ingest.sridunset (-1)SRID stamped into geometry/geography values written on the Arrow WKB → UDT ingest path, for columns whose GeoArrow crs metadata does not give one (a crs on the column takes precedence). Must be an integer >= -1. When unset, such columns get the kind default (geometry 0, geography 4326). See Write path.

Licence​

OptionMeaning
arpeio.adbc.licenseLicence blob, inline.
arpeio.adbc.license_filePath to a .lic file.
arpeio.adbc.license.statusRead-only (GetOption); reports <state>;code=<ARROW_LIC_*>;tier=<tier>;expires=<epoch>.

The driver also reads the shared ARPEIO_ADBC_LICENCE[_FILE] environment variables and an arpeio_adbc.lic file next to the library. Full resolution order in Licensing.

Standard ADBC connection options​

These use the ADBC-standard keys (no arpemssql namespace):

OptionValuesMeaning
adbc.connection.autocommittrue (default) / falseAutocommit mode. Accepted as a database option or on an open connection. With false, a bulk ingest runs inside your open transaction and is kept or undone by commit / rollback; with true, each ingest is its own transaction (see arpemssql.bulk_atomic).
adbc.connection.catalogdatabase nameSwitches the current database (USE [db] on the open session; with no session yet, validated by a test login). Empty is rejected.
adbc.connection.db_schemaschema nameChecked with SCHEMA_ID(...) (missing schema → NOT_FOUND) and stored client-side: SQL Server has no per-session default schema. Empty is rejected.
adbc.connection.transaction.isolation_levelread_uncommitted / read_committed / repeatable_read / snapshot / serializable / defaultValues take the adbc.connection.transaction.isolation. prefix. Maps to SET TRANSACTION ISOLATION LEVEL; survives an internal reconnect. .linearizable → NOT_IMPLEMENTED (no SQL Server equivalent); any other value → INVALID_ARGUMENT.
adbc.connection.readonlyfalse / 0Accepted as a no-op; true/1 → NOT_IMPLEMENTED (SQL Server has no session read-only mode).

catalog, db_schema, isolation_level and readonly are connection options (set on the open connection), not database options.

Statement & ingest options​

Set on the statement handle, not the database:

OptionDefaultMeaning
adbc.arpemssql.batch_sizebuffer_size (32000)Rows per Arrow batch for this statement, 1..max_batch_size. Defaults to the database's adbc.arpemssql.buffer_size.
adbc.arpemssql.max_batch_size1000000Upper bound for batch_size; must be >= the current batch_size.
adbc.ingest.target_table—Target table for adbc_ingest (bulk load via INSERT BULK).
adbc.ingest.modecreateadbc.ingest.mode.create / .append / .replace / .create_append (the short forms create, append, … also match).
adbc.ingest.target_catalog—Target database for ingest.
adbc.ingest.target_db_schema—Target schema for ingest.
adbc.ingest.temporaryfalsetrue/1 ingests into a session temp table (#name).

Bulk-insert options​

Set on the statement before adbc_ingest. Booleans take true/false, yes/no or 1/0, in any case; any other value is refused with INVALID_ARGUMENT. The options that existed before the bulk_* names also accept their older bcp_ spelling (e.g. arpemssql.bulk_tablock == arpemssql.bcp_tablock). That alias list is frozen: the newer options (bulk_atomic, bulk_order) have no bcp_ spelling and none will be added. All of them can be read back with GetOption. The defaults favour load speed, matching SQL Server's BULK INSERT fast-load behaviour.

OptionAliasDefaultMeaning
arpemssql.bulk_tablockarpemssql.bcp_tablocktrueTABLOCK hint. On a heap with no index it takes a bulk-update (BU) table lock, and it is needed for minimal logging. On an indexed table it is an exclusive table lock. false takes row locks instead (no minimal logging).
arpemssql.bulk_batch_sizearpemssql.bcp_batch_size1000000Rows per sub-batch sent to the server, 1..100000000.
arpemssql.bulk_atomic—falseWith autocommit=true, false commits each sub-batch on its own, so the transaction log never has to hold the whole load. On failure the earlier sub-batches stay committed and nothing of the failing one is kept; a failed replace keeps the old table (the load goes to a staging table, arpemssql_staging_<hex>, which replaces it in one short transaction at the end), and a failed create drops the table it created. true runs the whole ingest, DDL included, as one transaction, so a failure leaves the table as it was, but the log must hold the whole load. Ignored with autocommit=false, where the ingest runs inside the caller's transaction behind a savepoint.
arpemssql.bulk_keep_identityarpemssql.bcp_keep_identitytruetrue loads the source's values into the target's IDENTITY column, so a copied table keeps its keys. false leaves the column out of the load, so the server numbers the rows and any source values for it are ignored. A source without the IDENTITY column is numbered by the server either way. Not for temporary (#) tables: there an IDENTITY column must be left out of the source.
arpemssql.bulk_check_constraintsarpemssql.bcp_check_constraintsfalseEnforce CHECK/FK constraints during load (off = faster).
arpemssql.bulk_fire_triggersarpemssql.bcp_fire_triggersfalseFire INSERT triggers during load (off = faster).
arpemssql.bulk_keep_nullsarpemssql.bcp_keep_nullstrueKeep source NULLs instead of applying column DEFAULTs.
arpemssql.bulk_order——ORDER hint: the order the data is already sorted in, as col [ASC|DESC], ... (columns of the load; [bracket] names with spaces or commas; an IDENTITY column only with bulk_keep_identity=true). When it matches the clustered index the server can skip its sort; data not in that order is then rejected (error 4819). Empty clears it.
Version

arpemssql.bulk_atomic since ArpeMSSQL v0.6.5; arpemssql.bulk_order since ArpeMSSQL v0.6.6. Since v0.7.2 the defaults are bulk_atomic=false (was true), bulk_batch_size=1000000 (was 10000000) and bulk_keep_identity=true (was false).

Coming from SqlBulkCopy:

SqlBulkCopyOptions / propertyArpeMSSQL statement option
TableLockarpemssql.bulk_tablock — on by default here
KeepNullsarpemssql.bulk_keep_nulls — on by default here
CheckConstraintsarpemssql.bulk_check_constraints
FireTriggersarpemssql.bulk_fire_triggers
KeepIdentityarpemssql.bulk_keep_identity — on by default here
UseInternalTransactionthe default with autocommit=true: each sub-batch commits on its own (arpemssql.bulk_atomic=true makes the whole ingest one transaction instead)
BatchSizearpemssql.bulk_batch_size
ColumnOrderHintsarpemssql.bulk_order
DestinationTableNameadbc.ingest.target_table (+ target_db_schema / target_catalog)
an external SqlTransactionautocommit=false: the ingest joins the connection's transaction
ColumnMappingsnone: the INSERT BULK names each Arrow column, so they are matched to the target by name. Rename or select Arrow columns to remap
AllowEncryptedValueModifications— (Always Encrypted is not supported)

SqlBulkCopyOptions.Default corresponds to bulk_tablock=false, bulk_keep_nulls=false and bulk_keep_identity=false; the other defaults already match. With every hint off the INSERT BULK carries no WITH clause and takes row locks rather than the bulk-update table lock.

Accepted no-ops (back-compat)​

Recognised and ignored so strings copied from ODBC-era tooling still load:

  • Database options: adbc.arpemssql.mars, adbc.arpemssql.compression.
  • Connection options (set on an open connection): adbc.arpemssql.mars, adbc.arpemssql.enable_compression, and the bare mars / compression.
  • Statement options: adbc.arpemssql.prefetch, and adbc.arpemssql.memory_budget_mb (since v0.7.5; it was never enforced, and a read's memory is bounded by batch_size). Any value is accepted.

adbc.arpemssql.application_intent is no longer a no-op since v0.6.7 (see Read-only routing). The boolean adbc.arpemssql.application_intent_readonly was removed in v0.7.0: use application_intent.

The removed BCP knobs arpemssql.use_bcp, arpemssql.bcp_order_hint and arpemssql.bcp_auto_order are still accepted on the statement but have no effect and log a deprecation warning. The other arpemssql.bcp_* keys are live aliases of the bulk-insert options.


Connection string (ADO.NET form)​

adbc.arpemssql.connection_string (alias connection_string) accepts the ADO.NET Key=Value;… grammar: case-insensitive keywords, quoted values, doubled-quote escapes. Keywords map onto the options above; an unknown keyword is rejected. Boolean values (yes/no/true/false/1/0) are case-insensitive here.

Keyword(s)Option
Server, Data Source, Address, Addr, Network Addressserver (host, host,port, optional tcp: prefix; other protocol prefixes are rejected)
Database, Initial Catalogdatabase
User ID, UID, Userusername
Password, PWDpassword
Application Name, Appapp_name
Encrypt (Strict = tds_version=8.0)encrypt
TDS Version, TDSVersion (7.4 / 8.0)tds_version (since v0.7.5)
TrustServerCertificatetrust_server_cert
HostNameInCertificatehost_name_in_certificate (since v0.7.0)
ServerCertificate (PEM file of trusted CAs)tls_ca_file (since v0.7.0)
AllowCleartextLoginallow_cleartext_login
RequireKerberosrequire_kerberos (since v0.7.6)
Connection Timeout, Connect Timeout, Timeoutlogin_timeout
Packet Size, PacketSizepacket_size (0 or 512..32767)
ApplicationIntent, Application Intent (ReadOnly / ReadWrite)application_intent (since v0.6.7)
Integrated Security, Trusted_Connection, Trusted Connection (SSPI/yes/true/1, no/false/0)trusted
Authenticator (sspi/winsspi/krb5 → integrated, sql → SQL login)trusted
Authenticationauth mode: SqlPassword (or Sql Password), or the Entra ID values ActiveDirectoryDefault, ActiveDirectoryServicePrincipal, ActiveDirectoryManagedIdentity / ActiveDirectoryMSI (since v0.7.5, see Entra ID in a connection string). Other ActiveDirectory* values → NOT_IMPLEMENTED, anything else → INVALID_ARGUMENT
Krb5 Keytab File, Krb5KeytabFile, krb5-keytabfilekrb5.keytab
Krb5 Credential Cache, Krb5CredentialCache, krb5-credcachefilekrb5.ccache
Krb5 Principal, Krb5Principalkrb5.principal
Krb5 Password, Krb5Passwordkrb5.password
Service Principal Name, ServicePrincipalName, service_principal_namekrb5.spn

Integrated Security, Trusted_Connection, Authenticator and Authentication all set the same auth-mode field, so giving two of them is a duplicate-key error. An unknown or repeated keyword is an error, not silently ignored. Options that have no keyword here (query_timeout, buffer_size, the read-path rendering options, ingest.srid, access_token and the other discrete Entra options) are set as discrete options next to the connection string.

Server=localhost\SQL2022;Database=tpch;User ID=sa;Password=secret;Encrypt=true;Packet Size=8192

Connection URI​

Version

Since ArpeMSSQL v0.5.19.

The standard ADBC uri option takes the portable SQL Server URL used by the official drivers (Microsoft go-mssqldb, the ADBC Foundry driver), so a string copied from other SQL Server ADBC tooling works unchanged.

<scheme>://[user[:password]]@host[:port][/INSTANCE][?key=value&…]
  • Schemes (case-insensitive, equivalent): sqlserver://, mssql://, and the branded arpemssql://. The scheme only selects the URL grammar — it never picks the driver, so sqlserver:///mssql:// never collide with another SQL Server ADBC driver installed alongside this one.
  • The path segment is the SQL Server instance name (folded into host\INSTANCE), not the database — the database is the database query parameter. This matches go-mssqldb; it is the one surprising part of the grammar.
  • userinfo and query values are percent-decoded; query values treat + as a space (connection+timeout ≡ connection timeout). IPv6 hosts use the bracketed form: sqlserver://[::1]:1433/?database=d.
  • Reading uri back with GetOption gives mssql://host[:port][/INSTANCE][?database=db] for the current target, with no credentials and the port only when one was set. It connects to the same server and database when passed back in (since v0.7.2).

Query parameters (matched case-insensitively; unknown or repeated parameters are rejected):

Parameter(s)Option
database, initial catalogdatabase
user id, user, uidusername
password, pwdpassword
encrypt (strict = tds_version=8.0)encrypt
tds_versiontds_version (since v0.7.5)
TrustServerCertificatetrust_server_cert
connection timeout, connect timeout, dial timeoutlogin_timeout
packet sizepacket_size
app name, application nameapp_name
ApplicationIntentapplication_intent (since v0.6.7; accepted and ignored before)
hostNameInCertificatehost_name_in_certificate (since v0.7.0)
certificate, ServerCertificate (PEM file of trusted CAs)tls_ca_file (since v0.7.0)
fedauthsame values as Authentication, plus go-mssqldb's ActiveDirectoryApplication (= service principal), since v0.7.5; see Entra ID in a connection string

A service principal fits in the URL as sqlserver://<client id>%40<tenant>:<secret>@myserver.database.windows.net/?database=mydb&fedauth=ActiveDirectoryServicePrincipal.


Read-only routing (ApplicationIntent)​

Version

Since ArpeMSSQL v0.6.7. Earlier versions accepted ApplicationIntent and ignored it.

ApplicationIntent=ReadOnly (or adbc.arpemssql.application_intent=ReadOnly) sets the read-only-intent flag in the login. When the connection goes to an Availability Group listener with read-only routing configured, SQL Server answers with a redirect to a readable secondary and the driver reconnects there, with the same intent. As with SqlClient:

  • Name the database (Database / Initial Catalog): routing applies to a database in the Availability Group.
  • Connecting to a replica instance directly, not through the listener, is not routed.
  • A secondary configured with ALLOW_CONNECTIONS = READ_ONLY refuses connections without the read-only intent.
  • On a server outside an Availability Group the flag is ignored.
Server=ag-listener;Database=sales;ApplicationIntent=ReadOnly;User ID=reporter;Password=<password>;Encrypt=true

ReadWrite, the default, sends no intent. MultiSubnetFailover (trying every IP of a multi-subnet listener in parallel) is not supported.


Named instances​

Version

Since ArpeMSSQL v0.5.14.

A SQL Server named instance normally listens on a dynamic TCP port, not 1433. Given Server=host\INSTANCE, the driver asks the SQL Server Browser on UDP port 1434 which port the instance uses, then connects there — the same handshake SqlClient performs. Both the query path and the INSERT BULK path use it.

Server=localhost\DATAQ1          # port discovered via the Browser
Server=.\SQLEXPRESS # "." and "(local)" mean this machine
Server=localhost\DATAQ1,54312 # explicit port: no Browser lookup at all
  • UDP 1434 must be reachable and the Browser service must be running. If it does not answer, the connection fails after ~3 s with a message naming the instance and the workaround. The driver never falls back to 1433 on its own.
  • An explicit port bypasses the lookup (including an explicit ,1433) — the escape hatch when the Browser is firewalled off.
  • (localdb)\... is rejected: LocalDB is reached over a named pipe, not TCP.

For integrated auth the Kerberos SPN is derived after resolution, as MSSQLSvc/host:<resolved-port>. See Authentication.


Azure SQL, Microsoft Fabric & Entra ID​

Version

Entra ID authentication since ArpeMSSQL v0.5.20. Microsoft Fabric connections since ArpeMSSQL v0.7.5.

SQL-authentication connections to *.database.windows.net and *.datawarehouse.fabric.microsoft.com work out of the box — TLS 1.2+, SNI, and hostname verification are on the default path (use encrypt=true). Both the Proxy and Redirect gateway policies are supported: on Redirect the driver follows the gateway's ENVCHANGE ROUTING token and reconnects to the database node transparently (needs outbound TCP to ports 11000–11999). The redirect happens only at login: the TDS protocol allows the routing token only in the login response, so a connection is never moved once it is open. A server that sends one later breaks the protocol, and the statement fails with "the server sent a routing redirect (ENVCHANGE type 20) outside the login response".

Entra ID (Azure AD) authentication has four modes, all over verified TLS. Federated auth always uses full TLS and cannot be combined with a SQL login (in a connection string, User ID and Password then hold Entra ids, see Entra ID in a connection string).

1. Access-token passthrough​

Supply a bearer token you acquired out-of-band:

Python
import subprocess, adbc_driver_manager.dbapi as dbapi

token = subprocess.check_output(
["az", "account", "get-access-token",
"--resource", "https://database.windows.net/",
"--query", "accessToken", "-o", "tsv"],
).decode().strip()

conn = dbapi.connect(driver="arpemssql", db_kwargs={
"adbc.arpemssql.server": "myserver.database.windows.net",
"adbc.arpemssql.database": "mydb",
"adbc.arpemssql.encrypt": "true",
"adbc.arpemssql.access_token": token,
})

2. Service principal (client credentials)​

The driver acquires the token itself; omit access_token:

Python
db_kwargs={
"adbc.arpemssql.server": "myserver.database.windows.net",
"adbc.arpemssql.database": "mydb",
"adbc.arpemssql.encrypt": "true",
"adbc.arpemssql.tenant_id": "<tenant-guid-or-domain>",
"adbc.arpemssql.client_id": "<app-client-id>",
"adbc.arpemssql.client_secret": "<secret>",
}

The service principal must be a database user (CREATE USER [<app>] FROM EXTERNAL PROVIDER). The token is acquired once per connection and refreshes on reconnect.

3. Managed identity​

On an Azure host (VM/VMSS via IMDS, or App Service / Functions / Container Apps), no secret is needed:

Python
db_kwargs={
"adbc.arpemssql.server": "myserver.database.windows.net",
"adbc.arpemssql.database": "mydb",
"adbc.arpemssql.encrypt": "true",
"adbc.arpemssql.managed_identity": "true", # or a user-assigned client id
}

4. Default credential chain​

auth_type=ActiveDirectoryDefault tries, in order: environment service principal (AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET) → managed identity (short probe) → Azure CLI (az account get-access-token). Handy for code that runs unchanged on a dev machine, in CI, and on an Azure host:

Python
db_kwargs={
"adbc.arpemssql.server": "myserver.database.windows.net",
"adbc.arpemssql.database": "mydb",
"adbc.arpemssql.encrypt": "true",
"adbc.arpemssql.auth_type": "ActiveDirectoryDefault",
}

This is a practical subset of Azure's DefaultAzureCredential; workload-identity-file, Visual Studio, Azure PowerShell, and azd sources are not covered.

Entra ID in a connection string​

Version

Since ArpeMSSQL v0.7.5.

Modes 2 to 4 can also be chosen with SqlClient's Authentication keyword (or go-mssqldb's fedauth URL parameter). User ID and Password then hold the Entra ids, never a SQL login:

Authentication=User IDPasswordSame as
ActiveDirectoryServicePrincipalclient id, or <client id>@<tenant>client secretclient_id / tenant_id / client_secret
ActiveDirectoryManagedIdentity, ActiveDirectoryMSIuser-assigned client id (omit for system-assigned)—managed_identity
ActiveDirectoryDefault——auth_type=ActiveDirectoryDefault
Server=myserver.database.windows.net;Database=mydb;Encrypt=true;
Authentication=ActiveDirectoryServicePrincipal;User ID=<client id>@<tenant>;Password=<secret>

Values are matched case-insensitively and spaces are ignored (Active Directory Default works). The driver does not discover the tenant from the server, as SqlClient does: give it after @ in User ID or with adbc.arpemssql.tenant_id. A discrete adbc.arpemssql.* option wins over the connection string. ActiveDirectoryPassword, ActiveDirectoryInteractive, ActiveDirectoryDeviceCodeFlow, ActiveDirectoryIntegrated and ActiveDirectoryWorkloadIdentity return NOT_IMPLEMENTED; for a token from any other source, use access_token.


See also​