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.
| Form | Option key | Grammar | Best for |
|---|---|---|---|
| Discrete options | adbc.arpemssql.<field> | one option per field | programmatic clients, secrets kept out of a single string |
| Connection string | adbc.arpemssql.connection_string (alias connection_string) | ADO.NET Key=Value;… | pasting an existing SQL Server / SqlClient string |
| Connection URI | uri | sqlserver://… URL | portable tooling, copy-paste from go-mssqldb/ADBC tools |
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).
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
| Option | Alias | Default | Meaning |
|---|---|---|---|
adbc.arpemssql.server | hostname | — | Host, host,port / host:port / [::1]:port, ./(local) (→ localhost), or a named instance host\INSTANCE. See Named instances. |
adbc.arpemssql.port | port | 1433 | TCP port, 1..65535. Ignored for a named instance unless given explicitly. |
adbc.arpemssql.database | database | server default | Initial database. |
adbc.arpemssql.app_name | app_name | driver default | Program name reported to the server (sys.dm_exec_sessions.program_name). |
adbc.arpemssql.application_intent | — | ReadWrite | ReadOnly / 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.
| Option | Values | Meaning |
|---|---|---|
adbc.arpemssql.username / .password | string | SQL-authentication credentials (aliases username / password). |
adbc.arpemssql.trusted | a boolean, or sspi (= true), any case | Integrated auth: Windows SSPI, or Kerberos on Linux, no username/password. Alias trusted. |
adbc.arpemssql.auth_type | sql/SqlPassword, integrated/sspi/trusted, ActiveDirectoryDefault/default | Selects 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.keytab | path | Kerberos (Linux): keytab for integrated auth. |
adbc.arpemssql.krb5.ccache | path | Kerberos (Linux): credential cache. |
adbc.arpemssql.krb5.principal | name | Kerberos (Linux): client principal. |
adbc.arpemssql.krb5.password | string | Kerberos (Linux): password used to obtain a ticket (password-based Kerberos). |
adbc.arpemssql.krb5.spn | SPN | Integrated auth: override the derived service principal name (MSSQLSvc/host:port). See SPN. |
adbc.arpemssql.require_kerberos | a 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. |
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
| Option | Default | Meaning |
|---|---|---|
adbc.arpemssql.encrypt | login-only | true/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_version | 7.4 | 8.0 (or 8): TDS 8.0 strict encryption, see Strict encryption (TDS 8.0). |
adbc.arpemssql.trust_server_cert | false | true 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_certificate | the server host | Name (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_login | false | Permit the credentials-in-cleartext login exchange when encryption is off. |
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
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)
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.0and SNI; PRELOGIN and LOGIN7 then travel inside TLS (1.2 or 1.3); - the server certificate is always verified:
trust_server_cert=trueis refused, as Microsoft's drivers ignoreTrustServerCertificatethere. For a private CA or a self-signed certificate, trust it withtls_ca_file(ServerCertificate), and sethost_name_in_certificateif it names another host; - encryption is implied, so
encryptdoes 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
| Spelling | Values |
|---|---|
adbc.arpemssql.tds_version | 7.4 (default), 8.0 / 8 |
Connection string TDS Version, TDSVersion | same |
Connection string / option Encrypt=Strict | = 8.0 (conflicts with TDS Version=7.4) |
URI ?tds_version=8.0, ?encrypt=strict | same |
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)
| Option | Meaning |
|---|---|
adbc.arpemssql.access_token | Caller-supplied Entra ID bearer token (passthrough). |
adbc.arpemssql.tenant_id / .client_id / .client_secret | Service principal; the driver acquires a token via OAuth2 client credentials at connect. |
adbc.arpemssql.managed_identity | true/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
| Option | Default | Meaning |
|---|---|---|
adbc.arpemssql.login_timeout | 30 | TCP 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_timeout | 0 | Longest 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_size | 32000 | Rows 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_size | 8192 | TDS 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. |
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)
| Option | Values | Meaning |
|---|---|---|
adbc.arpemssql.uuid_casing | lower (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.geospatial | geoarrow (default) / wkb / varbinary | How geometry/geography (CLR UDT) columns are read. See Geospatial types. |
adbc.arpemssql.timestamp_precision | microsecond (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)
Since ArpeMSSQL v0.5.25.
| Option | Default | Meaning |
|---|---|---|
adbc.arpemssql.ingest.srid | unset (-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
| Option | Meaning |
|---|---|
arpeio.adbc.license | Licence blob, inline. |
arpeio.adbc.license_file | Path to a .lic file. |
arpeio.adbc.license.status | Read-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):
| Option | Values | Meaning |
|---|---|---|
adbc.connection.autocommit | true (default) / false | Autocommit 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.catalog | database name | Switches the current database (USE [db] on the open session; with no session yet, validated by a test login). Empty is rejected. |
adbc.connection.db_schema | schema name | Checked 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_level | read_uncommitted / read_committed / repeatable_read / snapshot / serializable / default | Values 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.readonly | false / 0 | Accepted 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:
| Option | Default | Meaning |
|---|---|---|
adbc.arpemssql.batch_size | buffer_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_size | 1000000 | Upper 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.mode | create | adbc.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.temporary | false | true/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.
| Option | Alias | Default | Meaning |
|---|---|---|---|
arpemssql.bulk_tablock | arpemssql.bcp_tablock | true | TABLOCK 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_size | arpemssql.bcp_batch_size | 1000000 | Rows per sub-batch sent to the server, 1..100000000. |
arpemssql.bulk_atomic | — | false | With 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_identity | arpemssql.bcp_keep_identity | true | true 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_constraints | arpemssql.bcp_check_constraints | false | Enforce CHECK/FK constraints during load (off = faster). |
arpemssql.bulk_fire_triggers | arpemssql.bcp_fire_triggers | false | Fire INSERT triggers during load (off = faster). |
arpemssql.bulk_keep_nulls | arpemssql.bcp_keep_nulls | true | Keep 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. |
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 / property | ArpeMSSQL statement option |
|---|---|
TableLock | arpemssql.bulk_tablock — on by default here |
KeepNulls | arpemssql.bulk_keep_nulls — on by default here |
CheckConstraints | arpemssql.bulk_check_constraints |
FireTriggers | arpemssql.bulk_fire_triggers |
KeepIdentity | arpemssql.bulk_keep_identity — on by default here |
UseInternalTransaction | the default with autocommit=true: each sub-batch commits on its own (arpemssql.bulk_atomic=true makes the whole ingest one transaction instead) |
BatchSize | arpemssql.bulk_batch_size |
ColumnOrderHints | arpemssql.bulk_order |
DestinationTableName | adbc.ingest.target_table (+ target_db_schema / target_catalog) |
an external SqlTransaction | autocommit=false: the ingest joins the connection's transaction |
ColumnMappings | none: 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 baremars/compression. - Statement options:
adbc.arpemssql.prefetch, andadbc.arpemssql.memory_budget_mb(since v0.7.5; it was never enforced, and a read's memory is bounded bybatch_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 Address | server (host, host,port, optional tcp: prefix; other protocol prefixes are rejected) |
Database, Initial Catalog | database |
User ID, UID, User | username |
Password, PWD | password |
Application Name, App | app_name |
Encrypt (Strict = tds_version=8.0) | encrypt |
TDS Version, TDSVersion (7.4 / 8.0) | tds_version (since v0.7.5) |
TrustServerCertificate | trust_server_cert |
HostNameInCertificate | host_name_in_certificate (since v0.7.0) |
ServerCertificate (PEM file of trusted CAs) | tls_ca_file (since v0.7.0) |
AllowCleartextLogin | allow_cleartext_login |
RequireKerberos | require_kerberos (since v0.7.6) |
Connection Timeout, Connect Timeout, Timeout | login_timeout |
Packet Size, PacketSize | packet_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 |
Authentication | auth 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-keytabfile | krb5.keytab |
Krb5 Credential Cache, Krb5CredentialCache, krb5-credcachefile | krb5.ccache |
Krb5 Principal, Krb5Principal | krb5.principal |
Krb5 Password, Krb5Password | krb5.password |
Service Principal Name, ServicePrincipalName, service_principal_name | krb5.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
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 brandedarpemssql://. The scheme only selects the URL grammar — it never picks the driver, sosqlserver:///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 thedatabasequery parameter. This matchesgo-mssqldb; it is the one surprising part of the grammar. userinfoand 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
uriback withGetOptiongivesmssql://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 catalog | database |
user id, user, uid | username |
password, pwd | password |
encrypt (strict = tds_version=8.0) | encrypt |
tds_version | tds_version (since v0.7.5) |
TrustServerCertificate | trust_server_cert |
connection timeout, connect timeout, dial timeout | login_timeout |
packet size | packet_size |
app name, application name | app_name |
ApplicationIntent | application_intent (since v0.6.7; accepted and ignored before) |
hostNameInCertificate | host_name_in_certificate (since v0.7.0) |
certificate, ServerCertificate (PEM file of trusted CAs) | tls_ca_file (since v0.7.0) |
fedauth | same 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)
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_ONLYrefuses 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
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
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:
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:
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:
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:
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
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 ID | Password | Same as |
|---|---|---|---|
ActiveDirectoryServicePrincipal | client id, or <client id>@<tenant> | client secret | client_id / tenant_id / client_secret |
ActiveDirectoryManagedIdentity, ActiveDirectoryMSI | user-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
- Authentication — SQL login and integrated auth (Windows SSPI, Kerberos on Linux)
- Data types — SQL Server → Arrow type mapping
- Compatibility — supported SQL Server versions & editions
- Troubleshooting — common connection failures
- Examples — copy-paste recipes
- Licensing — supplying your Arpeio licence