[sd-db]

Description

use_materialization_v2 can only be set project-wide today, as a behavior flag under flags:. For table and incremental models, it chooses between two materialization paths with a real tradeoff:

• Default: a single atomic CREATE OR REPLACE TABLE … AS SELECT. Readers never see an empty table, but column masks can't be applied at create time.
• V2: create the table, then insert. Column masks, comments, and constraints are applied at create time, but the table is briefly empty during a refresh.

A project that needs create-time masks on a few sensitive tables has to give up atomic refresh everywhere, or the other way round. This makes use_materialization_v2 a model config for table and incremental models, matching the dbt Fusion engine change in dbt-labs/dbt#16661:

• DatabricksConfig.use_materialization_v2: Optional[bool]. It can be set in {{ config(...) }}, in properties YAML, or per folder with +use_materialization_v2 in dbt_project.yml, and inherits like other model configs.
• A new use_materialization_v2() macro returns the model's setting when set. If the setting is unset or null, it returns the use_materialization_v2 behavior flag.
• Quoted values such as "false" arrive in Jinja as strings, and 'false' is truthy. The macro compares them case-insensitively to true, as Fusion does when it parses the config.
• The table and incremental materializations branch on the macro instead of reading the flag directly.

Views use one shared implementation in 1.13.0 and ignore this config. That unification is separate work, and this PR doesn't change view.sql. view_update_via_alter stays a separate opt-in setting. Seeds, snapshots, materialized views, streaming tables, metric views, and clones don't use the flag and are unchanged.

Projects that don't set the model config behave exactly as before.

Until dbt Core picks up the updated config schema from Fusion, dbt Core may warn that use_materialization_v2 is an unrecognized config key. The setting still takes effect.

Testing

• Unit (tests/unit/macros/materializations/test_use_materialization_v2.py): an unset or null setting follows the flag both ways. true/false and the strings "true"/"False" override it. This is the regression coverage for the change. Both table and incremental paths are already covered by the existing V1 and V2 functional suites.
• End to end, run locally on a UC SQL warehouse: with the flag off and +use_materialization_v2: true, table and incremental models were built by V2: DESCRIBE HISTORY showed a WRITE and no … AS SELECT. With the flag on and config(use_materialization_v2=false), they were built by the default path's CTAS. Models that didn't set the config followed the flag. These checks were not committed as functional tests.

Checklist

• I have run this code in development and it appears to resolve the stated issue
• This PR includes tests, or tests are not required/relevant for this PR
• I have updated the CHANGELOG.md and added information about my change to the "dbt-databricks next" section.

This pull request and its description were written by Isaac.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
dbt/adapters/databricks
impl.py
Project Total

This report was generated by python-coverage-comment-action