Upgrade to dbt™ 1.12

dbt Core™ 1.12 is the last stop before v2: it ships an opt-in Rust parser so you can test v2 compatibility early, and it flips seven behavior flags from earlier releases to enabled by default. This guide is based on the official dbt™ upgrade guide for v1.12; check the dbt Core™ 1.12 changelog for the full detail.

Prerequisites

An Admin role in Paradime, needed to change the workspace dbt™ version.
Your project on dbt™ 1.11, upgraded via the 1.11 guide.

Estimated time: 45 minutes, plus project testing.

What can break

The biggest upgrade impact is the set of behavior flags that become enabled by default in 1.12. If you never set them explicitly, their behavior changes when you switch versions:

Flag (now enabled by default)	Effect after upgrading
`require_all_warnings_handled_by_warn_error`	All warnings route through the `--warn-error` / `--warn-error-options` handler. Only affects projects using `warn_error: true` or `--warn-error`.
`require_batched_execution_for_custom_microbatch_strategy`	Custom microbatch strategies now execute in batches. Setting the flag to `false` with a custom microbatch macro triggers a deprecation warning.
`require_nested_cumulative_type_params`	Cumulative metrics using un-nested syntax now raise an error instead of a warning; they must nest under `cumulative_type_params` (required since 1.9).
`require_yaml_configuration_for_mf_time_spines`	Suppresses the `MFTimespineWithoutYamlConfigurationDeprecation` warning; legacy SQL file configuration keeps working. No functional impact.
`skip_nodes_if_on_run_start_fails`	A failing `on-run-start` hook now skips all selected resources.
`state_modified_compare_more_unrendered_values`	`state:modified` compares unrendered values, reducing false positives across target environments.
`validate_macro_args`	Macro arguments are validated by default.

You can opt out of any of these by setting the flag to false under flags: in dbt_project.yml, but note that the v2 engine removes that opt-out.

What’s new in dbt™ 1.12

Opt-in v2 parser

The --use-v2-parser flag delegates parsing to the new v2 Rust parser instead of the v1 Python parser. It is significantly faster, especially on larger projects where it can be 5–10× quicker, and it is the natural first step toward v2 compatibility: you can catch and fix project issues gradually rather than all at once. The flag changes no behavior unless explicitly set.

The Rust parser is beta. Its output manifest may differ from the Python parser’s in edge cases, which can affect downstream behavior. Fall back by removing --use-v2-parser, and report issues to dbt Labs. See Opt-in v2 parser.

New Iceberg `catalogs` spec

The catalogs.yml spec was reworked to be simpler and current with ecosystem Iceberg support. The new spec can also power cross-platform dbt™ Mesh.

Native private packages

packages.yml and dependencies.yml support installing packages from private GitHub, GitLab, or Azure DevOps repositories with the private key, using your system’s SSH configuration for authentication instead of a token or full Git URL:

packages:
  - private: your-org/your-internal-repo
    provider: "github"  # Supported values: "github", "gitlab", "ado"

UDF extensions

JavaScript UDFs on Snowflake and BigQuery: a .js file in functions/ plus a YAML file with arguments and return type.
Overloaded UDFs via the overloads property, so one function name accepts different input types. Supported for SQL UDFs in Snowflake and Postgres, and Python UDFs in Snowflake. All overloads form one DAG node; on retry, only failed overloads rerun.
Public third-party PyPI packages for Python UDFs via the optional packages config; the warehouse installs them when creating the UDF.
Python UDFs on Databricks (requires Unity Catalog; runtime_version and entry_point are ignored), in addition to Snowflake and BigQuery.

`latest_version_pointer` for versioned models

dbt™ can automatically create a pointer view named after a versioned model’s base name (for example dim_customers) once the latest version materializes, so you can query the current version without maintaining a view manually. Enable project-wide with the latest_version_pointer_enabled_by_default: true flag, per model with latest_version_pointer.enabled, and customize the name with latest_version_pointer.alias or the generate_latest_version_pointer_alias macro.

`--sql` flag for `dbt run-operation`

Execute ad hoc statements directly against your warehouse without defining a macro, for one-off operations like dropping a table, applying grants, or a data fix. The statement runs through the full Jinja compilation pipeline, so ref(), source(), var(), target, and other context variables are available.

