docs(formatter): fix null semantics — None excluded by exclude_none, not SQLGlot default

At the FormatConfig/YAML layer, normalize_functions=None is excluded from
generator_options by PydanticModel.dict(exclude_none=True). format_model_expressions
therefore uses its own False default, so YAML null behaves like false — not like
SQLGlot's direct None deferral.

Changes:
- FormatConfig docstring: distinguish None (excluded -> False path) from True
  (defers to SQLGlot default -> uppercase); remove the incorrect claim they are
  equivalent
- format_model_expressions docstring: clarify that direct None passes None to the
  SQLGlot generator (dialect-dependent) while the config path never reaches this
  because None is excluded before the call
- docs/reference/configuration.md: describe null as taking the false-default path;
  true remains the value that defers to SQLGlot's generator default
- tests: add test_format_config_normalize_functions_none asserting that
  FormatConfig(normalize_functions=None).generator_options omits the key and that
  the resulting format call preserves custom function casing (False behaviour)

Signed-off-by: Alberto Suman <alberto.suman@1komma5grad.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: albertosuman-1k5

docs/reference/configuration.md

@@ -114,7 +114,7 @@ Formatting settings for the `sqlmesh format` command and UI.
 | `normalize`           | Whether to normalize SQL (Default: False)                                                      | boolean |    N     |
 | `pad`                 | The number of spaces to use for padding (Default: 2)                                           |   int   |    N     |
 | `indent`              | The number of spaces to use for indentation (Default: 2)                                       |   int   |    N     |
-| `normalize_functions` | How to normalize function name casing. `False` (default) preserves the casing of custom and audit function names as written; `"upper"` uppercases all function names; `"lower"` lowercases all function names; `true` or `null` defers to SQLGlot's generator default, which uppercases all function names including custom ones. Note: SQLGlot built-in function names may still be canonicalized by the parser regardless of this setting. | string \| boolean \| null |    N     |
+| `normalize_functions` | How to normalize function name casing. `false` (default) preserves the casing of custom and audit function names as written; `"upper"` uppercases all function names; `"lower"` lowercases all function names; `true` defers to SQLGlot's generator default and uppercases all function names including custom ones; `null` (or omitting the key) is excluded during serialization and therefore takes the same `false` default path — it does **not** defer to SQLGlot's generator default. Note: SQLGlot built-in function names may still be canonicalized by the parser regardless of this setting. | string \| boolean \| null |    N     |
 | `leading_comma`       | Whether to use leading commas (Default: False)                                                 | boolean |    N     |
 | `max_text_width`      | The maximum text width in a segment before creating new lines (Default: 80)                    |   int   |    N     |
 | `append_newline`      | Whether to append a newline to the end of the file (Default: False)                            | boolean |    N     |

sqlmesh/core/config/format.py

@@ -20,10 +20,13 @@ class FormatConfig(BaseConfig):
             * ``"upper"`` — uppercases all function names, including custom audit
               references.
             * ``"lower"`` — lowercases all function names, including built-in ones.
-            * ``True`` or ``None`` — defers to SQLGlot's generator default, which
-              uppercases all function names including custom ones.  These two values are
-              equivalent; ``None`` passes the deferral explicitly rather than relying on
-              the SQLGlot default.
+            * ``True`` — defers to SQLGlot's generator default, which uppercases all
+              function names including custom ones.
+            * ``None`` — excluded from the serialized generator options by Pydantic's
+              ``exclude_none`` behaviour, so ``format_model_expressions`` falls back to
+              its own ``False`` default.  Setting this in YAML as ``null`` or omitting
+              the key is therefore equivalent to ``false``; it does **not** defer to
+              SQLGlot's generator default the way ``True`` does.
         leading_comma: Whether to use leading commas or not.
         max_text_width: The maximum text width in a segment before creating new lines.
         append_newline: Whether to append a newline to the end of the file or not.

sqlmesh/core/dialect.py

@@ -807,9 +807,13 @@ def format_model_expressions(
             * ``"upper"`` — uppercases all function names including custom audit
               references.
             * ``"lower"`` — lowercases all function names including built-ins.
-            * ``True`` or ``None`` — defers to SQLGlot's generator default, which
-              uppercases all function names including custom ones.  Passing ``None``
-              makes the deferral explicit rather than relying on the SQLGlot default.
+            * ``True`` — defers to SQLGlot's generator default (uppercase).
+            * ``None`` — passes ``None`` directly to the SQLGlot generator, which
+              defers to SQLGlot's own default (typically uppercase, but may vary by
+              dialect).  Note: this is the **direct generator API** behaviour.  When
+              called via ``FormatConfig``, ``None`` is excluded by Pydantic's
+              ``exclude_none`` serialization and this function receives its own ``False``
+              default instead — so the two paths are not equivalent.
         **kwargs: Additional keyword arguments to pass to the sql generator.
 
     Returns:

tests/core/test_dialect.py

@@ -527,6 +527,37 @@ def test_format_config_normalize_functions_false():
     assert config.generator_options["normalize_functions"] is False
 
 
+def test_format_config_normalize_functions_none():
+    """FormatConfig(normalize_functions=None) must be accepted but excluded from
+    generator_options by Pydantic's exclude_none serialization.  The config-layer
+    null therefore takes the False-default path in format_model_expressions rather
+    than deferring to SQLGlot's generator default the way True does.
+    """
+    config = FormatConfig(normalize_functions=None)
+
+    assert config.normalize_functions is None
+    # None is excluded by PydanticModel.dict(exclude_none=True), so the key must
+    # be absent from generator_options — format_model_expressions will use False.
+    assert "normalize_functions" not in config.generator_options
+
+    # Confirm the False-default behaviour: custom audit names must be preserved.
+    expressions = parse(
+        """
+        MODEL (
+          name x,
+          audits (
+            unique_combination_of_columns(columns := (id)),
+            not_null(columns := (id))
+          )
+        );
+        SELECT id FROM foo
+        """
+    )
+    result = format_model_expressions(expressions, **config.generator_options)
+    assert "unique_combination_of_columns" in result
+    assert "not_null" in result
+
+
 def test_macro_format():
     assert parse_one("@EACH(ARRAY(1,2), x -> x)").sql() == "@EACH(ARRAY(1, 2), x -> x)"
     assert parse_one("INTERVAL @x DAY").sql() == "INTERVAL @x DAY"