Add documentation regarding row constructo in PostgreSQL

Fixes: #5331
Change-Id: Ia795a4d4d8ae4944d8a160d18f8b917177acf0de
(cherry picked from commit 95106a9175741528cebfde8b6d0fd9756f82bd20)

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index 08f1e018e1be333f581086efd2ca799e98fac1e2..aacfc47d8a3a4759ba16205ebfe438b439dfab35 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -566,7 +566,7 @@ PostgreSQL to ensure that you are generating queries with SQLAlchemy that
 take full advantage of any indexes you may have created for full text search.
 
 FROM ONLY ...
-------------------------
+-------------
 
 The dialect supports PostgreSQL's ONLY keyword for targeting only a particular
 table in an inheritance hierarchy. This can be used to produce the
@@ -813,6 +813,50 @@ dialect in conjunction with the :class:`_schema.Table` construct:
     `PostgreSQL CREATE TABLE options
     <http://www.postgresql.org/docs/current/static/sql-createtable.html>`_
 
+Table values, Row and Tuple objects
+-----------------------------------
+
+Row Types
+^^^^^^^^^
+
+Built-in support for rendering a ``ROW`` is not available yet, however the
+:func:`_expression.tuple_` may be used in its place. Another alternative is
+to use the :attr:`_sa.func` generator with ``func.ROW`` ::
+
+    table.select().where(
+        tuple_(table.c.id, table.c.fk) > (1,2)
+    ).where(func.ROW(table.c.id, table.c.fk) < func.ROW(3, 7))
+
+Will generate the row-wise comparison::
+
+    SELECT *
+    FROM table
+    WHERE (id, fk) > (1, 2)
+    AND ROW(id, fk) < ROW(3, 7)
+
+.. seealso::
+
+    `PostgreSQL Row Constructors
+    <https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS>`_
+
+    `PostgreSQL Row Constructor Comparison
+    <https://www.postgresql.org/docs/current/functions-comparisons.html#ROW-WISE-COMPARISON>`_
+
+Table Types
+^^^^^^^^^^^
+
+PostgreSQL also supports passing a table as an argument to a function. This
+is not available yet in sqlalchemy, however the
+:func:`_expression.literal_column` function with the name of the table may be
+used in its place::
+
+    select(['*']).select_from(func.my_function(literal_column('my_table')))
+
+Will generate the SQL::
+
+    SELECT *
+    FROM my_function(my_table)
+
 ARRAY Types
 -----------