Microsoft SQL Server Driver v1.5.0¶

Note

This project is not associated with Microsoft.

Driver Version v1.5.0 Release Date 2026-07-07 Tested With Microsoft SQL Server 2022 Tested With Microsoft SQL Server 2025 Tested With Fabric Data Warehouse azure

This driver provides access to Microsoft SQL Server .

Installation & Quickstart¶

The driver can be installed with dbc :

dbc install mssql

Connecting¶

To use the driver, provide a SQL Server connection string as the uri option. The driver supports URI format and DSN-style connection strings, but URIs are recommended.

from adbc_driver_manager import dbapi

dbapi.connect(
  driver="mssql",
  db_kwargs={
      "uri": "mssql://sa:password@localhost:1433"
  }
)

Note: The example above is for Python using the adbc-driver-manager package but the process will be similar for other driver managers. See adbc-quickstarts .

Connection String Format¶

SQL Server URI syntax:

mssql://[user:[password]]@host[:port][/instance][?param1=value&param2=value]

sqlserver://[user:[password]]@host[:port][/instance][?param1=value&param2=value]

This follows the format of Microsoft’s official Go MSSQL driver .

Components:

scheme: mssql:// or sqlserver:// (required) - both schemes are supported
user/password: (optional) Credentials for standard SQL Server authentication.
host: (required) The hostname or IP address of the SQL Server machine.
port: (optional) Defaults to 1433.
instance: (optional) The name of the SQL Server instance (e.g., SQLExpress).
Query Parameters: Additional configuration options. For a list of common parameters, see the Microsoft’s official Go MSSQL driver

Note

Reserved characters in URI elements must be URI-encoded. For example, @ becomes %40.

Examples:

mssql://username:mypass@localhost?database=master&connection+timeout=30
mssql://username:mypass@localhost:1234?database=master&connection+timeout=30
mssql://username@localhost/SQLExpress?database=master&connection+timeout=30
sqlserver://sa@localhost/SQLExpress?database=master&connection+timeout=30
sqlserver://sa:mypass@localhost?database=master&connection+timeout=30
sqlserver://sa:mypass@localhost:1234?database=master&connection+timeout=30

EntraID (Azure Active Directory) authentication is enabled by adding a fedauth parameter to your connection URI. For more information, see the documentation for Microsoft’s official Go MSSQL driver .

This driver also supports other types of connection strings that are supported by Microsoft’s official Go MSSQL driver .

Feature & Type Support¶

Feature		Microsoft SQL Server	Fabric Data Warehouse
Bulk Ingestion	Create	✅
	Append	✅
	Create/Append	✅
	Replace	✅
	Temporary Table	✅	❌
	Target Catalog	✅	❌
	Target Schema	✅
	Non-nullable fields are marked NOT NULL	✅
Catalog (GetObjects)	depth=catalogs	✅
	depth=db_schemas	✅
	depth=tables	✅
	depth=columns (all)	✅
Get Parameter Schema		✅
Get Table Schema		✅
Prepared Statements		✅
Transactions		✅

Types¶

Database to Arrow¶

Database Type	Microsoft SQL Server	Fabric Data Warehouse
BIGINT	int64
BIT	bool
CHAR	string
DATE	date32[day]
DATETIME	timestamp[us] (with time zone)
DATETIME2	timestamp[us] (with time zone)
DECIMAL	decimal128
DOUBLE PRECISION	double
GEOGRAPHY	extension<geoarrow.wkb>	(NA/not tested)
GEOMETRY	extension<geoarrow.wkb>	(NA/not tested)
IMAGE	binary	(NA/not tested)
INT	int32
MONEY	decimal128	(NA/not tested)
NCHAR	string	(NA/not tested)
NTEXT	string	(NA/not tested)
NTEXT (mssql.query.large_text_type = large_string)	large_string	(NA/not tested)
NTEXT (mssql.query.large_text_type = string_view)	string_view	(NA/not tested)
NVARCHAR	string	(NA/not tested)
REAL	float
SMALLDATETIME	timestamp[us] (with time zone)	(NA/not tested)
SMALLINT	int16
SMALLMONEY	decimal128	(NA/not tested)
SQL_VARIANT	extension<parquet.variant>	(NA/not tested)
TEXT	string	(NA/not tested)
TEXT (mssql.query.large_text_type = large_string)	large_string	(NA/not tested)
TEXT (mssql.query.large_text_type = string_view)	string_view	(NA/not tested)
TIME	time64[ns] ⚠️ [1]
TIME(0)	time32[s]
TIME(1)	time32[ms]
TIME(2)	time32[ms]
TIME(3)	time32[ms]
TIME(4)	time64[us]
TIME(5)	time64[us]
TIME(6)	time64[us]
TIME(7)	time64[ns]	(NA/not tested)
TINYINT	uint8	(NA/not tested)
UNIQUEIDENTIFIER	extension<arrow.uuid>
VARBINARY	binary
VARCHAR	string
XML	string	(NA/not tested)