`on_error` model config

Control whether downstream models run when an upstream model fails. Set on_error: continue on a model to let its downstream models still attempt to run; the default (skip_children) skips all downstream models on failure. --fail-fast takes precedence and stops at the first failure regardless.

Semantic layer updates

Apache Ossie support: place Ossie-format .json files in an osi/ directory at the project root (configurable with osi-paths) and dbt™ parses them into the manifest alongside native semantic models. Ossie versions 0.1.0 and 0.1.1 are supported; other versions raise a parse error. dbt™ also writes an osi_document.json artifact to target/ at parse time.
New Semantic Layer YAML spec: semantic_model nests directly under each model instead of being a standalone top-level key, entities and dimensions are defined at the column level, measures are replaced by type: simple metrics within the model, and type_params is deprecated in favor of top-level keys within each metric. See Migrate to the latest YAML spec.

`selector` method for named YAML selectors

Reference a named selector from selectors.yml inside --select or --exclude, for example --select selector:my_selector, and compose it with other selection methods and operators. Combining the legacy --selector flag with --select / --exclude still ignores the latter two and now also raises a warning.

`vars.yml`

Define project variables in a vars.yml file at the project root instead of dbt_project.yml. It is parsed before dbt_project.yml, so dbt_project.yml can reference those variables with {{ var('...') }}. You cannot define variables in both files.

Improved exception handling

Internal failures that previously surfaced as raw Python errors (AttributeError, KeyError, IndexError, RuntimeError) are replaced with clear dbt™ errors such as CompilationError and ParsingError. Highlights: dependency-graph cycles raise a CompilationError, run-operation failures include the exception message in run_results.json, and snapshot validation failures show the relevant message without the long Python traceback. Use --debug when you need the full Python output.

New behavior flags (disabled by default)

Introduced in 1.12, opt-in:

Flag	What it does when enabled
`require_valid_schema_from_generate_schema_name`	Raises a parsing error (instead of a deprecation warning) when a custom `generate_schema_name` macro returns `null`.
`require_sql_header_in_test_configs`	Allows `sql_header` in the `config` of a generic data test at the model or column level.
`require_corrected_analysis_fqns`	Applies project-level analysis configuration from `dbt_project.yml` (previously silently ignored) and corrects analysis fully qualified names, for example `your_project.my_analysis` instead of `your_project.analyses.my_analysis`.
`require_source_and_semantic_model_names_without_spaces`	Raises an error (instead of a warning) when a source or semantic model name contains a space.
`allow_jinja_file_extensions`	Recognizes `.j2`, `.jinja`, and `.jinja2` suffixes on `.sql` and `.md` files, enabling Jinja-aware IDE syntax highlighting.
`latest_version_pointer_enabled_by_default`	Creates a latest version pointer view for every versioned model without per-model configuration.

Adapter-specific changes

Snowflake: snowflake.quote_args controls argument-name quoting on JavaScript UDFs; iceberg_version: 3 opts Iceberg tables into V3 (immutable after creation, default 2); the scheduler parameter on dynamic tables chooses between Snowflake-managed (ENABLE, requires target_lag) and dbt™-managed (DISABLE, dbt™‘s default) refreshes; snowflake_initialization_warehouse sets a separate warehouse for a dynamic table’s initial build; the transient config (and the snowflake_default_transient_dynamic_tables flag) creates dynamic tables without a Fail-safe period.
BigQuery: parallel microbatch execution is now supported; bigquery_use_standard_sql_for_partitions defaults to true (standard SQL via INFORMATION_SCHEMA.PARTITIONS) ahead of BigQuery’s legacy SQL deprecation on June 1, 2026, and can be set to false to revert; bigquery_reject_wildcard_metadata_source_freshness raises an error on metadata freshness checks against wildcard tables like events_*; job_link_info_level_log: true logs job links at info level; job_execution_timeout_seconds can be set per model, snapshot, seed, or test.
Redshift: redshift_skip_autocommit_transaction_statements: true skips unnecessary BEGIN/COMMIT/ROLLBACK statements when autocommit is enabled (defaults to false); the query_group session parameter tags queries for Workload Manager routing, configurable in the profile and overridable per model.
Databricks: the row_filter config applies a Unity Catalog row filter to table, incremental, materialized_view, and streaming_table materializations (not regular views or Hive Metastore relations); databricks_tags supports key-only tags ('' or None values) and now merges additively across hierarchy levels, with lower-level values winning on conflicts.

