Skip to main content

Upgrading to v1.12

Beta coming soon

dbt Core v1.12 is not yet available in beta. We will update this guide when it becomes available.

Resources​

What to know before upgrading​

dbt Labs is committed to providing backward compatibility for all versions 1.x. Any behavior changes will be accompanied by a behavior change flag to provide a migration window for existing projects. If you encounter an error upon upgrading, please let us know by opening an issue.

dbt provides the functionality from new versions of dbt Core via release tracks with automatic upgrades. If you have selected the Latest release track in dbt, you already have access to all the features, fixes, and other functionality included in the latest dbt Core version! If you have selected the Compatible release track, you will have access to the next monthly Compatible release after the dbt Core v1.12 final release.

New and changed features and functionality​

on_error model config Beta​

You can configure whether downstream models run when an upstream model fails using the on_error config. Set on_error: continue on a model to allow its downstream models to still attempt to run even when it fails. By default (skip_children), dbt skips all downstream models on failure. Note that --fail-fast takes precedence — runs with --fail-fast stop at the first failure, even if a model is configured with on_error: continue.

New Semantic Layer YAML spec​

dbt Core v1.12 adds support for the latest Semantic Layer YAML specification, which simplifies how you define metrics and dimensions by embedding semantic annotations directly alongside each model.

Key changes in the new spec:

  • semantic_model is nested directly under each model instead of being a standalone top-level key.
  • Entities and dimensions are defined at the column level.
  • Measures are replaced with type: simple metrics defined within the model.
  • type_params is deprecated; its parameters are now top-level keys within each metric definition.

For migration guidance and a comparison between the latest spec and the legacy spec, refer to Migrate to the latest YAML spec. For the semantic model reference, refer to Semantic models.

.env file for environment variables Beta​

dbt Core now automatically loads environment variables from a .env file in your current working directory. Shell environment variables take precedence over .env values. New projects created with dbt init include .env in the default .gitignore. For more information, refer to About env_var function.

packages config for Python UDFs Beta​

You can specify public third-party PyPI packages for your Python UDF with the optional packages config. The warehouse installs these packages when it creates the UDF, which lets your UDF use functionality from external Python libraries. For more information, refer to Defining UDFs in dbt and the packages config reference.

selector method for named YAML selectors Beta​

You can reference a named selector from selectors.yml inside --select or --exclude using the selector method (for example, selector:my_selector). This makes it easier to compose reusable YAML selectors with other selection methods, graph operators, and set operators on the command line without duplicating logic.

When you use the legacy --selector flag together with --select or --exclude, dbt only uses --selector for node selection and ignores --select and --exclude. Starting in dbt Core v1.12, dbt also raises a warning when these flags are combined. If you want to combine a selector with --select or --exclude, use the new selector: method instead.

Compiled SQL for snapshots Beta​

dbt compile writes compiled SQL for snapshots to target/compiled/, consistent with models, tests, analyses, and functions. Each snapshot gets its own output file, named from the snapshot identifier, so multiple snapshot blocks in the same source file do not share one compiled path.

For more information, refer to About dbt compile.

Support for vars.yml Beta​

You can use the vars.yml file, located at the project root, to define project variables. This keeps variable definitions in one place and helps simplify dbt_project.yml. Variables defined in vars.yml are parsed before dbt_project.yml, so you can reference them in dbt_project.yml using {{ var('...') }}. You can continue to define variables in dbt_project.yml as before, but you cannot define variables in both files. For details and precedence, refer to Project variables.

Improved exception handling and error messages​

dbt Core v1.12 improves exception handling so error messages are clearer and stack traces are easier to interpret.

Previously, some internal failures surfaced as Python errors (for example, AttributeError, KeyError, IndexError, RuntimeError), which could be difficult to understand. In dbt Core v1.12, these are replaced with dbt errors (such as CompilationError and ParsingError) that include a clear error message. When you need the full Python error output for debugging, use --debug or check the logs.

