dataface 0.1.2__py3-none-any.whl

dataface/core/execute/adapters/sql_adapter.py

@@ -0,0 +1,710 @@
+"""SQL query adapter for executing raw SQL queries.
+
+Stage: EXECUTE
+Purpose: Execute SQL queries via dbt adapters or direct DuckDB connections.
+
+DuckDB queries execute via the raw duckdb driver (already a hard dep) with
+full parameterized query support ($1, $2 placeholders). All other warehouses
+execute via build_adapter() from dbt_adapter_factory — the adapter package for
+that warehouse must be installed (e.g. pip install dbt-postgres).
+
+Security: DuckDB uses parameterized queries. Non-DuckDB queries inline params
+after Jinja rendering — values are validated dashboard YAML variables, not
+raw user input from HTTP.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.source import SourceConfig
+    from dataface.core.execute.adapters.base import ResolvedRelation
+
+from dataface.core.compile.filter_injection import inject_filters
+from dataface.core.compile.models.face.compiled import VariableValues
+from dataface.core.compile.models.query.compiled import (
+    AnyQuery,
+    is_sql_query,
+)
+from dataface.core.compile.parameterized import render_parameterized
+from dataface.core.execute.adapters.base import (
+    BaseAdapter,
+    QueryParams,
+    QueryResult,
+    handle_adapter_error,
+)
+from dataface.core.execute.dbt_jinja import has_dbt_jinja
+from dataface.core.execute.dialects import get_dialect
+from dataface.core.execute.duckdb_config import normalize_duckdb_config
+from dataface.core.execute.sql_guard import validate_select_only, validate_setup_sql
+from dataface.core.execute.sql_literals import (
+    inline_dialect_params as _inline_dialect_params,
+    inline_params as _inline_params,
+    inline_qmark_params as _inline_qmark_params,
+)
+
+logger = logging.getLogger(__name__)
+
+# DuckDB resolves relative read_csv()/read_parquet() paths against the process cwd.
+# The adapter temporarily switches cwd to the face's project root so those queries
+# work, but that global mutation must be serialized across requests.
+_DUCKDB_CWD_LOCK = threading.RLock()
+
+
+class SqlAdapter(BaseAdapter):
+    """Adapter for executing raw SQL queries.
+
+    DuckDB sources use the raw duckdb driver (parameterized, fast).
+    All other warehouses use build_adapter() from dbt_adapter_factory.
+
+    Supported query types: sql
+
+    Example:
+        >>> adapter = SqlAdapter()
+        >>> query = SqlQuery(sql="SELECT * FROM users WHERE id = {{ user_id }}")
+        >>> result = adapter.execute(query, {"user_id": 1})
+    """
+
+    def __init__(
+        self,
+        dbt_project_path: str | None = None,
+        use_example_db: bool = False,
+        connection_string: str | None = None,
+        project_root: Path | None = None,
+        profile_type: str = "duckdb",
+        read_only: bool = True,
+        duckdb_config: dict[str, Any] | None = None,
+        allow_external_access_in_readonly: bool = False,
+    ):
+        """Initialize SQL adapter.
+
+        Args:
+            dbt_project_path: Path to dbt project (default: current directory)
+            use_example_db: If True, use DuckDB example database instead of dbt config
+            connection_string: DuckDB connection string (e.g., ":memory:" or file path)
+            project_root: Root directory for resolving relative file paths in read_csv()
+            profile_type: Database type for dialect selection (e.g., 'postgres', 'duckdb')
+            read_only: If True (default), open DuckDB connections in read-only mode.
+                File-based DuckDB: opened with read_only=True — the driver refuses all writes.
+                In-memory DuckDB (:memory:): always opened read-write regardless of this flag
+                because there is no other way to populate an in-memory database; this is a
+                known exception. enable_external_access=False is still forced for :memory:
+                when read_only=True unless allow_external_access_in_readonly=True.
+
+                When read_only=True (and allow_external_access_in_readonly=False),
+                enable_external_access=False is forced on the DuckDB config regardless of
+                any user-supplied duckdb_config. This blocks httpfs URL fetches and
+                read_csv/read_parquet/read_json against local and remote paths.
+                To allow external access on the default path, use read_only=False.
+
+                Non-DuckDB warehouses (Postgres, Snowflake, BigQuery, etc.) are not affected
+                by this flag — they have no native read-only driver knob. Use SELECT-only
+                credentials/roles at the warehouse level for those.
+
+                Callers that must write (cache backends, test fixture setup) should pass
+                read_only=False explicitly.
+            duckdb_config: Optional DuckDB config dict for the default connection.
+                When read_only=True and allow_external_access_in_readonly=False,
+                enable_external_access in this dict is overridden to False.
+                To enable external access with read_only=True, set both
+                allow_external_access_in_readonly=True AND
+                duckdb_config={"enable_external_access": True}.
+            allow_external_access_in_readonly: Security opt-in. When True AND
+                read_only=True AND duckdb_config contains enable_external_access=True,
+                the adapter passes enable_external_access=True through to DuckDB instead
+                of forcing it to False. Default False preserves the existing defense:
+                read_only=True always implies enable_external_access=False.
+
+                This flag is for local-dev surfaces (e.g. the playground server) that
+                need BOTH a non-exclusive file lock (for coexistence with concurrent
+                dft render / Cursor preview processes) AND external file access
+                (read_csv, read_json_auto). It must NOT be set in multi-tenant or
+                deployed surfaces. Approved callsites are listed on
+                LOCAL_AUTHORING_REGISTRY_KWARGS in adapter_registry.py
+                (playground, MCP, chat, serve).
+        """
+        self.dbt_project_path = Path(dbt_project_path) if dbt_project_path else None
+        self.use_example_db = use_example_db
+        self.connection_string = connection_string or ":memory:"
+        self.project_root = project_root
+        self.profile_type = profile_type
+        self.read_only = read_only
+        self.allow_external_access_in_readonly = allow_external_access_in_readonly
+        self._duckdb_config = duckdb_config
+        self._connection: Any = None  # Lazy-loaded DuckDB connection (default)
+        # Thread-local storage for per-source DuckDB connection caches.
+        self._tls = threading.local()
+        # Track all connections opened across all threads so close() can clean up.
+        self._all_conns: list[Any] = []
+        self._all_conns_lock = threading.Lock()
+        self._manifest: dict[str, Any] | None = None  # Lazy-loaded dbt manifest
+        self._manifest_from_snapshot: bool = False
+        self._prod_manifest: dict[str, Any] | None = None
+        self._prod_manifest_loaded: bool = False
+        self._dialect = get_dialect(profile_type)
+
+    @property
+    def supported_types(self) -> set[str]:
+        """Return supported query types."""
+        return {"sql"}
+
+    def _can_execute(self, query: AnyQuery) -> bool:
+        """Check if this adapter can execute the query.
+
+        DbtAdapter owns: SQL with dbt jinja and no source (needs manifest resolution).
+        SqlAdapter owns: everything else — plain SQL, or any query with a source.
+        """
+        if not is_sql_query(query):
+            return False
+        # Dbt-jinja with no source → DbtAdapter's territory (manifest resolution needed)
+        return not (has_dbt_jinja(query.sql) and query.source is None)
+
+    def _execute(
+        self,
+        query: AnyQuery,
+        variables: VariableValues | None = None,
+        params: QueryParams = None,
+        source_config: SourceConfig | None = None,
+    ) -> QueryResult:
+        """Execute a SQL query.
+
+        Uses parameterized queries (DuckDB) or safe literal inlining (dbt adapters).
+
+        Args:
+            query: AnyQuery object (SqlQuery expected)
+            variables: Variable values for Jinja resolution
+            params: Optional pre-computed parameter values.
+            source_config: Typed source config from SourceResolver. When None,
+                the adapter uses its default connection and configured profile_type.
+
+        Returns:
+            QueryResult with data or error
+        """
+        if not is_sql_query(query):
+            return QueryResult(
+                data=[],
+                error=f"Expected SQL query, got {query.query_type}",
+            )
+
+        sql = query.sql
+        resolved_relations: list[ResolvedRelation] = []
+
+        if self.dbt_project_path:
+            sql, resolved_relations = self._resolve_dbt_sql(sql)
+
+        # Resolver-provided source_config is the single source of truth. When
+        # absent, the adapter falls through to its own default connection using
+        # the configured profile_type.
+        raw_config: dict[str, Any] | None = (
+            source_config.model_dump(by_alias=True)
+            if source_config is not None
+            else None
+        )
+        dialect_name: str = (
+            source_config.type if source_config is not None else self.profile_type
+        )
+
+        # Resolve setup_sql Jinja before branching on dialect.
+        resolved_setup_sql: str | None = None
+        if query.setup_sql:
+            resolved = self._resolve_setup_sql(query.setup_sql, variables)
+            if isinstance(resolved, QueryResult):
+                return resolved
+            resolved_setup_sql = resolved
+
+        if params is not None:
+            resolved_sql = sql
+            resolved_params = params
+        else:
+            try:
+                parameterized = render_parameterized(
+                    sql,
+                    variables=variables or {},
+                    dialect=get_dialect(dialect_name),
+                )
+                resolved_sql = parameterized.sql
+                resolved_params = parameterized.params
+            except (ValueError, KeyError, TypeError) as e:
+                return handle_adapter_error("SQL parameterization", e)
+
+        if query.filters:
+            try:
+                dialect_obj = get_dialect(dialect_name)
+                injected_sql, filter_params = inject_filters(
+                    resolved_sql,
+                    query.filters,
+                    variables or {},
+                    dialect_obj,
+                    param_offset=len(resolved_params),
+                )
+                resolved_sql = injected_sql
+                resolved_params = list(resolved_params) + filter_params
+            except (ValueError, KeyError, TypeError) as e:
+                return handle_adapter_error("filter injection", e)
+
+        if self.use_example_db or dialect_name == "duckdb":
+            # Execute DuckDB setup_sql before main query on the same connection.
+            if resolved_setup_sql:
+                err = self._execute_setup_sql_duckdb(resolved_setup_sql, raw_config)
+                if err is not None:
+                    return err
+            result = self._execute_duckdb(
+                resolved_sql, resolved_params, query, raw_config
+            )
+        else:
+            result = self._execute_via_dbt_adapter(
+                resolved_sql,
+                resolved_params,
+                query,
+                raw_config,
+                dialect_name,
+                setup_sql=resolved_setup_sql,
+            )
+
+        if resolved_relations:
+            result.resolved_relations = resolved_relations
+
+        return result
+
+    def _resolve_setup_sql(
+        self,
+        setup_sql: str,
+        variables: VariableValues | None,
+    ) -> str | QueryResult:
+        """Resolve Jinja in setup_sql. Returns resolved string or a QueryResult on error."""
+        from dataface.core.compile.jinja import resolve_jinja_template
+
+        try:
+            return resolve_jinja_template(setup_sql, variables=variables or {})
+        except Exception as e:  # noqa: BLE001
+            return handle_adapter_error("setup_sql template resolution", e)
+
+    def _execute_setup_sql_duckdb(
+        self,
+        resolved_setup_sql: str,
+        source_config: dict[str, Any] | None = None,
+    ) -> QueryResult | None:
+        """Execute setup_sql on a DuckDB connection. Returns None on success."""
+        try:
+            validate_setup_sql(resolved_setup_sql, dialect="duckdb")
+            with _DUCKDB_CWD_LOCK:
+                duckdb_conn = self._get_duckdb_connection_for_query(source_config)
+                duckdb_conn.execute(resolved_setup_sql)
+        except Exception as e:  # noqa: BLE001
+            return handle_adapter_error("setup_sql execution", e)
+        return None
+
+    def _execute_duckdb(
+        self,
+        sql: str,
+        params: list[Any],
+        query: AnyQuery,
+        source_config: dict[str, Any] | None = None,
+    ) -> QueryResult:
+        """Execute SQL query using DuckDB with parameterized execution.
+
+        Uses parameterized queries to prevent SQL injection attacks.
+        Parameters are passed separately from the SQL string.
+        """
+        import importlib.util
+        import os
+
+        if importlib.util.find_spec("duckdb") is None:
+            return QueryResult(
+                data=[],
+                error="DuckDB not installed - install with: pip install duckdb",
+            )
+
+        try:
+            validate_select_only(sql, dialect="duckdb")
+            with _DUCKDB_CWD_LOCK:
+                conn = self._get_duckdb_connection_for_query(source_config)
+
+                original_cwd = os.getcwd()
+                if self.project_root:
+                    os.chdir(self.project_root)
+
+                try:
+                    result = conn.execute(sql, params or [])
+                    columns = (
+                        [desc[0] for desc in result.description]
+                        if result.description
+                        else []
+                    )
+                    rows = result.fetchall()
+                finally:
+                    os.chdir(original_cwd)
+
+            if query.limit and query.limit > 0:
+                rows = rows[: query.limit]
+
+            data = [dict(zip(columns, row, strict=False)) for row in rows]
+            col_descs = (
+                {desc[0]: tuple(desc) for desc in result.description}
+                if result.description
+                else None
+            )
+
+            return QueryResult(
+                data=data, columns=columns, column_descriptions=col_descs
+            )
+
+        except Exception as e:  # noqa: BLE001
+            return handle_adapter_error("DuckDB SQL execution", e)
+
+    @staticmethod
+    def _push_limit_into_sql(sql: str, limit: int) -> str:
+        """Wrap sql with an outer LIMIT N.
+
+        Always wraps — the outer LIMIT bounds the inner one when both are present,
+        yielding the smaller of the two values (safe and idempotent). Checking for
+        'limit' in sql.lower() is brittle: it matches column names (limit_amount),
+        CTEs, comments, and string literals, causing silent full-table scans on
+        large tables when the wrapping is skipped.
+
+        Trailing semicolons are stripped before wrapping — they appear in SQL pasted
+        from IDEs and would produce a parse error inside the subquery on BigQuery,
+        Snowflake, Redshift, and Postgres.
+        """
+        stripped = sql.rstrip().rstrip(";").rstrip()
+        return f"SELECT * FROM ({stripped}) AS _dft_limit_wrap LIMIT {limit}"
+
+    def _execute_via_dbt_adapter(
+        self,
+        sql: str,
+        params: list[Any],
+        query: AnyQuery,
+        source_config: dict[str, Any] | None,
+        dialect_name: str,
+        setup_sql: str | None = None,
+    ) -> QueryResult:
+        """Execute SQL via the dbt adapter for non-DuckDB warehouses.
+
+        Params are inlined as SQL literals — dbt adapter.execute() only accepts
+        plain SQL. This is safe because params come from compiled dashboard YAML
+        variables, not raw user input.
+
+        For dialects that return the full result set (e.g. BigQuery), query.limit
+        is pushed into the SQL string before execution to avoid full-table scans.
+
+        setup_sql (if any) runs inside the same connection_named("dataface_query")
+        block as the main query so temp functions/tables are visible to the query.
+        BigQuery CREATE TEMP FUNCTION is session-scoped — two connection_named calls
+        produce two distinct connections and the temp function would not be visible.
+        """
+        from dataface.core.execute.adapters.dbt_adapter_factory import build_adapter
+
+        if source_config is None:
+            return QueryResult(
+                data=[],
+                error=(
+                    f"No source config found for dialect '{dialect_name}'. "
+                    f"Provide an inline source: block or a named source in _sources.yaml."
+                ),
+            )
+
+        try:
+            param_list = list(params) if params else []
+            # The dbt adapter.execute() accepts only plain SQL — no bound params.
+            # Inline params as SQL literals before passing the SQL string.
+            # Named-param dialects (BigQuery @paramN, Databricks :paramN, SQL
+            # Server @pN) use inline_dialect_params with the dialect's param()
+            # method so each placeholder format is matched correctly.
+            # All other dialects use $N positional placeholders.
+            dialect_obj = get_dialect(dialect_name)
+            if dialect_obj.uses_named_params:
+                inlined_sql = _inline_dialect_params(sql, param_list, dialect_obj.param)
+            elif dialect_obj.param(1) == "?":
+                inlined_sql = _inline_qmark_params(sql, param_list)
+            else:
+                inlined_sql = _inline_params(sql, param_list)
+
+            # Push LIMIT into the SQL for all non-DuckDB dialects. dbt-adapters'
+            # execute(..., fetch=True) materializes the full agate.Table in memory
+            # before returning — Python slicing after the fact pulls the entire
+            # result set over the wire. DuckDB is excluded because it executes
+            # locally and its native cursor handles LIMIT correctly without rewriting.
+            if dialect_name != "duckdb" and query.limit and query.limit > 0:
+                inlined_sql = self._push_limit_into_sql(inlined_sql, query.limit)
+
+            # Validate setup_sql + main SQL separately (different allowlists)
+            # before opening the dbt connection — fail-closed if either piece
+            # contains mutating SQL. validate_setup_sql also runs in the DuckDB
+            # setup path; running it here too is the correct re-check for the
+            # combined-script branch since the strings hit a different driver.
+            if setup_sql:
+                validate_setup_sql(setup_sql, dialect=dialect_name)
+            validate_select_only(inlined_sql, dialect=dialect_name)
+
+            adapter = build_adapter(source_config)
+            with adapter.connection_named("dataface_query"):
+                if setup_sql:
+                    # BigQuery rejects standalone "CREATE TEMP FUNCTION" — it
+                    # must appear in the same script as a query that uses
+                    # (or at least follows) it. Sending setup_sql in a separate
+                    # execute() call also drops session-scoped TEMP entities
+                    # before the main query runs. Concatenate so dbt sends them
+                    # as one multi-statement script.
+                    combined_sql = setup_sql.rstrip().rstrip(";") + ";\n" + inlined_sql
+                    _, table = adapter.execute(
+                        combined_sql, auto_begin=True, fetch=True
+                    )
+                else:
+                    _, table = adapter.execute(inlined_sql, auto_begin=True, fetch=True)
+
+            columns = [col.lower() for col in table.column_names]
+            rows = list(table.rows)
+
+            # Python-side limit as safety net for non-BQ dialects
+            if query.limit and query.limit > 0:
+                rows = rows[: query.limit]
+
+            data = [dict(zip(columns, row, strict=False)) for row in rows]
+            return QueryResult(data=data, columns=columns)
+
+        except Exception as e:  # noqa: BLE001
+            return handle_adapter_error(f"{dialect_name} SQL execution", e)
+
+    def _get_duckdb_connection_for_query(
+        self, source_config: dict[str, Any] | None = None
+    ) -> Any:
+        """Get DuckDB connection for a query.
+
+        Uses the typed ``source_config`` (resolver-provided) when it points at a
+        DuckDB source; otherwise falls through to the adapter's default
+        connection. The thread-local connection cache is keyed by
+        ``source_config['path']`` — two named DuckDB sources that point at the
+        same path share a connection. For ``:memory:`` this means two distinct
+        named sources both using ``:memory:`` collapse into one in-memory DB;
+        callers needing isolated in-memory DBs must use distinct paths (e.g.
+        ``:memory:db_a``, ``:memory:db_b``) or different connection_strings.
+        """
+        if source_config and source_config.get("type") == "duckdb":
+            schema = source_config.get("schema") or ""
+            path = str(source_config.get("path") or ":memory:")
+            cache_key = f"{path}\0{schema}" if schema else path
+            return self._create_duckdb_connection_from_config(source_config, cache_key)
+        return self._get_duckdb_connection()
+
+    def _resolve_duckdb_config(
+        self, source_config: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        """Resolve DuckDB config: source-level overrides adapter-level default."""
+        return normalize_duckdb_config(source_config) or self._duckdb_config
+
+    def _create_duckdb_connection_from_config(
+        self, source_config: dict[str, Any], cache_key: str
+    ) -> Any:
+        """Create or retrieve a cached DuckDB connection from source config."""
+        import duckdb
+
+        if "database" in source_config and "path" not in source_config:
+            raise ValueError(
+                "DuckDB source_config uses the unsupported 'database' key. "
+                'Use \'path\' instead (e.g. {"type": "duckdb", "path": "db.duckdb"}).'
+            )
+        db_path = source_config.get("path", ":memory:")
+        raw_config = self._resolve_duckdb_config(source_config)
+        duckdb_config = raw_config or None
+
+        sources = getattr(self._tls, "sources", None)
+        if sources is None:
+            sources = self._tls.sources = {}
+
+        if cache_key not in sources:
+            resolved_path = db_path
+            if (
+                self.project_root
+                and db_path != ":memory:"
+                and not Path(db_path).is_absolute()
+            ):
+                resolved_path = str(self.project_root / db_path)
+
+            conn = duckdb.connect(
+                resolved_path,
+                **self._resolve_duckdb_connect_kwargs(
+                    resolved_path,
+                    self.read_only,
+                    duckdb_config,
+                    self.allow_external_access_in_readonly,
+                ),
+            )
+            schema = source_config.get("schema") or ""
+            if schema:
+                if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", schema):
+                    raise ValueError(
+                        f"Invalid schema name {schema!r}: must match "
+                        r"^[A-Za-z_][A-Za-z0-9_]*$"
+                    )
+                conn.execute("SET search_path = ?", [f"{schema},main"])
+            sources[cache_key] = conn
+            with self._all_conns_lock:
+                self._all_conns.append(conn)
+
+        return sources[cache_key]
+
+    def close(self) -> None:
+        """Close all database connections."""
+        if self._connection:
+            self._connection.close()
+            self._connection = None
+
+        with self._all_conns_lock:
+            conns, self._all_conns = self._all_conns, []
+        for conn in conns:
+            conn.close()
+
+        if hasattr(self._tls, "sources"):
+            self._tls.sources = {}
+
+    @staticmethod
+    def _resolve_duckdb_connect_kwargs(
+        path: str,
+        read_only: bool,
+        duckdb_config: dict[str, Any] | None,
+        allow_external_access_in_readonly: bool = False,
+    ) -> dict[str, Any]:
+        """Build duckdb.connect() kwargs for the given path and security posture.
+
+        When read_only=True and allow_external_access_in_readonly=False (default):
+        - Adds read_only=True for file-based paths (not :memory: — in-memory DuckDB
+          must always be opened read-write; this is a known exception).
+        - Forces enable_external_access=False in the config, overriding any
+          user-supplied duckdb_config value. This is the defense-in-depth contract:
+          no quiet bypass via config when the adapter is set to read-only.
+
+        When read_only=True and allow_external_access_in_readonly=True:
+        - Same read_only=True driver flag for file-based paths (non-exclusive lock).
+        - enable_external_access is NOT forced to False; caller's duckdb_config value
+          passes through. This is the deliberate local-dev opt-in for playground,
+          MCP, chat, and serve: non-exclusive lock + external file reads. Approved
+          callsites are listed on LOCAL_AUTHORING_REGISTRY_KWARGS in adapter_registry.py.
+
+        When read_only=False:
+        - No read_only driver flag.
+        - duckdb_config is passed through as-is.
+        """
+        kwargs: dict[str, Any] = {}
+        if read_only and path != ":memory:":
+            kwargs["read_only"] = True
+        if duckdb_config is not None or read_only:
+            config = dict(duckdb_config or {})
+            if read_only and not (
+                allow_external_access_in_readonly
+                and config.get("enable_external_access") is True
+            ):
+                config["enable_external_access"] = False
+            if config:
+                kwargs["config"] = config
+        return kwargs
+
+    def _get_duckdb_connection(self) -> Any:
+        """Get or create the default DuckDB connection."""
+        if self._connection is None:
+            import duckdb
+
+            if self.use_example_db:
+                self._connection = duckdb.connect(":memory:")
+            elif self.dbt_project_path:
+                from dataface.core.execute.adapters.dbt_utils import (
+                    DBT_PROJECT_DB_NAMES,
+                )
+
+                conn = None
+                for db_name in DBT_PROJECT_DB_NAMES:
+                    db_path = self.dbt_project_path / "data" / db_name
+                    if db_path.exists():
+                        conn = duckdb.connect(
+                            str(db_path),
+                            **self._resolve_duckdb_connect_kwargs(
+                                str(db_path),
+                                self.read_only,
+                                self._duckdb_config,
+                                self.allow_external_access_in_readonly,
+                            ),
+                        )
+                        break
+
+                if conn is None:
+                    conn = duckdb.connect(
+                        self.connection_string,
+                        **self._resolve_duckdb_connect_kwargs(
+                            self.connection_string,
+                            self.read_only,
+                            self._duckdb_config,
+                            self.allow_external_access_in_readonly,
+                        ),
+                    )
+
+                self._connection = conn
+            else:
+                self._connection = duckdb.connect(
+                    self.connection_string,
+                    **self._resolve_duckdb_connect_kwargs(
+                        self.connection_string,
+                        self.read_only,
+                        self._duckdb_config,
+                        self.allow_external_access_in_readonly,
+                    ),
+                )
+
+        return self._connection
+
+    def _get_manifest(self) -> dict[str, Any] | None:
+        """Load dbt manifest.json if available."""
+        if self._manifest is not None:
+            return self._manifest
+        if not self.dbt_project_path:
+            return None
+
+        target_path = self.dbt_project_path / "target" / "manifest.json"
+        snapshot_path = self.dbt_project_path / "manifest.snapshot.json"
+
+        from dataface.core.execute.adapters.dbt_utils import load_dbt_manifest
+
+        self._manifest = load_dbt_manifest(self.dbt_project_path)
+        self._manifest_from_snapshot = (
+            self._manifest is not None
+            and not target_path.exists()
+            and snapshot_path.exists()
+        )
+        return self._manifest
+
+    def _get_prod_manifest(self) -> dict[str, Any] | None:
+        """Load the committed prod manifest snapshot, if available."""
+        if self._prod_manifest_loaded:
+            return self._prod_manifest
+        self._prod_manifest_loaded = True
+        if not self.dbt_project_path:
+            return None
+        if self._manifest_from_snapshot:
+            return None
+        snapshot_path = self.dbt_project_path / "manifest.snapshot.json"
+        if not snapshot_path.exists():
+            return None
+        import json
+
+        try:
+            with open(snapshot_path) as f:
+                self._prod_manifest = json.load(f)
+        except (OSError, json.JSONDecodeError) as e:
+            logger.debug("Failed to load prod manifest snapshot: %s", e)
+        return self._prod_manifest
+
+    def _resolve_dbt_sql(self, sql: str) -> tuple[str, list[ResolvedRelation]]:
+        """Resolve SQL with dbt-specific Jinja functions (ref, source)."""
+        from dataface.core.execute.adapters.dbt_utils import (
+            resolve_dbt_refs_with_provenance,
+        )
+
+        manifest = self._get_manifest()
+        if not manifest:
+            return sql, []
+
+        prod_manifest = self._get_prod_manifest()
+        return resolve_dbt_refs_with_provenance(sql, manifest, prod_manifest)