Install & Compatibility
Where this runs
tested against v1.9.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.000s · 119.2MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 10.3s · import 0.000s · 116MB
120MB installed
● package 120MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
dbt-sqlserver
✓ # dbt-sqlserver is a dbt adapter plugin.
# Users typically do not import symbols directly from this library in Python code.
# Interaction is primarily via the dbt CLI and configuration files (profiles.yml, dbt_project.yml).
dbt adapters are loaded by dbt-core at runtime based on configuration, not through explicit Python imports in user scripts.
The primary interaction with dbt-sqlserver is through the dbt CLI and configuration files. This Python snippet demonstrates how to construct the `profiles.yml` content required to connect dbt to a SQL Server database, using environment variables for sensitive or variable settings. After setting up the `profiles.yml` and a dbt project, `dbt debug` is used to verify the connection.
import os
# Configure your SQL Server connection details using environment variables or replace placeholders.
profiles_yml_content = f"""
sqlserver_quickstart:
target: dev
outputs:
dev:
type: sqlserver
driver: {os.environ.get('SQLSERVER_ODBC_DRIVER', 'ODBC Driver 17 for SQL Server')} # e.g., 'ODBC Driver 17 for SQL Server' or 'ODBC Driver 18 for SQL Server'
server: {os.environ.get('SQLSERVER_SERVER', 'localhost')} # e.g., 'your_server_name.database.windows.net' or 'localhost\\SQLEXPRESS'
port: {os.environ.get('SQLSERVER_PORT', '1433')}
database: {os.environ.get('SQLSERVER_DATABASE', 'dbt_test_db')}
schema: {os.environ.get('SQLSERVER_SCHEMA', 'dbt_sqlserver_qs')}
authentication: {os.environ.get('SQLSERVER_AUTH_METHOD', 'sql')} # 'sql', 'windows', or 'aad'
# For 'sql' authentication:
user: {os.environ.get('SQLSERVER_USER', 'your_user_name_here')}
password: {os.environ.get('SQLSERVER_PASSWORD', 'your_password_here')}
# For 'aad' or 'windows' authentication, consult dbt-sqlserver documentation.
# trust_cert: true # Optional: Use with caution if not validating certs
"""
print("To quickly get started with dbt-sqlserver:")
print("1. Ensure you have the appropriate Microsoft ODBC Driver for SQL Server installed on your system.")
print("2. Create or update a file named `profiles.yml` in your `~/.dbt/` directory (or specify with --profiles-dir). ")
print("3. Populate it with content similar to the following (replace placeholders or set environment variables):")
print("\n" + profiles_yml_content)
print("\n4. Initialize a dbt project: `dbt init my_sqlserver_project`")
print("5. In `my_sqlserver_project/dbt_project.yml`, set `profile: sqlserver_quickstart`")
print("6. Navigate into your project directory: `cd my_sqlserver_project`")
print("7. Test your connection: `dbt debug`")
dbt --version
Debug
Known issues
breakingdbt-sqlserver versions are tightly coupled with dbt-core versions. Ensure that your installed dbt-sqlserver adapter's major version matches your dbt-core installation's major version (e.g., dbt-sqlserver==1.9.x with dbt-core==1.9.x). Mismatched versions can lead to unexpected behavior or errors.fixAlways install `dbt-sqlserver` with a version specifier that aligns with your `dbt-core` version: `pip install dbt-core~=1.9.0 dbt-sqlserver~=1.9.0`
affects: All versions
gotchaConnecting to SQL Server requires a pre-installed Microsoft ODBC Driver for SQL Server on the system where dbt is running. The `dbt-sqlserver` package only installs the `pyodbc` Python library, which acts as a wrapper for the native ODBC driver.fixDownload and install the appropriate Microsoft ODBC Driver for SQL Server (e.g., version 17 or 18) for your operating system. Ensure the `driver` field in your `profiles.yml` matches the installed driver name exactly (e.g., 'ODBC Driver 17 for SQL Server').
affects: All versions
gotchaDifferent authentication methods (SQL, Windows, Azure AD) for SQL Server have distinct configuration requirements in `profiles.yml`. Incorrectly configured authentication details are a common source of connection failures.fixCarefully review the `authentication` field in your `profiles.yml`. For 'sql' authentication, ensure `user` and `password` are correct. For 'windows' authentication, ensure the dbt process runs under a Windows-authenticated user. For 'aad' (Azure AD) authentication, provide `client_id`, `client_secret`, and `tenant_id` if using service principal.
affects: All versions
gotchaSQL Server's default transaction isolation levels and locking behaviors can lead to deadlocks or concurrency issues in busy environments, especially during dbt runs involving large transformations. Versions 1.8.2 and later re-introduced `NOLOCK` behavior in some queries to mitigate this.fixMonitor SQL Server performance and locks during dbt runs. Consider using `NOLOCK` where appropriate (if it aligns with your data consistency requirements) via dbt macros, or consult SQL Server documentation for tuning transaction isolation levels and concurrency control for your specific use case. The adapter's `trust_cert` setting can also impact connection stability.
affects: Prior to 1.8.2, and current versions with specific workload patterns.
Upgrade
Version history
1.10.0latest on PyPI · released Jun 10, 2026
Audit
Dependencies
dbt-corerequireddbt-sqlserver is an adapter plugin for dbt-core, providing the core dbt functionality.
pyodbcrequiredUsed internally by dbt-sqlserver to connect to SQL Server databases.