@@ -1,6 +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). Passing `scale > precision` now raises `ValueError`, and a declared `scale` smaller than the value's own scale is widened so fractional digits are not lost.
 - Preserve the originating session when re-fetching or concurrently polling async statements on the kernel backend.
 
 # 4.8.0 (2026-10-24)
 
@@ -107,9 +107,11 @@
 # will infer the Decimal to be a DECIMAL and will preserve its current precision and scale.
 ex4_p3 = Decimal("12.3456")
 
-# For this parameter value, we bind a decimal with custom scale and precision
-# that will result in the decimal being truncated.
-ex4_p4 = DecimalParameter(value=ex4_p3, scale=4, precision=2)
+# For this parameter value, we bind a decimal with custom precision and scale,
+# i.e. DECIMAL(precision, scale). The declared scale is a minimum: if the value has
+# more fractional digits, the bound type is widened so no digits are lost. Here
+# DECIMAL(10,2) is widened to DECIMAL(12,4) and 12.3456 round-trips unchanged.
+ex4_p4 = DecimalParameter(value=ex4_p3, precision=10, scale=2)
 
 EX4_QUERY = "SELECT ? `p1`, ? `p2`, ? `p3`, ? `p4`"
 EX4_PARAMS = [ex4_p1, ex4_p2, ex4_p3, ex4_p4]
 
@@ -600,6 +600,12 @@ def __init__(
         If set, `scale` and `precision` must both be set. If neither is set, the value
         will be casted to the smallest possible DECIMAL type that can contain it.
 
+        When set, `precision` and `scale` declare a *minimum* DECIMAL(precision, scale)
+        type: if the value needs more fractional or integer digits than declared, the
+        bound type is widened to fit it (capped at precision 38) so no digits are lost.
+        The value is never rounded or truncated to a narrower declared type; round the
+        `Decimal` yourself (e.g. with `Decimal.quantize`) before binding if you need that.
+
         :value:
             The value to bind for this parameter. This will be casted to a DECIMAL.
         :name:
@@ -618,7 +624,9 @@ def __init__(
             The number of digits to the right of the decimal point. If the value itself
             has more fractional digits, the value's scale is used so no digits are lost.
         :precision:
-            The maximum precision (total number of digits) of the number between 1 and 38.
+            The minimum precision (total number of digits) of the number, between 1 and 38.
+            If the value has more integer digits than `precision - scale` allows, or its
+            scale is widened, the precision grows to fit it (up to 38).
         """
         self.value: decimal.Decimal = value
         self.name = name
@@ -630,6 +638,18 @@ def __init__(
                 "DecimalParameter requires both or none of scale and precision to be set"
             )
 
+        if self.scale is not None and self.precision is not None and self.scale > self.precision:
+            # Earlier releases documented these arguments the other way round
+            # (scale = total digits, precision = fractional digits). Fail loudly
+            # instead of silently reinterpreting a call written that way.
+            raise ValueError(
+                "DecimalParameter scale ({}) must not exceed precision ({}). `precision` is "
+                "the total number of digits and `scale` is the number of digits after the "
+                "decimal point, as in SQL DECIMAL(precision, scale).".format(
+                    self.scale, self.precision
+                )
+            )
+
     def valid_scale_and_precision(self):
         if (self.scale is None and self.precision is None) or (
             isinstance(self.scale, int) and isinstance(self.precision, int)
 
@@ -112,6 +112,21 @@ def test_calculate_decimal_cast_string(value, expected):
     (
         (Decimal("123.45"), 2, 10, "DECIMAL(10,2)"),
         (Decimal("123"), 0, 10, "DECIMAL(10,0)"),
+        # Value scale exceeds declared scale: scale widens, declared int room (8) is kept
+        (Decimal("123.4567"), 2, 10, "DECIMAL(12,4)"),
+        # Value has more integer digits than declared precision - scale allows
+        (Decimal("123456789012.5"), 2, 10, "DECIMAL(14,2)"),
+        # Positive exponent: 1E+3 needs 4 integer digits, no fractional digits
+        (Decimal("1E+3"), 0, 2, "DECIMAL(4,0)"),
+        # Widened precision is capped at 38
+        (Decimal("0.123456789012345678901234567890123456"), 2, 10, "DECIMAL(38,36)"),
+        # Widened scale is capped at the (capped) precision
+        (Decimal("0.1234567890123456789012345678901234567890"), 2, 10, "DECIMAL(38,38)"),
+        # NaN / Infinity leave the declared type untouched
+        (Decimal("NaN"), 2, 10, "DECIMAL(10,2)"),
+        (Decimal("Infinity"), 2, 10, "DECIMAL(10,2)"),
+        # Non-Decimal values (no as_tuple) fall back to the declared type
+        (1.5, 2, 10, "DECIMAL(10,2)"),
     ),
 )
 def test_decimal_explicit_precision_scale_cast_string(value, scale, precision, expected):
@@ -120,6 +135,12 @@ def test_decimal_explicit_precision_scale_cast_string(value, scale, precision, e
     assert p._cast_expr() == expected
 
 
+def test_decimal_scale_greater_than_precision_rejected():
+    """Callers using the old (swapped) argument convention must fail loudly."""
+    with pytest.raises(ValueError, match="must not exceed precision"):
+        DecimalParameter(Decimal("12.3456"), scale=4, precision=2)
+
+
 class Primitive(Enum):
     """These are the inferrable types. This Enum is used for parametrized tests."""