Arrow to Database¶

Arrow Type	Microsoft SQL Server Type		Fabric Data Warehouse Type
	Bind	Ingest	Bind	Ingest
	binary	VARBINARY	VARBINARY(MAX)	VARBINARY	VARBINARY(MAX)
binary_view	VARBINARY	VARBINARY(MAX)	VARBINARY	VARBINARY(MAX) ⚠️ [3] [4]
bool	BIT
date32[day]	DATE
decimal128	DECIMAL	DECIMAL ⚠️ [5]	DECIMAL	DECIMAL ⚠️ [5]
double	DOUBLE PRECISION	FLOAT	DOUBLE PRECISION	FLOAT
extension<geoarrow.wkb>	(NA/not tested)	GEOGRAPHY, GEOMETRY	(NA/not tested)
extension<parquet.variant>	SQL_VARIANT		(NA/not tested)
fixed_size_binary	VARBINARY	VARBINARY(MAX)	VARBINARY	VARBINARY(MAX)
float	REAL
halffloat	REAL	(NA/not tested)	REAL	(NA/not tested)
int16	SMALLINT
int32	INT
int64	BIGINT
large_binary	VARBINARY	VARBINARY(MAX)	VARBINARY	VARBINARY(MAX)
large_string	NVARCHAR	NVARCHAR(MAX)	VARCHAR(MAX)	VARCHAR
string	NVARCHAR	NVARCHAR(MAX)	VARCHAR(MAX)	VARCHAR
string_view	NVARCHAR	NVARCHAR(MAX)	VARCHAR(MAX)	VARCHAR ⚠️ [3] [6]
time32[ms]	TIME	TIME(7)	TIME	TIME(3)
time32[s]	TIME	TIME(7)	TIME	TIME(0)
time64[ns]	TIME	TIME(7)	TIME(6)
time64[us]	TIME	TIME(7)	TIME	TIME(6)
timestamp[ms]	DATETIME2		DATETIME2(3)
timestamp[ms] (with time zone)	DATETIME2		DATETIME2(3)
timestamp[ns]	DATETIME2 [2]		DATETIME2(6) [2]	DATETIME2(6) [7]
timestamp[ns] (with time zone)	DATETIME2 [2]		DATETIME2(6) [2]	DATETIME2(6) [7]
timestamp[s]	DATETIME2		DATETIME2(0)
timestamp[s] (with time zone)	DATETIME2		DATETIME2(0)
timestamp[us]	DATETIME2		DATETIME2(6)
timestamp[us] (with time zone)	DATETIME2		DATETIME2(6)

Microsoft Fabric Data Warehouse Support¶

Microsoft Fabric Data Warehouse (hereafter referred to as ‘FDW’) is described as a “relational warehouse on a data lake foundation”. It uses T-SQL, the same dialect of SQL as used by Microsoft SQL Server, and can be connected to over the same protocol using the same driver with some additional configuration.

Limitations¶

Bulk ingest into a temporary table is not supported.
Various data types differ between FDW and regular SQL Server. Consult Microsoft documentation for more details.

Connecting¶

Get the hostname:

Open the warehouse in the web UI.
In the top toolbar, click the gear icon to open the settings panel.
Choose the “SQL endpoint” tab.
Copy the hostname, which will look something like “xxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxx.datawarehouse.fabric.microsoft.com ”.

