feat: struct-aware schema_dump default + values_from / set_from builder methods (#442)

## Summary

- Flip `schema_dump` `wire_format` default from `True` to `False`. Cross-library consistency: `msgspec.Struct` now matches Pydantic / dataclass / attrs by default. Wire-aligned output (camelCase via `field.encode_name`) requires explicit `wire_format=True`.
- Add `Insert.values_from`, `Insert.values_from_many`, `Update.set_from`. Each accepts any schema kind (dict, dataclass, msgspec, Pydantic, attrs) and dispatches through `schema_dump(wire_format=False)`.
- Deprecate `Insert.values_from_dict` / `Insert.values_from_dicts`. Both emit `DeprecationWarning` pointing at the new methods. Removal target: 0.48.0.
- `values_from_many` now uses `serialize_collection` (per-batch type-keyed cache) instead of a per-item `schema_dump` loop.

## Why

`schema_dump`'s prior default (`wire_format=True`) silently emitted `field.encode_name` keys for `msgspec.Struct(rename=...)` instances — meaning `sql.insert(t).columns(*schema_dump(struct).keys()).values(...)` against snake_case Postgres tables blew up with `column "userId" does not exist` whenever the source schema declared `rename="camel"`.

## Behavior change

| Caller pattern | Before | After |
|---|---|---|
| `schema_dump(struct)` on `msgspec.Struct(rename="camel")` | `{"userId": ...}` | `{"user_id": ...}` |
| `schema_dump(struct, wire_format=True)` | `{"userId": ...}` | `{"userId": ...}` (unchanged) |
| `schema_dump(pydantic_model)` / `dataclass` / `attrs` | Python names | Python names (unchanged) |
| `Insert.values_from_dict({...})` | Silent | Emits `DeprecationWarning` |

Author: cofin

docs/changelog.rst

@@ -13,6 +13,36 @@ Recent Updates
 v0.46.2 - Framework Filter ``orderBy`` Aliases (Unreleased)
 -----------------------------------------------------------
 
+**Changed (breaking default):**
+
+* ``sqlspec.utils.serializers.schema_dump`` (and its helpers
+  ``serialize_collection`` / ``get_collection_serializer``) now default
+  ``wire_format=False``. Calling ``schema_dump(struct)`` on a ``msgspec.Struct``
+  declared with ``rename=`` now returns Python attribute names by default
+  (matching Pydantic, dataclass, and attrs output) instead of wire-aligned
+  ``field.encode_name`` keys. Pass ``wire_format=True`` explicitly to restore
+  the prior wire-aligned output for JSON / API payloads. This default flip
+  closes the silent footgun where ``sql.update(t).set(**schema_dump(struct))``
+  emitted camelCase column names for snake_case database tables. The kwarg
+  remains a no-op for non-msgspec inputs.
+
+**Added:**
+
+* ``Insert.values_from(data, *, exclude_unset=True)``,
+  ``Insert.values_from_many(items, *, exclude_unset=True)``, and
+  ``Update.set_from(data, *, exclude_unset=True)`` builder methods. Each accepts
+  any schema kind (dict, dataclass, ``msgspec.Struct``, ``pydantic.BaseModel``,
+  attrs class) and dispatches through ``schema_dump(wire_format=False)`` so SQL
+  column names are always Python attribute names regardless of any wire-rename
+  meta on the source schema.
+
+**Deprecated:**
+
+* ``Insert.values_from_dict`` and ``Insert.values_from_dicts`` now emit a
+  ``DeprecationWarning`` pointing at ``Insert.values_from`` /
+  ``Insert.values_from_many`` respectively. The dict-shaped methods continue to
+  work; they are scheduled for removal in 0.48.0.
+
 **Fixed:**
 
 * Missing named SQL statements now raise ``SQLStatementNotFoundError``, a

sqlspec/builder/_dml.py

@@ -11,6 +11,7 @@
 from sqlspec.builder._parsing_utils import extract_sql_object_expression
 from sqlspec.exceptions import SQLBuilderError
 from sqlspec.protocols import SQLBuilderProtocol
+from sqlspec.utils.serializers import schema_dump
 from sqlspec.utils.type_guards import has_expression_and_sql, has_parameter_builder, is_dict
 
 __all__ = (
@@ -322,6 +323,26 @@ def set(self, *args: Any, **kwargs: Any) -> Self:
         current_expr.set("expressions", existing + assignments)
         return self
 
+    def set_from(self, data: Any, *, exclude_unset: bool = True) -> Self:
+        """Set columns from a dict, dataclass, msgspec.Struct, Pydantic model, or attrs class.
+
+        Schema instances are normalised via :func:`sqlspec.utils.serializers.schema_dump`
+        with ``wire_format=False`` and dispatched to :meth:`set` via keyword unpack. The
+        dict shape uses Python attribute names regardless of msgspec ``rename=`` or
+        Pydantic ``Field(alias=...)``.
+
+        Args:
+            data: A dict, dataclass instance, ``msgspec.Struct``, ``pydantic.BaseModel``,
+                or ``attrs``-decorated class instance.
+            exclude_unset: If True, exclude fields that were never set (msgspec UNSET,
+                Pydantic ``model_fields_set``, dataclass empty defaults). No-op for attrs.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        payload = schema_dump(data, exclude_unset=exclude_unset, wire_format=False)
+        return self.set(**payload)
+
 
 @trait
 class UpdateFromClauseMixin:

sqlspec/builder/_insert.py

@@ -16,6 +16,8 @@
 from sqlspec.builder._select import ReturningClauseMixin
 from sqlspec.core import SQLResult
 from sqlspec.exceptions import SQLBuilderError
+from sqlspec.utils.deprecation import warn_deprecation
+from sqlspec.utils.serializers import schema_dump, serialize_collection
 from sqlspec.utils.type_guards import has_expression_and_sql
 
 if TYPE_CHECKING:
@@ -104,21 +106,8 @@ def get_insert_expression(self) -> exp.Insert:
         """Get the insert expression (public API)."""
         return self._get_insert_expression()
 
-    def values_from_dict(self, data: "Mapping[str, Any]") -> "Self":
-        """Adds a row of values from a dictionary.
-
-        This is a convenience method that automatically sets columns based on
-        the dictionary keys and values based on the dictionary values.
-
-        Args:
-            data: A mapping of column names to values.
-
-        Returns:
-            The current builder instance for method chaining.
-
-        Raises:
-            SQLBuilderError: If `into()` has not been called to set the table.
-        """
+    def _bind_values_from_dict(self, data: "Mapping[str, Any]") -> "Self":
+        """Bind a single dict row without deprecation warnings (internal)."""
         insert_expr = self._get_insert_expression()
         if insert_expr.args.get("this") is None:
             raise SQLBuilderError(ERR_MSG_TABLE_NOT_SET)
@@ -132,21 +121,8 @@ def values_from_dict(self, data: "Mapping[str, Any]") -> "Self":
 
         return self.values(*[data[col] for col in self._columns])
 
-    def values_from_dicts(self, data: "Sequence[Mapping[str, Any]]") -> "Self":
-        """Adds multiple rows of values from a sequence of dictionaries.
-
-        This is a convenience method for bulk inserts from structured data.
-
-        Args:
-            data: A sequence of mappings, each representing a row of data.
-
-        Returns:
-            The current builder instance for method chaining.
-
-        Raises:
-            SQLBuilderError: If `into()` has not been called to set the table,
-                           or if dictionaries have inconsistent keys.
-        """
+    def _bind_values_from_dicts(self, data: "Sequence[Mapping[str, Any]]") -> "Self":
+        """Bind many dict rows without deprecation warnings (internal)."""
         if not data:
             return self
 
@@ -168,6 +144,107 @@ def values_from_dicts(self, data: "Sequence[Mapping[str, Any]]") -> "Self":
 
         return self
 
+    def values_from_dict(self, data: "Mapping[str, Any]") -> "Self":
+        """Adds a row of values from a dictionary.
+
+        .. deprecated:: 0.46.2
+            Use :meth:`values_from` instead — it accepts dicts, msgspec Structs,
+            Pydantic models, dataclasses, and attrs classes.
+
+        Args:
+            data: A mapping of column names to values.
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Raises:
+            SQLBuilderError: If `into()` has not been called to set the table.
+        """
+        warn_deprecation(
+            version="0.46.2",
+            deprecated_name="Insert.values_from_dict",
+            kind="method",
+            alternative="Insert.values_from() — accepts dicts, msgspec Structs, Pydantic models, dataclasses, and attrs classes",
+            removal_in="0.48.0",
+        )
+        return self._bind_values_from_dict(data)
+
+    def values_from_dicts(self, data: "Sequence[Mapping[str, Any]]") -> "Self":
+        """Adds multiple rows of values from a sequence of dictionaries.
+
+        .. deprecated:: 0.46.2
+            Use :meth:`values_from_many` instead — it accepts dicts, msgspec Structs,
+            Pydantic models, dataclasses, and attrs classes.
+
+        Args:
+            data: A sequence of mappings, each representing a row of data.
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Raises:
+            SQLBuilderError: If `into()` has not been called to set the table,
+                           or if dictionaries have inconsistent keys.
+        """
+        warn_deprecation(
+            version="0.46.2",
+            deprecated_name="Insert.values_from_dicts",
+            kind="method",
+            alternative="Insert.values_from_many() — accepts dicts, msgspec Structs, Pydantic models, dataclasses, and attrs classes",
+            removal_in="0.48.0",
+        )
+        return self._bind_values_from_dicts(data)
+
+    def values_from(self, data: Any, *, exclude_unset: bool = True) -> "Self":
+        """Add a row of values from a dict, dataclass, msgspec.Struct, Pydantic model, or attrs class.
+
+        Schema instances are normalised via :func:`sqlspec.utils.serializers.schema_dump`
+        with ``wire_format=False`` then bound as a single row. The dict shape uses Python
+        attribute names regardless of msgspec ``rename=`` or Pydantic ``Field(alias=...)``;
+        wire-aligned names never make sense for SQL column binding.
+
+        Args:
+            data: A dict, dataclass instance, ``msgspec.Struct``, ``pydantic.BaseModel``,
+                or ``attrs``-decorated class instance.
+            exclude_unset: If True, exclude fields that were never set. Honoured by
+                msgspec (UNSET fields), Pydantic (``model_fields_set``), and dataclass
+                (via empty default-field semantics). No-op for attrs.
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Raises:
+            SQLBuilderError: If ``into()`` has not been called or the dict shape is
+                incompatible with previously set columns.
+        """
+        payload = schema_dump(data, exclude_unset=exclude_unset, wire_format=False)
+        return self._bind_values_from_dict(payload)
+
+    def values_from_many(self, items: "Sequence[Any]", *, exclude_unset: bool = True) -> "Self":
+        """Add multiple rows from a sequence of dicts, dataclasses, msgspec Structs, Pydantic models, or attrs classes.
+
+        Each item is normalised via :func:`sqlspec.utils.serializers.schema_dump` with
+        ``wire_format=False`` then bound as a multi-row INSERT. Mixed schema kinds in the
+        same sequence are supported (each item normalises independently); however, the
+        resulting dict shapes must agree on key sets.
+
+        Args:
+            items: A sequence of schema instances or dicts.
+            exclude_unset: See :meth:`values_from` for per-library semantics.
+
+        Returns:
+            The current builder instance for method chaining. Empty input returns the
+            builder unchanged.
+
+        Raises:
+            SQLBuilderError: If ``into()`` has not been called or item dict shapes
+                disagree on key sets.
+        """
+        if not items:
+            return self
+        payload = serialize_collection(items, exclude_unset=exclude_unset, wire_format=False)
+        return self._bind_values_from_dicts(payload)
+
     def on_conflict(self, *columns: str) -> "ConflictBuilder":
         """Adds an ON CONFLICT clause with specified columns.
 

sqlspec/utils/serializers/_schema.py

@@ -201,7 +201,7 @@ def _build_dump_function(sample: Any, exclude_unset: bool, wire_format: bool) ->
 
 
 def get_collection_serializer(
-    sample: Any, *, exclude_unset: bool = True, wire_format: bool = True
+    sample: Any, *, exclude_unset: bool = True, wire_format: bool = False
 ) -> "SchemaSerializer":
     """Return cached serializer pipeline for the provided sample object."""
     key = _make_serializer_key(sample, exclude_unset, wire_format)
@@ -219,7 +219,7 @@ def get_collection_serializer(
 
 
 def serialize_collection(
-    items: "Iterable[Any]", *, exclude_unset: bool = True, wire_format: bool = True
+    items: "Iterable[Any]", *, exclude_unset: bool = True, wire_format: bool = False
 ) -> "list[Any]":
     """Serialize a collection using cached pipelines keyed by item type."""
     serialized: list[Any] = []
@@ -254,19 +254,20 @@ def get_serializer_metrics() -> "dict[str, int]":
         return metrics
 
 
-def schema_dump(data: Any, *, exclude_unset: bool = True, wire_format: bool = True) -> Any:
+def schema_dump(data: Any, *, exclude_unset: bool = True, wire_format: bool = False) -> Any:
     """Dump a schema model or dict to a plain representation.
 
     Args:
         data: A schema instance (msgspec.Struct, Pydantic BaseModel, dataclass, attrs class)
             or plain dict / primitive.
         exclude_unset: If True, exclude fields that were never set (msgspec UNSET, Pydantic
             model_fields_set semantics). No-op for attrs (attrs has no unset concept).
-        wire_format: msgspec-only knob. Default True keeps the historical behavior of
-            emitting ``field.encode_name`` (honours ``rename=`` on the Struct). Pass
-            ``wire_format=False`` to opt msgspec into Python attribute names (``field.name``)
-            for cross-library consistency. Pydantic, dataclass, and attrs branches always
-            use Python attribute names regardless of this flag.
+        wire_format: msgspec-only knob. Default ``False`` emits Python attribute names
+            (``field.name``) for cross-library consistency — keys match Pydantic, dataclass,
+            and attrs output regardless of the Struct's ``rename=`` meta. Pass
+            ``wire_format=True`` to emit ``field.encode_name`` (honours ``rename=`` on the
+            Struct) for wire-aligned JSON / API payloads. Pydantic, dataclass, and attrs
+            branches always use Python attribute names regardless of this flag.
     """
     if is_dict(data):
         return data

tests/unit/builder/test_insert_builder.py

@@ -33,9 +33,10 @@ def test_insert_with_table_in_constructor() -> None:
 
 
 def test_insert_values_from_dict() -> None:
-    """Test INSERT using values_from_dict method."""
+    """Test INSERT using values_from_dict method (deprecated; emits DeprecationWarning)."""
     data = {"id": 1, "name": "John", "status": "active"}
-    query = sql.insert("users").values_from_dict(data)
+    with pytest.warns(DeprecationWarning, match=r"values_from"):
+        query = sql.insert("users").values_from_dict(data)
     stmt = query.build()
 
     assert "INSERT INTO" in stmt.sql
@@ -46,9 +47,10 @@ def test_insert_values_from_dict() -> None:
 
 
 def test_insert_values_from_dicts_multiple_rows() -> None:
-    """Test INSERT using values_from_dicts for multiple rows."""
+    """Test INSERT using values_from_dicts for multiple rows (deprecated; emits DeprecationWarning)."""
     data = [{"id": 1, "name": "John"}, {"id": 2, "name": "Jane"}, {"id": 3, "name": "Bob"}]
-    query = sql.insert("users").values_from_dicts(data)
+    with pytest.warns(DeprecationWarning, match=r"values_from"):
+        query = sql.insert("users").values_from_dicts(data)
     stmt = query.build()
 
     assert "INSERT INTO" in stmt.sql
@@ -130,9 +132,12 @@ def test_insert_columns_and_values_consistency() -> None:
 
 
 def test_insert_inconsistent_dict_keys_error() -> None:
-    """Test that inconsistent dictionary keys in values_from_dicts raises error."""
+    """Test that inconsistent dictionary keys in values_from_dicts raises error (deprecated method)."""
     data = [{"id": 1, "name": "John"}, {"id": 2, "email": "jane@test.com"}]
-    with pytest.raises(SQLBuilderError, match="do not match expected keys"):
+    with (
+        pytest.warns(DeprecationWarning, match=r"values_from"),
+        pytest.raises(SQLBuilderError, match="do not match expected keys"),
+    ):
         sql.insert("users").values_from_dicts(data).build()
 
 
@@ -310,12 +315,42 @@ def test_on_conflict_parameter_merging() -> None:
 
 
 def test_on_conflict_with_values_from_dict() -> None:
-    """Test ON CONFLICT with values_from_dict."""
+    """Test ON CONFLICT with values_from_dict (deprecated method emits DeprecationWarning)."""
     data = {"id": 1, "name": "John", "email": "john@test.com"}
-    query = sql.insert("users").values_from_dict(data).on_conflict("id").do_update(name="Updated")
+    with pytest.warns(DeprecationWarning, match=r"values_from"):
+        query = sql.insert("users").values_from_dict(data).on_conflict("id").do_update(name="Updated")
     stmt = query.build()
 
     assert "ON CONFLICT" in stmt.sql
     assert "DO UPDATE" in stmt.sql
     assert "name_1" in stmt.parameters
     assert stmt.parameters["name_1"] == "Updated"
+
+
+def test_values_from_dict_warning_message_contains_migration_pointer() -> None:
+    """Warning text must name the replacement API explicitly."""
+    import warnings
+
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        sql.insert("users").values_from_dict({"id": 1})
+
+    deprecation_warnings = [w for w in caught if issubclass(w.category, DeprecationWarning)]
+    assert len(deprecation_warnings) == 1
+    msg = str(deprecation_warnings[0].message)
+    assert "values_from" in msg
+    assert "msgspec" in msg or "Pydantic" in msg or "dataclass" in msg
+
+
+def test_values_from_dicts_warning_message_contains_migration_pointer() -> None:
+    """values_from_dicts warning must point at values_from_many()."""
+    import warnings
+
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        sql.insert("users").values_from_dicts([{"id": 1}])
+
+    deprecation_warnings = [w for w in caught if issubclass(w.category, DeprecationWarning)]
+    assert len(deprecation_warnings) == 1
+    msg = str(deprecation_warnings[0].message)
+    assert "values_from_many" in msg

tests/unit/builder/test_parameter_naming.py

@@ -173,8 +173,8 @@ def test_insert_with_columns_uses_column_names() -> None:
 
 
 def test_insert_values_from_dict_preserves_keys() -> None:
-    """Test that INSERT values_from_dict preserves dictionary keys."""
-    query = sql.insert("orders").values_from_dict({
+    """Test that INSERT values_from preserves dictionary keys."""
+    query = sql.insert("orders").values_from({
         "customer_id": 12345,
         "product_name": "Widget",
         "quantity": 3,
@@ -314,7 +314,7 @@ def test_no_generic_param_names_in_update_operations() -> None:
 def test_no_generic_param_names_in_insert_operations() -> None:
     """Test that INSERT operations use descriptive parameter names."""
     test_cases = [
-        sql.insert("users").values_from_dict({"name": "John", "email": "john@test.com"}),
+        sql.insert("users").values_from({"name": "John", "email": "john@test.com"}),
         sql.insert("posts").columns("title", "content").values("Hello", "World"),
     ]