Environment:MaterializeInc Materialize Dbt Materialize Runtime

Knowledge Sources	MaterializeInc/materialize dbt-materialize README
Domains	Data_Engineering, dbt
Last Updated	2026-02-08 21:00 GMT

Overview

Python runtime environment for the dbt-materialize adapter, providing dbt-core, dbt-postgres, psycopg2, and a connection to a running Materialize instance (version >= 0.68.0).

Description

This environment provides the runtime for the dbt-materialize adapter plugin. It extends the dbt-postgres adapter with Materialize-specific behavior including disabled transactions, auto-routed catalog queries, and support for Materialize-specific relation types (sources, sinks, indexes, materialized views). The adapter connects to Materialize via psycopg2 and injects session parameters (`auto_route_catalog_queries=on`, `welcome_message=off`, `current_object_missing_warnings=off`) at connection time.

Usage

Use this environment for running dbt run, dbt test, dbt deploy, and other dbt commands against a Materialize database. It is the mandatory prerequisite for MaterializeConnectionManager_Open, MaterializeAdapter_Relations, Dbt_Materialize_Commands, and Deploy_Promote_Pattern implementations.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	Python 3.9+
Database	Materialize >= 0.68.0	Version validated at connection time
Network	TCP access to Materialize instance	Default port 6875

Dependencies

Python Packages

`dbt-common` >= 1.10, < 3.0
`dbt-adapters` >= 1.7, < 2.0
`dbt-core` >= 1.8.0 (backwards compatibility, not a functional dependency)
`dbt-postgres` >= 1.8, < 1.11
`psycopg2` (PostgreSQL driver, inherited from dbt-postgres)

Dev Dependencies

`dbt-tests-adapter` (from dbt-labs/dbt-adapters, only when `RELEASE_BUILD` is not set)

Credentials

The following connection parameters are configured in `profiles.yml`:

`host`: Materialize hostname
`port`: Materialize port (default 6875)
`user`: Database user
`password`: Database password
`database`: Database name (default `materialize`)
`schema`: Default schema
`cluster`: Optional target cluster (defaults to user's default cluster)
`sslmode`: SSL connection mode
`connect_timeout`: Connection timeout in seconds
`retries`: Number of connection retries

Quick Install

pip install dbt-materialize

# Or install from source:
cd misc/dbt-materialize
pip install -e .

Code Evidence

Materialize version validation from `connections.py:112-131`:

@classmethod
def open(cls, connection):
    connection = super().open(connection)
    connection.handle.autocommit = True
    mz_version = connection.handle.info.parameter_status("mz_version")
    mz_version = mz_version.split()[0]  # e.g. v0.79.0-dev
    mz_version = mz_version[1:]  # e.g. 0.79.0-dev
    if not versions_compatible(mz_version, SUPPORTED_MATERIALIZE_VERSIONS):
        raise dbt_common.exceptions.DbtRuntimeError(
            f"Detected unsupported Materialize version {mz_version}\n"
            f"  Supported versions: {SUPPORTED_MATERIALIZE_VERSIONS}"
        )
    return connection

Session parameter injection from `connections.py:41-66`:

def connect(**kwargs):
    options = [
        "--auto_route_catalog_queries=on",
        "--welcome_message=off",
        "--current_object_missing_warnings=off",
        *(kwargs.get("options") or []),
    ]
    kwargs["options"] = " ".join(options)
    return _connect(**kwargs)

Common Errors

Error Message	Cause	Solution
`Detected unsupported Materialize version X`	Materialize version below 0.68.0	Upgrade Materialize to >= 0.68.0
Default cluster not found	Default cluster for dbt user does not exist	Set `cluster` explicitly in `profiles.yml` or per-model config
`pg_terminate_backend` not supported	dbt attempting PostgreSQL-style cancellation	dbt-materialize overrides `cancel()` to use `connection.handle.close()` instead

Compatibility Notes

Transactions disabled: Materialize does not support arbitrary queries in transactions, so `begin()`, `commit()`, and `clear_transaction()` are all no-ops. This follows the pattern used by dbt-snowflake and dbt-bigquery.
Autocommit mode: Connections are set to autocommit mode (`connection.handle.autocommit = True`) to avoid implicit transaction wrapping.
Cluster parameter: The `cluster` parameter in `profiles.yml` is not passed in the connection string but is used by dbt macros to set the cluster per-model.
RELEASE_BUILD: When the `RELEASE_BUILD` environment variable is set, dev dependencies (dbt-tests-adapter) are excluded from the package.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment