Model contracts for incremental models: on_schema_change can be 'fail' in addition to 'append_new_columns'

[MichelleArk]

Contributions

• I have read the contribution docs, and understand what's expected of me.

Link to the page on docs.getdbt.com requiring updates

https://docs.getdbt.com/reference/resource-configs/contract#incremental-models-and-on_schema_change

What part(s) of the page would you like to see updated?

Why require that incremental models also set on_schema_change, and why to append_new_columns?

This part should be updated to reflect that on_schema_change can be set to append_new_columns or fail.

Reasoning: (from dbt-labs/dbt-core#7975)

(from @graciegoheen)

There's not a clear reason to prevent contracted incremental models from having on_schema_change = fail - which triggers an error message when the source and target schemas diverge. This config forces you to execute a full-refresh if you add a new column or remove and old column from your incremental model. Removing an old column would also break your "contract" - so there shouldn't be an issue with doubling up on errors here.

(fom @jtcohen6)

Why only support these two, and not all four? This is an opinionated choice, but really:

• sync_all_columns: is exactly the same as append_new_columns, but with the ability to remove columns that get deleted, a thing you're specifically not supposed to do with contracted models (unless you're bumping the version)
• ignore means that your contract check will succeed, assuming you've coordinated yaml + SQL updates (tmp table == yaml) — but the resulting columns in the target table will not actually reflect the columns described in your contract! You need to full-refresh to make the stated contract and resulting table line up. At the point where you must full-refresh, that's really what on_schema_change: fail is for.

Additional information

No response