Skip to main content

Upgrading to v1.0

Upgrade Guides Are Moving

The location of the dbt Core upgrade guides has changed, and they will soon be removed from Guides. The new location is in the Docs tab under Available dbt versions. You have been redirected to the new URL, so please update any saved links and bookmarks.

Resources​

What to know before upgrading​

dbt Core major version 1.0 includes a number of breaking changes! Wherever possible, we have offered backwards compatibility for old behavior, and (where necessary) made migration simple.

Renamed fields in dbt_project.yml​

These affect everyone:

  • model-paths have replaced source-paths in dbt-project.yml.
  • seed-paths have replaced data-paths in dbt-project.yml with a default value of seeds.
  • The packages-install-path was updated from modules-path. Additionally the default value is now dbt_packages instead of dbt_modules. You may need to update this value in clean-targets.
  • Default for quote_columns is now True for all adapters other than Snowflake.

These probably don't:

  • The default value of test-paths has been updated to be the plural tests.
  • The default value of analysis-paths has been updated to be the plural analyses.

Tests​

The two test types are now "singular" and "generic" (instead of "data" and "schema", respectively). The test_type: selection method accepts test_type:singular and test_type:generic. (It will also accept test_type:schema and test_type:data for backwards compatibility.) Not backwards compatible: The --data and --schema flags to dbt test are no longer supported, and tests no longer have the tags 'data' and 'schema' automatically applied. Updated docs: tests, test selection, selection methods.

The greedy flag/property has been renamed to indirect_selection, which is now eager by default. Note: This reverts test selection to its pre-v0.20 behavior by default. dbt test -s my_model will select multi-parent tests, such as relationships, that depend on unselected resources. To achieve the behavior change in v0.20 + v0.21, set --indirect-selection=cautious on the CLI or indirect_selection: cautious in YAML selectors. Updated docs: test selection examples, yaml selectors.

Global macros​

Global project macros have been reorganized, and some old unused macros have been removed: column_list, column_list_for_create_table, incremental_upsert. This is unlikely to affect your project.

Installation​

  • Installation docs reflects adapter-specific installations
  • python -m pip install dbt is no longer supported, and will raise an explicit error. Install the specific adapter plugin you need as python -m pip install dbt-<adapter>.
  • brew install dbt is no longer supported. Install the specific adapter plugin you need (among Postgres, Redshift, Snowflake, or BigQuery) as brew install dbt-<adapter>.
  • Removed official support for python 3.6, which is reaching end of life on December 23, 2021

For users of adapter plugins​

  • BigQuery: Support for ingestion-time-partitioned tables has been officially deprecated in favor of modern approaches. Use partition_by and incremental modeling strategies instead. For more information, refer to Incremental models.

For maintainers of plugins + other integrations​

We've introduced a new structured event interface, and we've transitioned all dbt logging to use this new system. This includes a breaking change for adapter plugins, requiring a very simple migration. For more details, see the events module README. If you maintain a different kind of plugin that needs legacy logging, for the time being, you can re-enable it with an env var (DBT_ENABLE_LEGACY_LOGGER=True); be advised that we will remove this capability in a future version of dbt Core.

The dbt RPC Server has been split out from dbt-core and is now packaged separately. Its functionality will be fully deprecated by the end of 2022, in favor of a new dbt Server. Instead of dbt rpc, use dbt-rpc serve.

Artifacts: New schemas (manifest v4, run results v4, sources v3). Notable changes: add metrics nodes; schema test + data test nodes are renamed to generic test + singular test nodes; freshness threshold default values look slightly different.

Deprecations from long ago​

Several under-the-hood changes from past minor versions, tagged with deprecation warnings, have now been fully deprecated.

  • The packages argument of dispatch has been deprecated and will raise an exception when used.
  • The "adapter_macro" macro has been deprecated. Instead, use the dispatch method to find a macro and call the result.
  • The release arg has been removed from the execute_macro method.

New features and changed documentation​

  • Add metrics, a new node type
  • Generic tests can be defined in tests/generic (new), in addition to macros/ (as before)
  • Parsing: partial parsing and static parsing have been turned on by default.
  • Global configs have been standardized. Related updates to global CLI flags and profiles.yml.
  • The init command has a whole new look and feel. It's no longer just for first-time users.
  • Add result:<status> subselectors for smarter reruns when dbt models have errors and tests fail. See examples: Pro-tips for Workflows
  • Secret-prefixed env vars are now allowed only in profiles.yml + packages.yml
0
Edit this page