Warn when documented columns are missing on the V2 materialization path

The persist_docs missing-column warning only covered the V1 path
(get_persist_doc_columns). The V2 (relation-config) path diffs column
comments through ColumnCommentsConfig.get_diff, where a column documented
in schema.yml but absent from the relation was still emitted into the
diff (targeting a nonexistent column on the ALTER) with no feedback.

Warn about those columns and skip them, matching the V1 behavior and the
same warning message. Addresses review feedback on databricks#1563.

Author: r-jais

dbt/adapters/databricks/relation_configs/column_comments.py

@@ -1,7 +1,9 @@
 from typing import ClassVar, Optional
 
 from dbt.adapters.contracts.relation import RelationConfig
+from dbt.adapters.events.types import AdapterEventWarning
 from dbt.adapters.relation_configs.config_base import RelationResults
+from dbt_common.events.functions import warn_or_error
 
 from dbt.adapters.databricks.logging import logger
 from dbt.adapters.databricks.relation_configs.base import (
@@ -23,8 +25,28 @@ def get_diff(self, other: "ColumnCommentsConfig") -> Optional["ColumnCommentsCon
             # Create a case-insensitive lookup for other's column comments
             other_comments_lower = {k.lower(): v for k, v in other.comments.items()}
 
+            # Warn about columns that are documented in the model's schema but are not present in
+            # the relation. These are skipped below (rather than erroring on the alter), so surface
+            # them to the user to catch typos and stale documentation.
+            missing = [
+                column_name
+                for column_name in self.comments
+                if column_name.lower() not in other_comments_lower
+            ]
+            if missing:
+                warn_or_error(
+                    AdapterEventWarning(
+                        base_msg=(
+                            "The following columns are specified in the schema but are not present "
+                            "in the database and will be skipped: " + ", ".join(missing)
+                        )
+                    )
+                )
+
             for column_name, comment in self.comments.items():
                 # Use case-insensitive comparison for column names
+                if column_name.lower() not in other_comments_lower:
+                    continue
                 other_comment = other_comments_lower.get(column_name.lower())
                 if comment != other_comment:
                     column_name = f"`{column_name}`"

tests/unit/relation_configs/test_column_comments_config.py

@@ -1,4 +1,4 @@
-from unittest.mock import Mock
+from unittest.mock import Mock, patch
 
 from agate import Table
 
@@ -102,3 +102,36 @@ def test_get_diff__case_mismatch_with_actual_changes(self):
         assert diff == ColumnCommentsConfig(
             comments={"`account_id`": "New Account ID"}, persist=True
         )
+
+    @patch("dbt.adapters.databricks.relation_configs.column_comments.warn_or_error")
+    def test_get_diff__warns_and_skips_missing_column(self, mock_warn):
+        """Documented columns absent from the relation are warned about and skipped."""
+        # col2 is documented but not present in the relation
+        config = ColumnCommentsConfig(
+            comments={"col1": "new comment", "col2": "comment for missing column"}, persist=True
+        )
+        other = ColumnCommentsConfig(comments={"col1": "old comment"})
+        diff = config.get_diff(other)
+        # Only the existing column is included in the diff; the missing one is skipped.
+        assert diff == ColumnCommentsConfig(comments={"`col1`": "new comment"}, persist=True)
+        # A warning is emitted naming the missing column.
+        mock_warn.assert_called_once()
+        warned_event = mock_warn.call_args.args[0]
+        assert "col2" in warned_event.base_msg
+        assert "col1" not in warned_event.base_msg
+
+    @patch("dbt.adapters.databricks.relation_configs.column_comments.warn_or_error")
+    def test_get_diff__no_warning_when_all_present(self, mock_warn):
+        """No warning is emitted when every documented column exists (case-insensitively)."""
+        config = ColumnCommentsConfig(comments={"account_id": "Account ID"}, persist=True)
+        other = ColumnCommentsConfig(comments={"Account_ID": ""})
+        config.get_diff(other)
+        mock_warn.assert_not_called()
+
+    @patch("dbt.adapters.databricks.relation_configs.column_comments.warn_or_error")
+    def test_get_diff__no_warning_when_not_persisting(self, mock_warn):
+        """Missing columns are not evaluated (or warned about) when persist is False."""
+        config = ColumnCommentsConfig(comments={"col1": "comment", "col2": "comment"})
+        other = ColumnCommentsConfig(comments={"col1": "comment"})
+        assert config.get_diff(other) is None
+        mock_warn.assert_not_called()