dbt Core 1.2 and utils 0.9.0 prep

[joellabes]

This is a:

• documentation update
• bug fix with no breaking changes
• new functionality
• a breaking change

All pull requests from community contributors should target the main branch (default).

Description & motivation

The cross-db macros have been moved to dbt Core in v1.2. They already were dispatched to the dbt project, but now there are also deprecation warnings which will show during compilation. I've also bumped the min dbt version to 1.2-rc1.

I think that with these changes, we could release utils 0.9.0-rc1 immediately, and release 0.9.0 final when 1.2 final ships.

Checklist

• I have verified that these changes work locally on the following warehouses (Note: it's okay if you do not have access to all warehouses, this helps us understand what has been covered)
  • BigQuery
  • Postgres
  • Redshift
  • Snowflake
• I followed guidelines to ensure that my changes will work on "non-core" adapters by:
  • dispatching any new macro(s) so non-core adapters can also use them (e.g. the star() source)
  • using the limit_zero() macro in place of the literal string: limit 0
  • using dbt_utils.type_* macros instead of explicit datatypes (e.g. dbt_utils.type_timestamp() instead of TIMESTAMP
• I have updated the README.md (if applicable)
• I have added tests & descriptions to my models (and macros if applicable)
• I have added an entry to CHANGELOG.md

[dbeatty10]

Super exciting to see all this prepped for the final planned release prior to dbt_utils 1.0! 🚀

The implementation turned out really clean with the reusable xdb_deprecation_warning macro 🤩

One blocking item:

• @jtcohen6 and I made a decision regarding the dbt. namespace prefix, but I'm not sure if it was a local decision only affecting these docs or if it was a more global decision in relation to style. I'd like to get that clarified so the deprecation warning reflects the recommended style one way or the other. Is there anyone responsible for dbt code style?

[dbeatty10]

@jtcohen6 and I decided here to omit the dbt namespace for the public-facing documentation for cross-database macros.

I feel the public-facing documentation and the deprecation warning should be in tight alignment; it's confusing for end users when they differ.

There are two different permissible options here (with dbt. prefix or without). I wonder if this style guide or somewhere else would be good to document our explicit recommendation for which option to use?

Suggested change

	{% macro xdb_deprecation_warning(macro, package, model) %}
	{%- set error_message = "Warning: the `" ~ macro ~"` macro is no longer available in dbt_utils and backwards compatibility will be removed in a future version. Use `dbt." ~ macro ~ "` instead. The " ~ package ~ "." ~ model ~ " model triggered this warning." -%}
	{%- do exceptions.warn(error_message) -%}
	{% endmacro %}
	{% macro xdb_deprecation_warning(macro, package, model) %}
	{%- set error_message = "Warning: the `" ~ macro ~"` macro is no longer available in dbt_utils and backwards compatibility will be removed in a future version. Drop the `dbt_utils.` prefix and use just `" ~ macro ~ "` instead. The " ~ package ~ "." ~ model ~ " model triggered this warning." -%}
	{%- do exceptions.warn(error_message) -%}
	{% endmacro %}

[joellabes]

I 💯 agree with your desire for consistency of advice, especially for the exact same functions.

Ideally that should be true for all macros across the board, which would mean that we should have no dbt. to be in alignment with other out of the box macros (e.g it would be weird for someone to start going around saying {{ dbt.ref('my_model') }}.

BUT.

My gut feeling on why these ones are different is that they get a bit uncanny-valley-y. If I am new to dbt, then coming across {{ dateadd() }}, {{ except() }} etc could feel quite confusing - do I need to put all SQL keywords into Jinja braces? (In fairness, people shouldn't come across this in their early days, because it should all be deep in the bowels of packages' code.)

If we do {{ dbt.dateadd() }}, then it's clear that it's behaviour provided by dbt, even though it looks a bunch like standard SQL.

This sort of matches up with something else I've been thinking of, which is the shorthand node selection syntax being the same for a package or a model or a directory (dbt run -s something). I think we're doing a disservice letting the default advice be "type whatever you want! We'll work it out!" versus the more explicit package:something, path:something. But that's a different issue for a different day.

If you or jerco feel very strongly in the opposite direction, I'm willing to be talked around. I just like to know where my magic is coming from 🐰🎩

[dbeatty10]

Jerco and I both considered the two options and decided on the version that is shorter to read and write and aligns with {{ ref() }}, {{ source() }}, etc. i.e., without dbt. prefix.

Since we both had the same preference, we didn't discuss it in detail.

[dbeatty10]

I'm guessing this will drop the -rc1 suffix and flip to just >=1.2.0 prior to the final release of dbt_utils 0.9.0?

[joellabes]

Indeed!

• dbt-utils 0.9.0-rc1 supports dbt-core 1.2.0-rc1.
• dbt-utils 0.9.0 will support dbt-core 1.2.0