ai: apply changes for #1006 (2 review threads)

Addresses:
  - #4418398193 at CHANGELOG.md:4
  - #4418398199 at src/databricks/sql/parameters/native.py:673

Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>

Author: peco-engineer-bot[bot]

CHANGELOG.md

@@ -1,7 +1,7 @@
 # Release History
 
 # Unreleased
-- **Behaviour change:** `DecimalParameter` now binds `DECIMAL(precision, scale)`, matching SQL: `precision` is the total number of digits and `scale` the number of fractional digits (earlier docs described them the other way round). Calls written for the old convention (`scale > precision`, e.g. `scale=10, precision=2`) still bind `DECIMAL(10,2)` but emit a `DeprecationWarning`; swap your arguments, as this will raise `ValueError` in a future release. A declared `scale` equal to or less than `precision` is now interpreted with the SQL meaning, and a declared `scale` smaller than the value's own scale is widened so fractional digits are not lost (up to the 38-digit DECIMAL maximum; a value needing more digits than that still has its excess fractional digits rounded).
+- **Behaviour change:** `DecimalParameter` now binds `DECIMAL(precision, scale)`, matching SQL: `precision` is the total number of digits and `scale` the number of fractional digits (earlier docs described them the other way round). Calls written for the old convention (`scale > precision`, e.g. `scale=10, precision=2`) still bind `DECIMAL(10,2)` but emit a `FutureWarning`; swap your arguments, as this will raise `ValueError` in a future release. A declared `scale` equal to or less than `precision` is now interpreted with the SQL meaning, and a declared `scale` smaller than the value's own scale is widened so fractional digits are not lost (up to the 38-digit DECIMAL maximum; a value needing more digits than that still has its excess fractional digits rounded).
 - Preserve the originating session when re-fetching or concurrently polling async statements on the kernel backend.
 
 # 4.8.0 (2026-10-24)

src/databricks/sql/parameters/native.py

@@ -2,12 +2,15 @@
 
 import datetime
 import decimal
+import logging
 import warnings
 from enum import Enum, auto
 from typing import Optional, Sequence, Any, TYPE_CHECKING
 
 from databricks.sql.exc import NotSupportedError
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     # Type-annotation-only imports. ``from __future__ import annotations`` keeps
     # these out of the runtime import graph; the ``TSparkParameter*`` objects
@@ -672,6 +675,15 @@ def valid_scale_and_precision(self):
     def _cast_expr(self):
         if self.scale is not None and self.precision is not None:
             precision, scale = self._effective_precision_and_scale(self.precision, self.scale)
+            if (precision, scale) != (self.precision, self.scale):
+                logger.debug(
+                    "DecimalParameter declared DECIMAL(%d,%d) is bound as DECIMAL(%d,%d) "
+                    "to fit the value's digits (precision capped at 38)",
+                    self.precision,
+                    self.scale,
+                    precision,
+                    scale,
+                )
             # SQL DECIMAL type syntax is DECIMAL(precision, scale)
             return self.CAST_EXPR.format(precision, scale)
         else:

tests/unit/test_parameters.py

@@ -140,8 +140,23 @@ def test_decimal_explicit_precision_scale_cast_string(value, scale, precision, e
     assert p._cast_expr() == expected
 
 
+def test_decimal_widened_type_is_logged(caplog):
+    """A bound type that differs from the declared one is reported at debug level."""
+    p = DecimalParameter(Decimal("123.4567"), scale=2, precision=10)
+    with caplog.at_level("DEBUG", logger="databricks.sql.parameters.native"):
+        assert p._cast_expr() == "DECIMAL(12,4)"
+    assert "DECIMAL(10,2) is bound as DECIMAL(12,4)" in caplog.text
+
+
+def test_decimal_unchanged_type_is_not_logged(caplog):
+    p = DecimalParameter(Decimal("123.45"), scale=2, precision=10)
+    with caplog.at_level("DEBUG", logger="databricks.sql.parameters.native"):
+        assert p._cast_expr() == "DECIMAL(10,2)"
+    assert "is bound as" not in caplog.text
+
+
 def test_decimal_scale_greater_than_precision_legacy_swapped():
-    """Callers using the old (swapped) convention keep working, with a deprecation warning."""
+    """Callers using the old (swapped) convention keep working, with a FutureWarning."""
     with pytest.warns(FutureWarning, match="legacy"):
         p = DecimalParameter(Decimal("123.45"), scale=10, precision=2)
     assert p.precision == 10