fix: enforce 255-character identifier length limit for Databricks relations

CHANGELOG.md

@@ -1,3 +1,9 @@
+## dbt-databricks 1.11.8 (TBD)
+
+### Fixes
+
+- Validate relation identifier length at creation time and raise a clear error when it exceeds Databricks' 255-character limit ([#1309](https://github.com/databricks/dbt-databricks/issues/1309))
+
 ## dbt-databricks 1.11.7 (Apr 17, 2026)
 
 ### Features

dbt/adapters/databricks/relation.py

@@ -17,6 +17,7 @@
 from dbt.adapters.databricks.utils import remove_undefined
 
 KEY_TABLE_PROVIDER = "Provider"
+MAX_CHARACTERS_IN_IDENTIFIER = 255
 
 
 @dataclass
@@ -86,6 +87,19 @@ class DatabricksRelation(BaseRelation):
     databricks_table_type: Optional[DatabricksTableType] = None
     temporary: Optional[bool] = False
 
+    def __post_init__(self) -> None:
+        if self.identifier and self.type:
+            if len(self.identifier) > self.relation_max_name_length():
+                raise DbtRuntimeError(
+                    f"Databricks has a maximum identifier length of "
+                    f"{self.relation_max_name_length()} characters. "
+                    "Use a shorter name or configure a custom alias."
+                )
+
+    @classmethod
+    def relation_max_name_length(cls) -> int:
+        return MAX_CHARACTERS_IN_IDENTIFIER
+
     @classmethod
     def __pre_deserialize__(cls, data: dict[Any, Any]) -> dict[Any, Any]:
         data = super().__pre_deserialize__(data)

tests/unit/test_relation.py

@@ -1,5 +1,6 @@
 import pytest
 from dbt_common.contracts.constraints import ConstraintType
+from dbt_common.exceptions import DbtRuntimeError
 
 from dbt.adapters.databricks import relation
 from dbt.adapters.databricks.constraints import (
@@ -8,6 +9,7 @@
     PrimaryKeyConstraint,
 )
 from dbt.adapters.databricks.relation import (
+    MAX_CHARACTERS_IN_IDENTIFIER,
     DatabricksQuotePolicy,
     DatabricksRelation,
     DatabricksRelationType,
@@ -370,6 +372,27 @@ def test_render_constraints_for_create__with_constraints(
         assert relation.render_constraints_for_create() == "a > 1, PRIMARY KEY (a)"
 
 
+class TestIdentifierLengthValidation:
+    def test_valid_identifier_length(self):
+        identifier = "a" * MAX_CHARACTERS_IN_IDENTIFIER
+        rel = DatabricksRelation.create(identifier=identifier, type="table")
+        assert rel.identifier == identifier
+
+    def test_identifier_too_long_raises(self):
+        identifier = "a" * (MAX_CHARACTERS_IN_IDENTIFIER + 1)
+        with pytest.raises(DbtRuntimeError, match="maximum identifier length of 255 characters"):
+            DatabricksRelation.create(identifier=identifier, type="table")
+
+    def test_long_identifier_without_type_is_allowed(self):
+        identifier = "a" * (MAX_CHARACTERS_IN_IDENTIFIER + 1)
+        rel = DatabricksRelation.create(identifier=identifier)
+        assert rel.identifier == identifier
+
+    def test_none_identifier_is_allowed(self):
+        rel = DatabricksRelation.create(identifier=None, type="table")
+        assert rel.identifier is None
+
+
 class TestDatabricksRenderLimited:
     def test_render_limited_with_empty_no_alias(self):
         relation = DatabricksRelation.create(