Users should always call adapter.drop_relation instead of calling {{ drop_relation() }} directly

[jtcohen6]

Adapter maintainers and users should always call either:

• adapter.drop_relation
• drop_relation_if_exists (syntactic sugar that checks cache first, and then calls adapter.drop_relation)

Why? Calling {{ drop_relation() }} directly does not update the cache!! That happens within the adapter drop_relation method here:

dbt-adapters/dbt/adapters/sql/impl.py

Lines 140 to 145 in a2292c8

	def drop_relation(self, relation):
	if relation.type is None:
	raise RelationTypeNullError(relation)
	self.cache_dropped(relation)
	self.execute_macro(DROP_RELATION_MACRO_NAME, kwargs={"relation": relation})

Even though this method ultimately shells out to a macro called {{ drop_relation() }}:

dbt-adapters/dbt/include/global_project/macros/relations/drop.sql

Lines 26 to 34 in a2292c8

	{% macro drop_relation(relation) -%}
	{{ return(adapter.dispatch('drop_relation', 'dbt')(relation)) }}
	{% endmacro %}
	{% macro default__drop_relation(relation) -%}
	{% call statement('drop_relation', auto_begin=False) -%}
	{{ get_drop_sql(relation) }}
	{%- endcall %}
	{% endmacro %}

Proposals

• Document this for adapter maintainers and users (https://docs.getdbt.com/reference/dbt-jinja-functions/adapter#drop_relation)
• Deprecate/remove/rename {{ drop_relation() }}, either by calling dispatch directly in the adapter method or renaming this macro so that it is more clearly returning adapter.dispatch(DROP_RELATION_MACRO_NAME) and not a macro that should be called directly