Key improvements:

  • Cleaner default output: Built-in Python exceptions (Exception, ValueError, RuntimeError) are replaced with dbt errors, so dbt no longer treats them as internal errors or displays unnecessary stack traces.
  • Parsing and config validation: Invalid field values raise a ParsingError instead of a raw InvalidFieldValue exception when applying dbt_project.yml configs to resources. In a generic data test, a config value that is a string or a number instead of a set of key-value pairs raises a TestConfigNotDictError.
  • Snapshot validation: When snapshot validation fails, dbt shows the relevant error message and omits the long Python error output.
  • dbt run-operation: When a run-operation call fails, the exception message is included in run_results.json, which makes failures easier to inspect.
  • Cycle detection: Dependency graph cycles raise a CompilationError instead of the built-in RuntimeError.
  • Semantic model dependencies: When a semantic model references a disabled or missing model, dbt raises a CompilationError instead of an IndexError.
 More scenarios with exception handling improvements
  • A string concatenation in a doc() argument (such as doc('foo' ~ 'bar')) is skipped during doc block resolution instead of crashing with an AttributeError.
  • A Jinja variable (such as doc(my_variable)) raises a DocTargetNotFoundError.
  • When a meta value in schema.yml references an undefined Jinja variable, dbt converts it to None instead of raising a TypeError during partial parse.
  • When sources, tables, exposure tags, or packages are set to null, dbt treats them as an empty list instead of raising a TypeError.
  • When a model with custom contract constraints is evaluated during state:modified selection, dbt returns None for unknown constraint types instead of raising a KeyError.

Managing changes to legacy behaviors​

dbt Core v1.12 introduces new flags for managing changes to legacy behaviors. You may opt into recently introduced changes (disabled by default), or opt out of mature changes (enabled by default), by setting true / false values, respectively, for flags in dbt_project.yml.

You can read more about each of these behavior changes in the following links:

Adapter-specific features and functionalities​

Snowflake​

  • You can set the iceberg_version config on Snowflake Iceberg tables to control which Iceberg format version Snowflake uses. Set it to 3 to use Iceberg V3, which improves VARIANT type support and makes row-level changes more efficient by tracking deletions separately instead of rewriting data. The default value is 2. Note that you cannot change the value of iceberg_version after table creation.

  • You can configure the scheduler parameter on Snowflake dynamic tables to control how refreshes are managed. Setting it to ENABLE lets Snowflake automatically refresh the dynamic table, while DISABLE means dbt manages refreshes during model execution. When scheduler is set to ENABLE, you must also specify target_lag.

    By default, dbt sets scheduler to DISABLE (unlike Snowflake’s native default of ENABLE), so dbt controls the refresh schedule unless you explicitly opt in to Snowflake’s scheduler. If you specify target_lag without setting scheduler, dbt automatically sets scheduler to ENABLE.

  • You can use the snowflake_initialization_warehouse parameter to specify a warehouse for the initial build and reinitialization of a dynamic table, separate from snowflake_warehouse which is used for regular incremental refreshes.

  • You can create Snowflake dynamic tables as transient (no Fail-safe period) by setting the transient config on models.

    When transient is not set on a model, the snowflake_default_transient_dynamic_tables flag controls the default. Set this flag to true to make all dynamic tables transient by default.

BigQuery​

  • Added the bigquery_use_standard_sql_for_partitions flag. When set to true, dbt uses standard SQL (INFORMATION_SCHEMA.PARTITIONS) instead of legacy SQL ($__PARTITIONS_SUMMARY__) when calling get_partitions_metadata(). The flag defaults to false in this release. BigQuery is deprecating legacy SQL starting June 1, 2026, so it is recommended to migrate before that date.
  • Added the bigquery_reject_wildcard_metadata_source_freshness flag. When you set this flag to true, dbt raises a DbtRuntimeError if you run metadata-based source freshness checks with wildcard table identifiers (for example, events_*), preventing incorrect freshness results.
  • You can configure BigQuery job link logging with job_link_info_level_log. By default, dbt logs job links at the debug level. To log job links at the info level, set job_link_info_level_log: true in your BigQuery profile. This makes job links visible in dbt logs for easier access to the BigQuery console. For more information, see BigQuery setup.
  • You can set job_execution_timeout_seconds per model, snapshot, seed, or test, in addition to the profile-level configuration. The per-resource value takes precedence over the default value set in the profile level. For more information, refer to BigQuery setup.

Redshift​

  • The redshift_skip_autocommit_transaction_statements flag defaults to false, preserving legacy behavior of sending BEGIN/COMMIT/ROLLBACK statements even when autocommit is enabled. To skip unnecessary transaction statements and improve performance, set the flag to true.
  • Added support for the query_group session parameter, allowing dbt to tag queries for Redshift Workload Manager routing and query logging. When configured in a profile, dbt sets query_group when opening a connection and the value applies for the duration of that session. You can also configure query_group at the model level to temporarily override the default value for a specific model, and dbt reverts the value at the end of model materialization. For more information, see Redshift configurations.

Quick hits​

  • dbt seed now supports the --empty flag. Use it to create seed tables with the correct schema but without loading any data.

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading