dbt-fabric

dbt adapter for Microsoft Fabric Synapse Data Warehouse.

The 1.12.x adapter series requires dbt-core 1.12 or newer. Adapter minor versions follow the corresponding dbt-core minor version.

Documentation

We've bundled all documentation on the dbt docs site

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

Installation

This adapter uses mssql-python to connect to Fabric, which bundles its own driver.

Latest version:

pip install -U dbt-fabric

dbt package compatibility

The following releases were reviewed for the 1.12 adapter update. This is a macro compatibility review, not certification of every package feature.

Use the maintained metaplane/dbt_expectations and godatadriven/dbt_date packages rather than their older Calogica distributions. Configure these dispatch entries in dbt_project.yml to select the adapter's overrides:

dispatch:
  - macro_namespace: dbt_utils
    search_order: ["dbt", "dbt_utils"]
  - macro_namespace: dbt_expectations
    search_order: ["dbt", "dbt_expectations"]
  - macro_namespace: dbt_date
    search_order: ["dbt", "dbt_date"]
  - macro_namespace: dbt_artifacts
    search_order: ["dbt", "dbt_artifacts"]
  - macro_namespace: dbt_constraints
    search_order: ["dbt", "dbt_constraints"]
  - macro_namespace: audit_helper
    search_order: ["dbt", "audit_helper"]
  - macro_namespace: dbt_profiler
    search_order: ["dbt", "dbt_profiler"]
  - macro_namespace: dbt_external_tables
    search_order: ["dbt", "dbt_external_tables"]

vars:
  "dbt_date:time_zone": "UTC"

Keep Elementary and Project Evaluator's native dispatch configuration. Package upgrades are made in the consuming project's packages.yml, followed by dbt deps; upgrading the adapter does not upgrade installed dbt packages.

Support remains partial: regex tests are not covered by this update, Elementary 0.26.1 explicitly rejects regex tests on Fabric, and dbt-expectations median / quantile tests still need T-SQL-specific windowing adaptations. Warehouse regex scalar functions are currently a preview feature; their availability alone does not make all upstream regex macros compatible.

dbt_artifacts upstream dependency

Adapter changes alone do not make the unmodified 2.11.1 release compatible. The package's model SQL and non-dispatched column lists contain SQL Server-only branches, and its project configuration enables unsupported documentation persistence on Fabric. The unpublished upstream compatibility patch adds Fabric to those branches without enabling Snowflake-only models. It has not been submitted or released upstream.

Until a compatible upstream release is available, use a patched package revision, or download the patch and apply it to the installed 2.11.1 package after dbt deps:

git -C dbt_packages/dbt_artifacts apply /absolute/path/to/dbt_artifacts_fabric.patch

Configure the dispatch entry above and the package's upload hook:

on-run-end:
  - "{{ dbt_artifacts.upload_results(results) }}"

Initialize the package tables with dbt run --select package:dbt_artifacts before running other project commands. JSON metadata is stored as text. The integration test explicitly applies the patch to its temporary package installation, then exercises all 11 uploads and all 34 enabled core models; it does not demonstrate compatibility with the unpatched release.

dbt_constraints limitations

Fabric primary and unique keys use NONCLUSTERED NOT ENFORCED; foreign keys use NOT ENFORCED and must reference the same database. Passing dbt tests provides the data validation; Warehouse does not enforce those keys during subsequent DML. Declare NOT NULL in an enforced model contract and rebuild the table to establish physical nullability. The package warns rather than claiming to add NOT NULL to an existing nullable column.

The package's pre-build hook releases foreign keys on tables selected for rebuild. If a referenced table has an incoming FK from an unselected table, the build fails before dropping any keys: include the dependent table in dbt build so its FK can be recreated. Keep the package's default start/end hooks enabled, and include the constraint tests in the build. Disabling release-before-build can leave keys that block table replacement or truncation.

Profiling results have no implicit row order; order the consuming query explicitly. Quote special identifiers in group_by, for example [order date].

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.

Core 1.12 development environment

The development group follows published Core 1.12 patch releases available through the configured CFS feed, and uv.lock pins the resolved versions. See the contributing guide for feed access and setup.

uv sync --locked
uv run --locked pytest tests/unit

Known Core 1.12.5 limitation: run-operation --sql starts a transaction but does not commit it before releasing the connection. Inline writes can therefore be rolled back despite a success result. This requires a dbt Core fix; Fabric's rollback-on-close behavior remains unchanged.

When using --empty with an explicit SQL alias, disable the generated relation alias so T-SQL receives only one alias. This retains the zero-row filter:

select * from
{{ source('my_source', 'my_table').incorporate(require_alias=False) }} as t

The same pattern applies to ref(). Omitting the model's explicit alias also avoids the duplicate-alias problem.

License

Code of Conduct

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