Implementation:MaterializeInc Materialize MaterializeConnectionManager Open

Knowledge Sources	`misc/dbt-materialize/dbt/adapters/materialize/connections.py`
Domains	Database Adapter Configuration, Connection Management, Credential Handling
Last Updated	2026-02-08

Overview

Concrete connection manager for Materialize provided by the dbt-materialize adapter, handling connection opening, session configuration, version validation, and autocommit mode.

Description

The MaterializeConnectionManager class extends PostgresConnectionManager to implement Materialize-specific connection behavior. Its open() class method delegates initial connection setup to the PostgreSQL parent, then applies critical Materialize customizations:

Autocommit mode: Sets connection.handle.autocommit = True to prevent psycopg2 from automatically opening transactions. Materialize does not support arbitrary multi-statement transactions, so all operations run in autocommit mode.
Version validation: Reads the mz_version server parameter from the connection, parses it (stripping the leading v and any build metadata), and checks it against SUPPORTED_MATERIALIZE_VERSIONS (currently >=0.68.0). Raises DbtRuntimeError on mismatch.

The companion MaterializeCredentials dataclass extends PostgresCredentials with:

cluster (Optional[str]): The target cluster for compute operations. When omitted, falls back to the connected user's default cluster.
application_name (Optional[str]): Defaults to dbt-materialize v{version}.

Session parameters are injected at connection time via a monkey-patched psycopg2.connect function that prepends options for auto_route_catalog_queries, welcome_message, and current_object_missing_warnings.

Usage

Use this implementation when:

Configuring a profiles.yml target of type materialize for dbt.
Understanding how Materialize connections differ from standard PostgreSQL connections.
Debugging connection failures related to version incompatibility or session parameter issues.

Code Reference

Source Location

File	Lines	Description
`misc/dbt-materialize/dbt/adapters/materialize/connections.py`	L112-131	`MaterializeConnectionManager.open()` method
`misc/dbt-materialize/dbt/adapters/materialize/connections.py`	L73-106	`MaterializeCredentials` dataclass
`misc/dbt-materialize/dbt/adapters/materialize/connections.py`	L41-70	`connect()` monkey-patch for psycopg2 session parameter injection

Signature

# MaterializeConnectionManager.open()
@classmethod
def open(cls, connection) -> Connection:
    ...

# MaterializeCredentials dataclass
@dataclass
class MaterializeCredentials(PostgresCredentials):
    cluster: Optional[str] = None
    application_name: Optional[str] = f"dbt-materialize v{__version__}"

    @property
    def type(self) -> str: ...

    def _connection_keys(self) -> tuple: ...

Import

from dbt.adapters.materialize.connections import MaterializeConnectionManager
from dbt.adapters.materialize.connections import MaterializeCredentials

I/O Contract

Inputs

Parameter	Type	Description
`connection`	`Connection`	A dbt Connection object with credentials populated from `profiles.yml`. The credentials must include host, port, user, database, and optionally cluster, sslmode, keepalives_idle, connect_timeout, search_path, retries, and application_name.

Outputs

Return	Type	Description
`connection`	`Connection`	The same Connection object, now with an open psycopg2 handle in autocommit mode. The handle has been version-validated against `SUPPORTED_MATERIALIZE_VERSIONS`.
(raises)	`DbtRuntimeError`	Raised if the connected Materialize version is outside the supported range.

Usage Examples

# profiles.yml — Materialize target configuration
my_project:
  target: dev
  outputs:
    dev:
      type: materialize
      host: localhost
      port: 6875
      user: materialize
      pass: password
      database: materialize
      schema: public
      cluster: quickstart
      sslmode: disable

# Internal usage within dbt (typically not called directly)
from dbt.adapters.materialize.connections import MaterializeConnectionManager

# The open() method is called by the dbt connection pool
connection = MaterializeConnectionManager.open(connection)
# connection.handle.autocommit is now True
# Materialize version has been validated

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment