Fixed #24894 -- Added contrib.postgres.functions.TransactionNow

docs/ref/contrib/postgres/functions.txt

@@ -0,0 +1,31 @@
+PostgreSQL specific database functions
+======================================
+
+All of these functions are available from the
+``django.contrib.postgres.functions`` module.
+
+.. currentmodule:: django.contrib.postgres.functions
+
+TransactionNow
+--------------
+
+.. class:: TransactionNow()
+
+.. versionadded:: 1.9
+
+Returns the date and time on the database server that the current transaction
+started. If you are not in a transaction it will return the date and time of
+the current statement. This is a complement to
+:class:`django.db.models.functions.Now`, which returns the date and time of the
+current statement.
+
+Note that only the outermost call to :func:`~django.db.transaction.atomic()`
+sets up a transaction and thus sets the time that ``TransactionNow()`` will
+return; nested calls create savepoints which do not affect the transaction
+time.
+
+Usage example::
+
+    >>> from django.contrib.postgres.functions import TransactionNow
+    >>> Article.objects.filter(published__lte=TransactionNow())
+    [<Article: How to Django>]

docs/ref/contrib/postgres/index.txt

@@ -34,6 +34,7 @@ Psycopg2 2.5 or higher is required.
     aggregates
     fields
     forms
+    functions
     lookups
     operations
     validators

docs/ref/models/database-functions.txt

@@ -203,7 +203,8 @@ Now
 
 .. versionadded:: 1.9
 
-Returns the database server's current date and time when the query is executed.
+Returns the database server's current date and time when the query is executed,
+typically using the SQL ``CURRENT_TIMESTAMP``.
 
 Usage example::
 
@@ -211,6 +212,13 @@ Usage example::
     >>> Article.objects.filter(published__lte=Now())
     [<Article: How to Django>]
 
+.. admonition:: PostgreSQL considerations
+
+    On PostgreSQL, the SQL ``CURRENT_TIMESTAMP`` returns the time that the
+    current transaction started. Therefore for cross-database compatibility,
+    ``Now()`` uses ``STATEMENT_TIMESTAMP`` instead. If you need the transaction
+    timestamp, use :class:`django.contrib.postgres.functions.TransactionNow`.
+
 Substr
 ------
 

docs/releases/1.9.txt

@@ -141,13 +141,18 @@ Minor features
 
 * Added support for the :lookup:`rangefield.contained_by` lookup for some built
   in fields which correspond to the range fields.
+
 * Added :class:`~django.contrib.postgres.fields.JSONField`.
+
 * Added :doc:`/ref/contrib/postgres/aggregates`.
 
 * Fixed serialization of
   :class:`~django.contrib.postgres.fields.DateRangeField` and
   :class:`~django.contrib.postgres.fields.DateTimeRangeField`.
 
+* Added the :class:`~django.contrib.postgres.functions.TransactionNow` database
+  function.
+
 :mod:`django.contrib.redirects`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^