Loosen type on replaceable_relation and renameable_relation and provi…

…de guidance in docstrings (#8647)

* loosen type on replaceable_relation and renameable_relation and provide guidance in docstrings

.changes/unreleased/Features-20230913-182707.yaml

@@ -0,0 +1,8 @@
+kind: Features
+body: Loosen typing requirement on renameable/replaceable relations to Iterable to
+  allow adapters more flexibility in registering relation types, include docstrings
+  as suggestions
+time: 2023-09-13T18:27:07.974612-04:00
+custom:
+  Author: mikealfare
+  Issue: "8647"

core/dbt/adapters/base/relation.py

@@ -1,6 +1,6 @@
 from collections.abc import Hashable
 from dataclasses import dataclass, field
-from typing import Optional, TypeVar, Any, Type, Dict, Iterator, Tuple, Set, FrozenSet
+from typing import Optional, TypeVar, Any, Type, Dict, Iterator, Tuple, Set, Union, FrozenSet
 
 from dbt.contracts.graph.nodes import SourceDefinition, ManifestNode, ResultNode, ParsedNode
 from dbt.contracts.relation import (
@@ -23,6 +23,7 @@
 
 
 Self = TypeVar("Self", bound="BaseRelation")
+SerializableIterable = Union[Tuple, FrozenSet]
 
 
 @dataclass(frozen=True, eq=False, repr=False)
@@ -35,10 +36,18 @@ class BaseRelation(FakeAPIObject, Hashable):
     include_policy: Policy = field(default_factory=lambda: Policy())
     quote_policy: Policy = field(default_factory=lambda: Policy())
     dbt_created: bool = False
+
     # register relation types that can be renamed for the purpose of replacing relations using stages and backups
-    renameable_relations: FrozenSet[str] = frozenset()
-    # register relation types that are replaceable, i.e. they have "create or replace" capability
-    replaceable_relations: FrozenSet[str] = frozenset()
+    # adding a relation type here also requires defining the associated rename macro
+    # e.g. adding RelationType.View in dbt-postgres requires that you define:
+    # include/postgres/macros/relations/view/rename.sql::postgres__get_rename_view_sql()
+    renameable_relations: SerializableIterable = ()
+
+    # register relation types that are atomically replaceable, e.g. they have "create or replace" syntax
+    # adding a relation type here also requires defining the associated replace macro
+    # e.g. adding RelationType.View in dbt-postgres requires that you define:
+    # include/postgres/macros/relations/view/replace.sql::postgres__get_replace_view_sql()
+    replaceable_relations: SerializableIterable = ()
 
     def _is_exactish_match(self, field: ComponentName, value: str) -> bool:
         if self.dbt_created and self.quote_policy.get_part(field) is False: