dbt-sqlserver

dbt adapter for Microsoft SQL Server and Azure SQL services.

The adapter supports dbt-core 0.14 or newer and follows the same versioning scheme. E.g. version 1.1.x of the adapter will be compatible with dbt-core 1.1.x.

Documentation

We've bundled all documentation on the dbt docs site:

• Profile setup & authentication
• Adapter documentation, usage and important notes

Join us on the dbt Slack to ask questions, get help, or to discuss the project.

Installation

By default this adapter uses the Microsoft ODBC driver.

This adapter requires the Microsoft ODBC driver to be installed: Windows | macOS | Linux

Debian/Ubuntu

Make sure to install the ODBC headers as well as the driver linked above:

sudo apt-get install -y unixodbc-dev

Latest version:

pip install -U dbt-sqlserver

Latest pre-release:

pip install -U --pre dbt-sqlserver

Optional: mssql-python backend

This adapter can also use the mssql-python driver behind a feature flag.

Install it explicitly when you want to use that backend:

pip install -U mssql-python

When this backend is enabled, the adapter does not require the ODBC driver-based connection path for that profile.

Changelog

See the changelog

Configuration

Flags

• dbt_sqlserver_use_default_schema_concat: (default: false) Controls schema name generation when a custom schema is set on a model.

• use_mssql_python: (default: false in the profile) Switches the connection backend from the legacy ODBC / pyodbc path to the mssql-python driver for that target profile.

  Flag value	custom_schema_name	Result
  false (default, legacy)	(none)	target.schema
  false (default, legacy)	"reporting"	reporting
  true (dbt-core standard)	(none)	target.schema
  true (dbt-core standard)	"reporting"	target.schema_reporting

  When false (the default), the adapter uses its legacy behaviour: custom_schema_name is used as-is without being prefixed by target.schema.
  When true, the adapter delegates to dbt-core's default__generate_schema_name, which concatenates target.schema + _ + custom_schema_name.

  Example usage in dbt_project.yml:

  vars:
    dbt_sqlserver_use_default_schema_concat: true  # Enable standard schema concatenation

  Note: If you want to permanently customise schema generation and avoid any future deprecation of this flag, override the sqlserver__generate_schema_name macro directly in your project.

mssql-python feature flag usage

Enable the backend per target in your profiles.yml:

your_profile:
  target: dev
  outputs:
    dev:
      type: sqlserver
      host: your-server
      port: 1433
      database: your-database
      schema: dbo
      user: your-user
      password: your-password
      encrypt: true
      trust_cert: false
      use_mssql_python: true

Notes

• use_mssql_python: true is a profile-level feature flag.
• When enabled, the adapter uses mssql-python instead of the legacy pyodbc connection path.
• The legacy ODBC driver setting is only needed for profiles that continue to use the ODBC backend.
• If you enable use_mssql_python, make sure the mssql-python package is installed in the environment running dbt.
• This path is intended to fail fast when required dependencies or unsupported settings are missing.

Testing

For local development and validation, use the documented adapter workflow from CONTRIBUTING.md:

make dev
make server
cp test.env.sample test.env
make unit
make functional

To exercise the mssql-python backend in tests, configure the profile or environment so that the target under test sets:

use_mssql_python: true

If you are testing in the devcontainer, ensure the mssql-python package is installed in that environment before running the unit or functional suite.

Contributing

This adapter is community-maintained. You are welcome to contribute by creating issues, opening or reviewing pull requests or helping other users in Slack channel. If you're unsure how to get started, check out our contributing guide.

License

Code of Conduct

This project and everyone involved is expected to follow the dbt Code of Conduct.