Skip to main content

Upgrading to v1.8

Resources​

What to know before upgrading​

dbt Labs is committed to providing backward compatibility for all versions 1.x, except for any changes explicitly mentioned on this page. If you encounter an error upon upgrading, please let us know by opening an issue.

Release tracks​

Starting in 2024, dbt provides the functionality from new versions of dbt Core via release tracks with automatic upgrades. Select a release track in your development, staging, and production environments to access everything in dbt Core v1.8+ and more. To upgrade an environment in the dbt Admin API or Terraform, set dbt_version to the string latest.

New and changed features and functionality​

Features and functionality new in dbt v1.8.

Snowflake column size change

Snowflake plans to increase the default column size for string and binary data types in September 2026. dbt-snowflake versions below v1.10.6 may fail to build certain incremental models when this change is deployed.

 Assess impact and required actions

If you're using a dbt-snowflake version below v1.10.6 or have not yet migrated to a release track in the dbt platform, your adapter version is incompatible with this change and may fail to build incremental models that meet both of the following conditions:

  • Contain string columns with collation defined
  • Use the on_schema_change='sync_all_columns' config

To check whether this change affects your project, run the following list command:

dbt ls -s config.materialized:incremental,config.on_schema_change:sync_all_columns --resource-type model

  • If the command returns No nodes selected!, no action is required.

  • If the command returns one or more models (for example, Found 1000 models, 644 macros), you may be impacted if those models have string columns that don't specify a width. In that case, upgrade to a version that includes the fix:

    • dbt Core: dbt-snowflake v1.10.6 or later. For upgrade instructions, refer to Upgrade adapters in the dbt Core v1 installation instructions.
    • dbt platform: Any release track (Latest, Compatible, Extended, or Fallback).
    • dbt Fusion engine: v2.0.0-preview.147 or higher.

    This ensures your incremental models can safely handle schema changes while maintaining required collation settings.

Unit Tests​

Historically, dbt's test coverage was confined to “data” tests, assessing the quality of input data or resulting datasets' structure.

In v1.8, we're introducing native support for unit testing. Unit tests validate your SQL modeling logic on a small set of static inputs before you materialize your full model in production. They support a test-driven development approach, improving both the efficiency of developers and the reliability of code.

Starting from v1.8, when you execute the dbt test command, it will run both unit and data tests. Use the test_type method to run only unit or data tests:


dbt test --select "test_type:unit"           # run all unit tests
dbt test --select "test_type:data"           # run all data tests

Unit tests are defined in YML files in your models/ directory and are currently only supported on SQL models. To distinguish between the two, the tests: config has been renamed to data_tests:. Both are currently supported for backward compatibility.

New data_tests: syntax​

The tests: syntax is changing to reflect the addition of unit tests. Start migrating your data test YML to use data_tests: after you upgrade to v1.8 to prevent issues in the future.


models:
  - name: orders
    columns:
      - name: order_id
        data_tests:
          - unique
          - not_null


The --empty flag​

The run and build commands now support the --empty flag for building schema-only dry runs. The --empty flag limits the refs and sources to zero rows. dbt will still execute the model SQL against the target data warehouse but will avoid expensive reads of input data. This validates dependencies and ensures your models will build properly.

dbt-core and adapters are decoupled​

Before v1.8, dbt adapters directly depended on components of dbt-core, and dbt-core depended on the adapter for execution. This bidirectional dependency made it difficult to develop adapters independently. Starting in dbt Core v1.8, dbt-core and adapters are decoupled, making it easier to maintain and evolve them independent of each other.

For backward compatibility, adapter packages continue to depend on dbt-core at install time. Running a dbt project still requires both dbt-core and an adapter, and since v1.0, many users have installed both together using pip install dbt-<adapter>.

This behavior remains unchanged. For example, pip install dbt-snowflake installs the latest versions of both dbt-core and dbt-snowflake.

Deprecated functionality​

The ability for installed packages to override built-in materializations without explicit opt-in from the user is being deprecated.

  • Overriding a built-in materialization from an installed package raises a deprecation warning.

  • Using a custom materialization from an installed package does not raise a deprecation warning.

  • Using a built-in materialization package override from the root project via a wrapping materialization is still supported. For example:

    {% materialization view, default %}
    {{ return(my_cool_package.materialization_view_default()) }}
    {% endmaterialization %}

Managing changes to legacy behaviors​

dbt Core v1.8 has introduced 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:

Quick hits​

  • Custom defaults of global config flags should be set in the flags dictionary in dbt_project.yml, instead of in profiles.yml. Support for profiles.yml has been deprecated.
  • New CLI flag --resource-type/--exclude-resource-type for including/excluding resources from dbt build, run, and clone.
  • To improve performance, dbt now issues a single (batch) query when calculating source freshness through metadata, instead of executing a query per source.
  • Syntax for DBT_ENV_SECRET_ has changed to DBT_ENV_SECRET and no longer requires the closing underscore.
  • The --select flag now reliably limits catalog.json to the selected nodes in all projects, regardless of project size. In earlier versions, node selectors were ignored for projects with 100 or more nodes, and sources were omitted from catalog.json entirely when more than 100 nodes were selected.

Was this page helpful?

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

0
Loading