fix: COMMENT ON syntax not supported prior to 16.1 (#1151)

### Description

For users on DBR before 16.1, COMMENT ON COLUMN is not supported. We
switched to COMMENT ON because it works with types other than table, but
here we need to bifurcate.

### Checklist

- [x] I have run this code in development and it appears to resolve the
stated issue
- [x] This PR includes tests, or tests are not required/relevant for
this PR
- [x] I have updated the `CHANGELOG.md` and added information about my
change to the "dbt-databricks next" section.

---------

Co-authored-by: Claude <[email protected]>

Author: benc-db

CHANGELOG.md

@@ -1,5 +1,8 @@
 ## dbt-databricks 1.10.10 (TBD)
 
+### Fixes
+- Gate column comment syntax on DBR version for better compatibility ([1151](https://github.com/databricks/dbt-databricks/pull/1151))
+
 ### Documentation
 - Update Databricks Job documentation to match current terminology ([1145](https://github.com/databricks/dbt-databricks/pull/1145))
 

dbt/include/databricks/macros/adapters/persist_docs.sql

@@ -13,7 +13,22 @@
 {% endmacro %}
 
 {% macro comment_on_column_sql(column_path, escaped_comment) %}
-COMMENT ON COLUMN {{ column_path }} IS '{{ escaped_comment }}'
+  {%- if adapter.compare_dbr_version(16, 1) >= 0 -%}
+    COMMENT ON COLUMN {{ column_path }} IS '{{ escaped_comment }}'
+  {%- else -%}
+    {{ alter_table_change_column_comment_sql(column_path, escaped_comment) }}
+  {%- endif -%}
+{% endmacro %}
+
+{% macro alter_table_change_column_comment_sql(column_path, escaped_comment) %}
+  {%- set parts = column_path.split('.') -%}
+  {%- if parts|length >= 4 -%}
+    {%- set table_path = parts[:-1] | join('.') -%}
+    {%- set column_name = parts[-1] -%}
+    ALTER TABLE {{ table_path }} ALTER COLUMN {{ column_name }} COMMENT '{{ escaped_comment }}'
+  {%- else -%}
+    {{ exceptions.raise_compiler_error("Invalid column path: " ~ column_path ~ ". Expected format: database.schema.table.column") }}
+  {%- endif -%}
 {% endmacro %}
 
 {% macro databricks__persist_docs(relation, model, for_relation, for_columns) -%}

tests/unit/macros/adapters/test_persist_docs_macros.py

@@ -25,10 +25,15 @@ def mock_model_with_columns(self):
 
         return model
 
-    def test_comment_on_column_sql(self, template_bundle):
+    def test_comment_on_column_sql_dbr_16_1_or_newer(self, template_bundle, context):
+        """Test COMMENT ON COLUMN syntax for DBR 16.1+"""
         column_path = "`test_db`.`test_schema`.`test_table`.id"
         escaped_comment = "This is a column comment"
 
+        # Mock adapter to return DBR 16.1+
+        context["adapter"] = Mock()
+        context["adapter"].compare_dbr_version = Mock(return_value=0)  # >= 16.1
+
         result = self.run_macro(
             template_bundle.template, "comment_on_column_sql", column_path, escaped_comment
         )
@@ -38,6 +43,64 @@ def test_comment_on_column_sql(self, template_bundle):
         """
         self.assert_sql_equal(result, expected_sql)
 
+    def test_comment_on_column_sql_dbr_older_than_16_1(self, template_bundle, context):
+        """Test ALTER TABLE syntax for DBR < 16.1"""
+        column_path = "`test_db`.`test_schema`.`test_table`.id"
+        escaped_comment = "This is a column comment"
+
+        # Mock adapter to return DBR < 16.1
+        context["adapter"] = Mock()
+        context["adapter"].compare_dbr_version = Mock(return_value=-1)  # < 16.1
+
+        result = self.run_macro(
+            template_bundle.template, "comment_on_column_sql", column_path, escaped_comment
+        )
+
+        expected_sql = """
+            ALTER TABLE `test_db`.`test_schema`.`test_table`
+            ALTER COLUMN id COMMENT 'This is a column comment'
+        """
+        self.assert_sql_equal(result, expected_sql)
+
+    def test_alter_table_change_column_comment_sql(self, template_bundle):
+        """Test the legacy ALTER TABLE CHANGE COLUMN syntax"""
+        column_path = "`test_db`.`test_schema`.`test_table`.id"
+        escaped_comment = "This is a column comment"
+
+        result = self.run_macro(
+            template_bundle.template,
+            "alter_table_change_column_comment_sql",
+            column_path,
+            escaped_comment,
+        )
+
+        expected_sql = """
+            ALTER TABLE `test_db`.`test_schema`.`test_table`
+            ALTER COLUMN id COMMENT 'This is a column comment'
+        """
+        self.assert_sql_equal(result, expected_sql)
+
+    def test_alter_table_change_column_comment_sql_invalid_path(self, template_bundle, context):
+        """Test error handling for invalid column path"""
+        column_path = "invalid_path"
+        escaped_comment = "This is a column comment"
+
+        # Mock exceptions module
+        context["exceptions"] = Mock()
+        context["exceptions"].raise_compiler_error = Mock(side_effect=Exception("Test error"))
+
+        with pytest.raises(Exception, match="Test error"):
+            self.run_macro(
+                template_bundle.template,
+                "alter_table_change_column_comment_sql",
+                column_path,
+                escaped_comment,
+            )
+
+        context["exceptions"].raise_compiler_error.assert_called_once_with(
+            "Invalid column path: invalid_path. Expected format: database.schema.table.column"
+        )
+
     def test_alter_relation_comment_sql(self, template_bundle, relation):
         result = self.run_macro(
             template_bundle.template,
@@ -82,7 +145,7 @@ def test_alter_relation_comment_sql_view(self, template_bundle):
         )
         self.assert_sql_equal(result, expected_sql)
 
-    def test_databricks__alter_column_comment_delta(
+    def test_databricks__alter_column_comment_delta_dbr_16_1_plus(
         self, template_bundle, context, relation, mock_model_with_columns
     ):
         context["config"] = Mock()
@@ -91,6 +154,9 @@ def test_databricks__alter_column_comment_delta(
         context["api"] = MagicMock()
         context["api"].Column.get_name = Mock(side_effect=lambda col: col["name"])
 
+        context["adapter"] = Mock()
+        context["adapter"].compare_dbr_version = Mock(return_value=0)  # >= 16.1
+
         context["run_query_as"] = Mock()
 
         self.run_macro_raw(
@@ -117,6 +183,45 @@ def test_databricks__alter_column_comment_delta(
         )
         self.assert_sql_equal(second_call, expected_second_sql)
 
+    def test_databricks__alter_column_comment_delta_dbr_older_than_16_1(
+        self, template_bundle, context, relation, mock_model_with_columns
+    ):
+        context["config"] = Mock()
+        context["config"].get = Mock(return_value="delta")
+
+        context["api"] = MagicMock()
+        context["api"].Column.get_name = Mock(side_effect=lambda col: col["name"])
+
+        context["adapter"] = Mock()
+        context["adapter"].compare_dbr_version = Mock(return_value=-1)  # < 16.1
+
+        context["run_query_as"] = Mock()
+
+        self.run_macro_raw(
+            template_bundle.template,
+            "databricks__alter_column_comment",
+            relation,
+            mock_model_with_columns.columns,
+        )
+
+        assert context["run_query_as"].call_count == 2
+
+        call_args_list = context["run_query_as"].call_args_list
+
+        first_call = call_args_list[0][0][0]
+        expected_first_sql = (
+            "ALTER TABLE `some_database`.`some_schema`.`some_table` "
+            "ALTER COLUMN id COMMENT 'Primary key'"
+        )
+        self.assert_sql_equal(first_call, expected_first_sql)
+
+        second_call = call_args_list[1][0][0]
+        expected_second_sql = (
+            "ALTER TABLE `some_database`.`some_schema`.`some_table` "
+            "ALTER COLUMN value COMMENT 'Contains \\'quoted\\' text'"
+        )
+        self.assert_sql_equal(second_call, expected_second_sql)
+
     def test_databricks__alter_column_comment_unsupported_format(
         self, template_bundle, context, relation, mock_model_with_columns
     ):