add example to update from that uses values

Change-Id: Ic02a722be9a30851a87e0da4759c728e86fb22c8
References: #11768
(cherry picked from commit fb5e64c51ab91edf9ab0936aa540195746f9155b)

diff --git a/doc/build/tutorial/data_update.rst b/doc/build/tutorial/data_update.rst
index e32b6676c76d0b72f3cfa108ebd95693348fe4ec..d21b153144d18ea603c18da8110f6f10265b59d5 100644 (file)
--- 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 a3b6965c862a4a25137c4f604db2acb03192b625..76c341652e34816e31d85b70b2002d886f3f7fec 100644 (file)
--- 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"}