dbt-fabric

dbt adapter for Microsoft Fabric Synapse Data Warehouse.

The adapter supports dbt-core 1.4 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

Installation

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

macOS (Apple Silicon)

Install unixODBC and the ODBC driver via Homebrew:

brew install unixodbc msodbcsql18

Modern Homebrew (post-Sonoma) ships libodbc.3.dylib, but pyodbc wheels are often compiled against libodbc.2.dylib. This mismatch causes the following error at runtime:

Library not loaded: /opt/homebrew/opt/unixodbc/lib/libodbc.2.dylib

Fix — recompile pyodbc against the installed unixODBC:

export LDFLAGS="-L/opt/homebrew/opt/unixodbc/lib"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include"
pip install --force-reinstall --no-binary :all: pyodbc

Alternative — create a compatibility symlink:

ln -s /opt/homebrew/opt/unixodbc/lib/libodbc.3.dylib \
      /opt/homebrew/opt/unixodbc/lib/libodbc.2.dylib

Latest version:

pip install -U dbt-fabric

Performance guidance for large projects

Fabric Warehouse DDL operations (e.g. CREATE TABLE, sp_rename) hold catalog locks that can block sys.tables/sys.views reads from concurrent dbt sessions. With many models and high thread counts this causes list_<schema> steps to stall for minutes.

Strongly recommended for projects with 500+ models or concurrent dbt runs:

# profiles.yml
my_fabric_project:
  target: dev
  outputs:
    dev:
      type: fabric
      # ... connection settings ...
      threads: 4          # keep low (4–8) to reduce catalog lock pressure
      query_timeout: 30   # fail fast on blocked catalog reads (seconds)

In your dbt_project.yml:

flags:
  cache_selected_only: true  # only list schemas for models in the current run

Or pass --no-populate-cache on the CLI for a single run. This prevents dbt from listing every schema in the warehouse upfront, significantly reducing catalog read pressure during concurrent runs.

Changelog

See the changelog

Contributing

This adapter is Microsoft-maintained. You are welcome to contribute by creating issues, opening or reviewing pull requests. 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 Microsoft Code of Conduct.