{"id":8932,"library":"dbt-sqlserver","title":"dbt-sqlserver Adapter","description":"dbt-sqlserver is a dbt adapter plugin that enables dbt to connect to and transform data in Microsoft SQL Server databases. It allows users to leverage dbt's powerful data transformation capabilities, including models, tests, and documentation, against SQL Server instances. The library maintains close compatibility with dbt-core's release cycle, typically releasing updates in sync with dbt-core's major versions. The current version is 1.9.0.","status":"active","version":"1.9.0","language":"python","source_language":"en","source_url":"https://github.com/dbt-msft/dbt-sqlserver","tags":["dbt","sqlserver","database","data transformation","etl","elt"],"install":[{"cmd":"pip install dbt-sqlserver","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"dbt-sqlserver is an adapter plugin for dbt-core, providing the core dbt functionality.","package":"dbt-core","optional":false},{"reason":"Used internally by dbt-sqlserver to connect to SQL Server databases.","package":"pyodbc","optional":false}],"imports":[{"note":"dbt adapters are loaded by dbt-core at runtime based on configuration, not through explicit Python imports in user scripts.","symbol":"dbt-sqlserver","correct":"# dbt-sqlserver is a dbt adapter plugin.\n# Users typically do not import symbols directly from this library in Python code.\n# Interaction is primarily via the dbt CLI and configuration files (profiles.yml, dbt_project.yml)."}],"quickstart":{"code":"import os\n\n# Configure your SQL Server connection details using environment variables or replace placeholders.\nprofiles_yml_content = f\"\"\"\nsqlserver_quickstart:\n  target: dev\n  outputs:\n    dev:\n      type: sqlserver\n      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'\n      server: {os.environ.get('SQLSERVER_SERVER', 'localhost')} # e.g., 'your_server_name.database.windows.net' or 'localhost\\\\SQLEXPRESS'\n      port: {os.environ.get('SQLSERVER_PORT', '1433')}\n      database: {os.environ.get('SQLSERVER_DATABASE', 'dbt_test_db')}\n      schema: {os.environ.get('SQLSERVER_SCHEMA', 'dbt_sqlserver_qs')}\n      authentication: {os.environ.get('SQLSERVER_AUTH_METHOD', 'sql')} # 'sql', 'windows', or 'aad'\n      # For 'sql' authentication:\n      user: {os.environ.get('SQLSERVER_USER', 'your_user_name_here')}\n      password: {os.environ.get('SQLSERVER_PASSWORD', 'your_password_here')}\n      # For 'aad' or 'windows' authentication, consult dbt-sqlserver documentation.\n      # trust_cert: true # Optional: Use with caution if not validating certs\n\"\"\"\n\nprint(\"To quickly get started with dbt-sqlserver:\")\nprint(\"1. Ensure you have the appropriate Microsoft ODBC Driver for SQL Server installed on your system.\")\nprint(\"2. Create or update a file named `profiles.yml` in your `~/.dbt/` directory (or specify with --profiles-dir). \")\nprint(\"3. Populate it with content similar to the following (replace placeholders or set environment variables):\")\nprint(\"\\n\" + profiles_yml_content)\nprint(\"\\n4. Initialize a dbt project: `dbt init my_sqlserver_project`\")\nprint(\"5. In `my_sqlserver_project/dbt_project.yml`, set `profile: sqlserver_quickstart`\")\nprint(\"6. Navigate into your project directory: `cd my_sqlserver_project`\")\nprint(\"7. Test your connection: `dbt debug`\")","lang":"python","description":"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."},"warnings":[{"fix":"Always 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`","message":"dbt-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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Download 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').","message":"Connecting 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully 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.","message":"Different 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor 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.","message":"SQL 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.","severity":"gotcha","affected_versions":"Prior to 1.8.2, and current versions with specific workload patterns."}],"env_vars":null,"search_vec":"'1.9.0':75 'adapt':4,11 'allow':28 'capabl':37 'close':50 'compat':51 'connect':17 'core':55,67 'current':72 'cycl':58 'data':21,35,79 'databas':26,78 'dbt':2,6,10,15,32,54,66,76 'dbt-core':53,65 'dbt-sqlserver':1,5 'document':42 'elt':82 'enabl':14 'etl':81 'includ':38 'instanc':46 'leverag':31 'librari':48 'maintain':49 'major':69 'microsoft':23 'model':39 'plugin':12 'power':34 'releas':57,60 'server':25,45 'sql':24,44 'sqlserver':3,7,77 'sync':63 'test':40 'transform':20,36,80 'typic':59 'updat':61 'user':29 'version':70,73","created_at":"2026-04-16T18:47:35.284197+00:00","updated_at":"2026-04-16T18:47:35.284197+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.10.0","cli_name":"dbt","cli_version":"Core:","type":"library","homepage":null,"github":"https://github.com/dbt-msft/dbt-sqlserver","docs":null,"changelog":"https://github.com/dbt-msft/dbt-sqlserver/blob/master/CHANGELOG.md","pypi":"https://pypi.org/project/dbt-sqlserver/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"skip","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}