Document unique bound parameters for text()

Will backport the feature from part of 36e8fe4 / #4808 to
1.3.

Fixes: #4933
Change-Id: Ide4069ff5cccd5ed83a5f314e5f21e51dfe08b7d

diff --git a/doc/build/changelog/unreleased_13/4933.rst b/doc/build/changelog/unreleased_13/4933.rst
new file mode 100644 (file)
index 0000000..d9b8c6c
--- /dev/null
+++ b/doc/build/changelog/unreleased_13/4933.rst
@@ -0,0 +1,9 @@
+.. change::
+    :tags: usecase, sql
+    :tickets: 4933
+
+    The :func:`.text` construct now supports "unique" bound parameters, which
+    will dynamically uniquify themselves on compilation thus allowing multiple
+    :func:`.text` constructs with the same bound parameter names to be combined
+    together.
+

diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 78c434cff5d965f99fdf05da16f54e84130359ad..204530ccd2cf850b8e2c1e79601c31e4923740f3 100644 (file)
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -1667,6 +1667,35 @@ class TextClause(
                 timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5)
             )
 
+        The :meth:`.TextClause.bindparams` method also supports the concept of
+        **unique** bound parameters.  These are parameters that are
+        "uniquified" on name at statement compilation time, so that  multiple
+        :func:`.text` constructs may be combined together without the names
+        conflicting.  To use this feature, specify the
+        :paramref:`.BindParameter.unique` flag on each :func:`.bindparam`
+        object::
+
+            stmt1 = text("select id from table where name=:name").bindparams(
+                bindparam("name", value='name1', unique=True)
+            )
+            stmt2 = text("select id from table where name=:name").bindparams(
+                bindparam("name", value='name2', unique=True)
+            )
+
+            union = union_all(
+                stmt1.columns(column("id")),
+                stmt2.columns(column("id"))
+            )
+
+        The above statement will render as::
+
+            select id from table where name=:name_1
+            UNION ALL select id from table where name=:name_2
+
+        .. versionadded:: 1.3.11  Added support for the
+           :paramref:`.BindParameter.unique` flag to work with :func:`.text`
+           constructs.
+
         """
         self._bindparams = new_params = self._bindparams.copy()