Build the connection URI:

mssql://xxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxx.datawarehouse.fabric.microsoft.com/?fedauth=ActiveDirectoryDefault

Ensure the Azure CLI is installed.
Run az login.

Now you can connect with the connection URI.

Bulk Ingest¶

Fabric Data Warehouse supports ingesting data from Parquet files in object storage as well as the INSERT BULK command that the driver normally uses to pipe data into the database. We have found Parquet files perform better, but they require configuring a staging area (either in Azure Blob Storage, Azure Data Lake Storage Gen2, or Fabric OneLake) where the driver will upload Parquet files. As long as the staging area is configured, however, the difference is transparent to you as a user of the ADBC driver. The driver defaults to uploading Parquet files when connected to FDW.

Using `INSERT BULK`¶

Set the option mssql.ingest.method (see below).

Using Azure Blob Storage or Azure Data Lake Storage Gen2 as a Staging Area¶

To use Azure Blob Storage (either directly, or through Azure Data Lake Storage Gen2), the user used to log in to FDW must have read permissions on the container. It must have these permissions even if it is already an owner of the data.

First, to configure/check the necessary permissions:

Open the Azure portal .
Open the storage account you wish to use.
On the left, expand “Data storage” and choose “Containers”.
Choose the container you wish to use.
On the left, choose “Access Control (IAM)”.
Choose the “Role assignments” tab.
The user must have the roles “Reader” and “Storage Blob Data Reader” (so FDW can read the uploaded data) and “Storage Blob Data Contributor” (so the driver can upload data).

If the user does not have the role:

Return to the “Check access” tab.
Click “Add role assignment”.
Search for the “Reader” role and select it.
Search for the “Storage Blob Data Reader” role and select it.
Select “Next” at the bottom.
Choose the user(s) to add.
Select “Review + assign” at the bottom.
Select “Review + assign” again.

Note

It may take a minute or two for permissions to propagate.

Note

We have not found in our experience that setting up and granting permissions to a Workspace Identity is necessary for interactive use.

Then, you must configure the driver:

Set the option mssql.ingest.storage_account to the name of the storage account.
Set the option mssql.ingest.storage_container to the name of the storage container.

In the following URLs, spamandeggs is the storage account name and super-secret is the storage container name:

https://spamandeggs.dfs.core.windows.net/super-secret/lineitem.parquet
https://spamandeggs.blob.core.windows.net/super-secret/lineitem.parquet

Using Microsoft Fabric OneLake as a Staging Area¶

Instead of Azure Blob Storage, you can instead use a Lakehouse inside a Fabric workspace as a stanging area via OneLake. You must instead set these options:

Set the option mssql.ingest.storage_url to https://onelake.blob.fabric.microsoft.com/<WORKSPACE_GUID>.
Set the option mssql.ingest.storage_container to <LAKEHOUSE_GUID>/Files.

The GUID of the workspace and the Lakehouse can be inferred by opening Microsoft Fabric, browsing to the Lakehouse, and looking at the URL. For example:

https://app.fabric.microsoft.com/groups/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/lakehouses/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                                        ^WORKSPACE_GUID                                 ^LAKEHOUSE_GUID

Note

In our testing, the “equivalent” URL that uses the name of the warehouse/lakehouse is not sufficient; only the URL that uses the GUIDs will work.

Using a Service Principal¶

You may want to authenticate with a service principal, e.g. in a pipeline. In general, this works, but please note the following additional requirements when using bulk ingest:

The service principal must have the storage permissions as described above. It should be granted these at the application level (Azure Portal => Subscriptions => Access control (IAM) => assign roles to the service principal); we have found that assigning the permissions at the storage container level is insufficient.
The service principal needs the following permissions granted through T-SQL in FDW, in addition to any permissions the user should have regularly:
```
GRANT ADMINISTER DATABASE BULK OPERATIONS TO [my-service-principal]
```

The service principal will be unable to access OneLake/Azure Blob Storage/Azure Data Lake Storage Gen2 unless it first generates an authentication token and performs a request with it. This can be done like so:

export AUTH_TOKEN=$(az account get-access-token \
  --resource https://api.fabric.microsoft.com \
  --query accessToken \
  -o tsv)
