Skip to main content

Upgrading to v1.8 (beta)

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.

dbt Labs plans to release dbt Core v1.8.0-b1 and dbt Labs-maintained adapters on February 28th, 2024.

Keep on latest version public preview​

With dbt Cloud, you can get early access to many new features and functionality before they're in the Generally Available (GA) release of dbt Core v1.8 without the need to manage version upgrades. Refer to the Keep on latest version setting for more details.

Availability

Microsoft Fabric support will be coming in late March. All other connections are supported.

New and changed features and functionality​

Features and functionality new in dbt v1.8.

New dbt Core adapter installation procedure​

Before v1.8, when you installed an adapter, you would automatically get dbt-core installed along with the adapter package (if you didn’t already have an existing, compatible version of dbt-core).

Beginning in v1.8, the dbt adapters and dbt Core have been decoupled. As a result, you must install both dbt-core and the desired adapter. A new pip installation needs to look like this:

pip install dbt-core dbt-ADAPTER_NAME

For example, you would use the following command if you use Snowflake:

pip install dbt-core dbt-snowflake

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.

Spaces in dbt model names​

We will begin deprecating support for spaces in dbt model names in v1.8 (raising a warning) before removing support entirely in v1.9 (raising an error). Reasons for removing spaces in model names include:

  • Spaces in a model name make it impossible to --select the model name because the argument gets split into pieces over spaces very early in the pipeline.
  • Most warehouses do not accept a table, or other object, with a space in its name.

To upgrade, replace any spaces in the model file name with an underscore and update any associated YAML that contains the model name to match. You can keep spaces in the database table name by configuring a custom alias.

Quick hits​

  • Global config flags are deprecated from the profiles.yml file and should be moved to the dbt_project.yml.
  • A new subcategory of flags has been created for legacy behaviors.
  • The --indirect_selection flag used with dbt test or dbt build configures which tests to run for the nodes you specify.
  • 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.
0
Edit this page