From: Federico Caselli <cfederico87@gmail.com>
Date: Tue, 10 Jun 2025 21:42:35 +0000 (+0200)
Subject: add example to update from that uses values
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fb5e64c51ab91edf9ab0936aa540195746f9155b;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

add example to update from that uses values

Change-Id: Ic02a722be9a30851a87e0da4759c728e86fb22c8
References: #11768
---

diff --git a/doc/build/orm/declarative_tables.rst b/doc/build/orm/declarative_tables.rst
index 4102680b75..5eb9578568 100644
--- a/doc/build/orm/declarative_tables.rst
+++ b/doc/build/orm/declarative_tables.rst
@@ -1026,9 +1026,9 @@ more open ended.
             col_a: Mapped[str | float | bool | None]
             col_b: Mapped[str | float | bool]
 
-    This raises an error since the union types used by ``col_a`` or ``col_b``,
-    are not found in ``TABase`` type map and ``JsonScalar`` must be referenced
-    directly.
+  This raises an error since the union types used by ``col_a`` or ``col_b``,
+  are not found in ``TABase`` type map and ``JsonScalar`` must be referenced
+  directly.
 
 .. _orm_declarative_mapped_column_pep593:
 
diff --git a/doc/build/tutorial/data_update.rst b/doc/build/tutorial/data_update.rst
index e32b6676c7..d21b153144 100644
--- a/doc/build/tutorial/data_update.rst
+++ b/doc/build/tutorial/data_update.rst
@@ -135,7 +135,7 @@ anywhere a column expression might be placed::
 UPDATE..FROM
 ~~~~~~~~~~~~~
 
-Some databases such as PostgreSQL and MySQL support a syntax "UPDATE FROM"
+Some databases such as PostgreSQL, MSSQL and MySQL support a syntax ``UPDATE...FROM``
 where additional tables may be stated directly in a special FROM clause. This
 syntax will be generated implicitly when additional tables are located in the
 WHERE clause of the statement::
@@ -172,6 +172,27 @@ order to refer to additional tables::
   SET address.email_address=%s, user_account.fullname=%s
   WHERE user_account.id = address.user_id AND address.email_address = %s
 
+``UPDATE...FROM`` can also be
+combined with the :class:`_sql.Values` construct
+on backends such as PostgreSQL, to create a single UPDATE statement that updates
+multiple rows at once against the named form of VALUES::
+
+  >>> from sqlalchemy import Values
+  >>> values = Values(
+  ...     user_table.c.id,
+  ...     user_table.c.name,
+  ...     name="my_values",
+  ... ).data([(1, "new_name"), (2, "another_name"), ("3", "name_name")])
+  >>> update_stmt = (
+  ...     user_table.update().values(name=values.c.name).where(user_table.c.id == values.c.id)
+  ... )
+  >>> from sqlalchemy.dialects import postgresql
+  >>> print(update_stmt.compile(dialect=postgresql.dialect()))
+  {printsql}UPDATE user_account
+  SET name=my_values.name
+  FROM (VALUES (%(param_1)s, %(param_2)s), (%(param_3)s, %(param_4)s), (%(param_5)s, %(param_6)s)) AS my_values (id, name)
+  WHERE user_account.id = my_values.id
+
 .. _tutorial_parameter_ordered_updates:
 
 Parameter Ordered Updates
diff --git a/tools/format_docs_code.py b/tools/format_docs_code.py
index a3b6965c86..76c341652e 100644
--- a/tools/format_docs_code.py
+++ b/tools/format_docs_code.py
@@ -31,7 +31,7 @@ ignore_paths = (
     re.compile(r"changelog/unreleased_\d{2}"),
     re.compile(r"README\.unittests\.rst"),
     re.compile(r"\.tox"),
-    re.compile(r"build"),
+    re.compile(rf"{home.as_posix()}/build"),
 )
 
 CUSTOM_TARGET_VERSIONS = {"declarative_tables.rst": "PY312"}