Quick hits

dbt™ surfaces occasional, non-blocking optimization hints, enabled by default; disable with the hints_enabled flag.
Fusion-specific names in warn_error_options (for example StaticAnalysis) are tolerated and ignored with a note, so configs can be shared across dbt Core™ and the v2 engine.
Macros invoked with dbt run-operation can ref() models with private or protected access without a DbtReferenceError.
dbt seed --empty creates seed tables with the correct schema but no data.
Environment variables load automatically from a .env file in the working directory; shell variables take precedence, and dbt init adds .env to the default .gitignore.
dbt compile writes compiled SQL for snapshots to target/compiled/, one output file per snapshot.

Upgrade steps

Audit the newly-default behavior flags

Check your project against the “What can break” table: un-nested cumulative metrics now error, failing on-run-start hooks now skip everything, and macro argument validation is on. Fix the code, or explicitly set a flag to false in dbt_project.yml to defer (remembering v2 removes the opt-out).

Test on 1.12 in a non-production environment

Pin a Bolt environment to dbt™ 1.12 in Settings > Environments or use a staging workspace, and run your schedules and a full dbt build from the Code IDE terminal.

Trial the v2 parser

Run dbt parse --use-v2-parser in the Code IDE terminal and fix anything it reports. This is the lowest-risk way to start on v2 readiness.

Switch the workspace version

In Settings > Workspace > General, select Change version, choose 1.12, and save. See Upgrade dbt Core™ version.

dbt --version reports 1.12.x, Bolt schedules run green, and dbt parse --use-v2-parser completes cleanly. The most likely failures come from the flipped behavior flags: cumulative metrics missing cumulative_type_params now error, and on-run-start hook failures now skip the whole run.

Next steps

Prepare for dbt™ v2

What the v2 engine removes, and the readiness checklist.

Upgrade with the DinoAI agent

Automate the flag audit and fixes with an agent-driven PR.

Manage dbt™ version

The workspace setting and per-environment overrides.

Official v1.12 upgrade guide

The upstream dbt™ documentation this guide is based on.

Foundations

Automate with AI agents

Set up & configure

Orchestrate data pipelines

Migrate to Paradime

Develop in Paradime

Learn dbt™

Upgrade to dbt™ 1.12

What can break

What’s new in dbt™ 1.12

Opt-in v2 parser

New Iceberg `catalogs` spec

Native private packages

UDF extensions

`latest_version_pointer` for versioned models

`--sql` flag for `dbt run-operation`

`on_error` model config

Semantic layer updates

`selector` method for named YAML selectors

`vars.yml`

Improved exception handling

New behavior flags (disabled by default)

Adapter-specific changes

Quick hits

Upgrade steps

Next steps

Prepare for dbt™ v2

Upgrade with the DinoAI agent

Manage dbt™ version

Official v1.12 upgrade guide

​What can break

​What’s new in dbt™ 1.12

​Opt-in v2 parser

​New Iceberg catalogs spec

​Native private packages

​UDF extensions

​latest_version_pointer for versioned models

​--sql flag for dbt run-operation

​on_error model config

​Semantic layer updates

​selector method for named YAML selectors

​vars.yml

​Improved exception handling

​New behavior flags (disabled by default)

​Adapter-specific changes

​Quick hits

​Upgrade steps

​Next steps

Prepare for dbt™ v2

Upgrade with the DinoAI agent

Manage dbt™ version

Official v1.12 upgrade guide

What can break

What’s new in dbt™ 1.12

Opt-in v2 parser

New Iceberg `catalogs` spec

Native private packages

UDF extensions

`latest_version_pointer` for versioned models

`--sql` flag for `dbt run-operation`

`on_error` model config

Semantic layer updates

`selector` method for named YAML selectors

`vars.yml`

Improved exception handling

New behavior flags (disabled by default)

Adapter-specific changes

Quick hits

Upgrade steps

Next steps