Microsoft SQL Server v1.1.0¶

Note

This project is not associated with Microsoft.

Driver Version v1.1.0 Tested With Microsoft SQL Server 2022

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

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

Feature & Type Support¶

Feature	Support
Bulk Ingestion	Create	✅
	Append	✅
	Create/Append	✅
	Replace	✅
	Temporary Table	✅
	Specify target catalog	✅
	Specify 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	✅

Feature	Name	Support	Description
Configuration	Connect with URI	✅	Test MSSQL URI without explicit port.
	Connect with mssql:// URI	✅	Test end-to-end connection with mssql:// scheme.
	Connect with sqlserver:// URI	✅	Test end-to-end connection with sqlserver:// scheme.

Types¶

Microsoft SQL Server to Arrow¶

Microsoft SQL Server Type	Arrow Type
BIGINT	int64
BIT	bool
CHAR	string
DATE	date32[day]
DATETIME	timestamp[us] (with time zone)
DATETIME2	timestamp[us] (with time zone)
DOUBLE PRECISION	double
INT	int32
NCHAR	string
NUMERIC	decimal128
REAL	float
SMALLINT	int16
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]
VARBINARY	binary
VARCHAR	string

Arrow to Microsoft SQL Server¶

Arrrow Type	Microsoft SQL Server Type
Arrrow Type	Bind	Ingest
binary	VARBINARY	VARBINARY(MAX)
binary_view	VARBINARY	VARBINARY(MAX)
bool	BIT
date32[day]	DATE
decimal128	NUMERIC
double	DOUBLE PRECISION
fixed_size_binary	VARBINARY	VARBINARY(MAX)
float	REAL
halffloat	REAL	(not tested)
int16	SMALLINT
int32	INT
int64	BIGINT
large_binary	VARBINARY	VARBINARY(MAX)
large_string	NVARCHAR	NTEXT
string	NVARCHAR	NTEXT
string_view	NVARCHAR	NTEXT
time32[ms]	TIME(3)	TIME(7) ⚠️ [3]
time32[s]	TIME(0)	TIME(7) ⚠️ [3]
time64[ns]	TIME(7)	TIME(7) ⚠️ [3]
time64[us]	TIME(6)	TIME(7) ⚠️ [3]
timestamp[ms]	DATETIME2
timestamp[ms] (with time zone)	DATETIME2
timestamp[ns]	DATETIME2 [2]	DATETIME2
timestamp[ns] (with time zone)	DATETIME2 [2]	DATETIME2
timestamp[s]	DATETIME2
timestamp[s] (with time zone)	DATETIME2
timestamp[us]	DATETIME2
timestamp[us] (with time zone)	DATETIME2

Previous Versions¶

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

v1.0.0