Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updating upgrade guide #5001

Merged
merged 18 commits into from
Feb 28, 2024
Merged
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
4596f87
add unit testing callout to updgrade guide
graciegoheen Feb 27, 2024
10a2e0c
add data_tests rename callout to upgrade guide
graciegoheen Feb 27, 2024
f463af2
Updating upgrade guide
matthewshaver Feb 27, 2024
2df4703
Merge branch 'mirgration-1-8' into add_unit_testing_to_upgrade_guide
matthewshaver Feb 27, 2024
54373fc
add unit testing callout to upgrade guide (#4997)
matthewshaver Feb 27, 2024
cb07e6b
Update 01-upgrading-to-v1.8.md
matthewshaver Feb 27, 2024
b80b828
Update 01-upgrading-to-v1.8.md
matthewshaver Feb 28, 2024
ec9ea2b
Update website/docs/docs/dbt-versions/core-upgrade/01-upgrading-to-v1…
matthewshaver Feb 28, 2024
fa393aa
Merge branch 'current' into mirgration-1-8
graciegoheen Feb 28, 2024
1411cc2
Update website/docs/docs/dbt-versions/core-upgrade/01-upgrading-to-v1…
matthewshaver Feb 28, 2024
7a294cc
Update website/docs/docs/dbt-versions/core-upgrade/01-upgrading-to-v1…
matthewshaver Feb 28, 2024
eb125e4
Update website/docs/docs/dbt-versions/core-upgrade/01-upgrading-to-v1…
matthewshaver Feb 28, 2024
5f2176a
Update website/docs/docs/dbt-versions/core-upgrade/01-upgrading-to-v1…
matthewshaver Feb 28, 2024
008ee5e
Update website/docs/docs/dbt-versions/core-upgrade/01-upgrading-to-v1…
matthewshaver Feb 28, 2024
e500315
Apply suggestions from code review
matthewshaver Feb 28, 2024
e896621
Apply suggestions from code review
matthewshaver Feb 28, 2024
8165eab
Update website/docs/docs/dbt-versions/core-upgrade/01-upgrading-to-v1…
mirnawong1 Feb 28, 2024
47e34b8
Update 01-upgrading-to-v1.8.md
mirnawong1 Feb 28, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -12,23 +12,53 @@ displayed_sidebar: "docs"
- [Cloud upgrade guide](/docs/dbt-versions/upgrade-dbt-version-in-cloud)
matthewshaver marked this conversation as resolved.
Show resolved Hide resolved
- Release schedule (coming soon)

:::tip Keep on latest version, always

Starting this year, let dbt Labs handle version upgrades for you. With dbt Cloud, you can get early access to new functionality before it lands in the final release of dbt Core v1.8 and without the need of managing your own version upgrades. For more details, refer to [Upgrade Core version in Cloud](/docs/dbt-versions/upgrade-dbt-version-in-cloud).
## What to know before upgrading

The **Keep on latest version** setting is currently available in beta for select dbt Cloud customers, rolling out to wider availability through February and March.
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](https://github.com/dbt-labs/dbt-core/issues/new).

For users of dbt Core, the v1.8.0-b1 release of `dbt-core` & dbt Labs-maintained adapters is planned for February 28.
dbt Labs plans to release dbt Core v1.8.0-b1 and dbt Labs-maintained adapters on February 28th, 2024.

:::
## Keep on the latest version in dbt Cloud

## What to know before upgrading
With dbt Cloud, you can get early access to many new features and functionality before it's in the Generally Available (GA) release of dbt Core v1.8 without the need to manage version upgrades. For more details, refer to [Upgrade Core version in Cloud](/docs/dbt-versions/upgrade-dbt-version-in-cloud).

dbt Labs is committed to providing backward compatibility for all versions 1.x, with the exception of any changes explicitly mentioned below. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new).
The **Keep on latest version** setting is currently available in closed beta for select dbt Cloud customers and will have wider availability in March of 2024.

## New and changed features and functionality

Features and functionality new in dbt v1.8
Features and functionality new in dbt v1.8.

### New dbt Core adapter installation procedure
matthewshaver marked this conversation as resolved.
Show resolved Hide resolved

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](https://github.com/dbt-labs/dbt-adapters/discussions/87). As a result, you must install _both_ dbt-core and the desired adapter. A new `pip` installation needs to look like this:

```shell
pip install dbt-core dbt-ADAPTER_NAME
```

matthewshaver marked this conversation as resolved.
Show resolved Hide resolved
For example, you would use the following command if you use Snowflake:
```shell
pip install dbt-core dbt-snowflake
```

### Unit Tests

Historically, dbt's test coverage was confined to [“data” tests](/docs/build/data-tests), assessing the quality of input data or resulting datasets' structure.

In v1.8, we're introducing native support for [unit testing](/docs/build/unit-tests). 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`](/reference/node-selection/methods#the-test_type-method) method to run only unit or data tests:

```shell

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.
matthewshaver marked this conversation as resolved.
Show resolved Hide resolved

### The `--empty` flag

Expand All @@ -37,4 +67,6 @@ The [`run`](/reference/commands/run#the-`--empty`-flag) and [`build`](/reference

## Quick hits

Coming soon!
- [Global config flags](/reference/global-configs/about-global-configs) are deprecated from the [`profiles.yml`](/docs/core/connect-data-platform/profiles.yml) file and should be moved to the [`dbt_project.yml`](/reference/dbt_project.yml).
- A new subcategory of flags has been created for [legacy behaviors](/reference/global-configs/legacy-behaviors).
matthewshaver marked this conversation as resolved.
Show resolved Hide resolved
- The [`--indirect_selection`](/reference/global-configs/indirect-selection) flag used with `dbt test` or `dbt build` configures which tests to run for the nodes you specify.
Loading