curl -fsS \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  "https://api.fabric.microsoft.com/v1/workspaces/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/items"
#                                                 ^ substitute your workspace GUID here

Options¶

Options Affecting Queries¶

mssql.query.large_text_type

Values: string, string_view, or large_string. Default: string

Determines the Arrow string type to use for VARCHAR(MAX) and NVARCHAR(MAX) (and their deprecated aliases TEXT and NTEXT) columns.

This does not affect bulk ingest.

Options Affecting Bulk Ingest¶

mssql.ingest.method

Values: auto, insertbulk, or parquet. Default: auto

Select how to bulk insert data.

auto: use parquet for Fabric Data Warehouse, else insertbulk
insertbulk: use INSERT BULK. Support for this is in preview for Fabric Data Warehouse.
parquet: upload Parquet files to a storage container and then copy them into the target table. Only supported on Fabric Data Warehouse.

In our testing, uploading Parquet is faster than using INSERT BULK. But for small-ish datasets, INSERT BULK may have acceptable performance, and is easier to set up.

mssql.ingest.allow_unsafe_casts

Type: boolean. Default: false

Only applies to parquet ingests. Some Arrow types must be downcast (e.g. timestamp[ns] to timestamp[us]); by default this uses a “safe” cast which will not truncate values, but this option will enable “unsafe” casts. Note that the rounding/truncation behavior is unspecified and may change, and is not necessarily the same as what the database does in INSERT BULK.

mssql.ingest.storage_account

Type: string The name of the Azure storage account to use as a staging area. Required for bulk ingest into Microsoft Fabric Data Warehouse.

mssql.ingest.storage_container

Type: string The name of the Azure storage container to use as a staging area. Required for bulk ingest into Microsoft Fabric Data Warehouse.

mssql.ingest.copy_method

Values: openrowset, copyinto, or bulkinsert. Default: openrowset

Selects the T-SQL statement used to load staged Parquet files into the target table when ingesting into Microsoft Fabric Data Warehouse. Has no effect when ingesting into Microsoft SQL Server (which uses INSERT BULK).

In some basic testing, we have not found any difference between these methods.

mssql.ingest.geo_type

Values: auto, geometry, or geography. Default: auto

What type to use when geoarrow.wkb is detected.

auto: in the GeoArrow metadata, if the detected SRID is nonzero and edges is spherical, then use GEOGRAPHY. Else use GEOMETRY.
geometry: always use GEOMETRY.
geography: in the GeoArrow metadata, if the detected SRID is nonzero, then use GEOGRAPHY. Else use GEOMETRY.

In all cases, if the detected SRID is nonzero, then it will be applied. Also, if the data contains an embedded SRID (i.e. it is EWKB), the embedded SRID will take precedence for that row.

Note

SQL Server requires a valid SRID for GEOGRAPHY columns.

Note

In driver version 1.4.x, the logic was different (and slightly inconsistent internally) and this option was not publicly documented. The original behavior would always use GEOGRAPHY when the SRID was not detected, which was semantically incorrect.

Compatibility¶

This driver was tested on:

Microsoft SQL Server 12.0.2000.8 SQL Azure
Microsoft SQL Server 16.0.4255.1 Enterprise Evaluation Edition (64-bit)
Microsoft SQL Server 17.0.4055.5 Enterprise Evaluation Edition (64-bit)

Previous Versions¶

To see documentation for previous versions of this driver, see the following:

Microsoft SQL Server Driver v1.5.0¶

Installation & Quickstart¶

Connecting¶

Connection String Format¶

Feature & Type Support¶

Types¶

Database to Arrow¶

Arrow to Database¶

Microsoft Fabric Data Warehouse Support¶

Limitations¶

Connecting¶

Bulk Ingest¶

Using INSERT BULK¶

Using Azure Blob Storage or Azure Data Lake Storage Gen2 as a Staging Area¶

Using Microsoft Fabric OneLake as a Staging Area¶

Using a Service Principal¶

Options¶

Options Affecting Queries¶

Options Affecting Bulk Ingest¶

Compatibility¶

Previous Versions¶

Using `INSERT BULK`¶