From d34d39ade76e6b67299d8d88a7e5a2278a793dc3 Mon Sep 17 00:00:00 2001
From: Adam Chainz <adam@adamj.eu>
Date: Mon, 1 Jun 2015 18:00:34 +0100
Subject: Fixed #24894 -- Added contrib.postgres.functions.TransactionNow

---
 docs/ref/contrib/postgres/functions.txt | 31 +++++++++++++++++++++++++++++++
 docs/ref/contrib/postgres/index.txt     |  1 +
 docs/ref/models/database-functions.txt  | 10 +++++++++-
 docs/releases/1.9.txt                   |  5 +++++
 4 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 docs/ref/contrib/postgres/functions.txt

(limited to 'docs')

diff --git a/docs/ref/contrib/postgres/functions.txt b/docs/ref/contrib/postgres/functions.txt
new file mode 100644
index 0000000000..c97af99bfb
--- /dev/null
+++ b/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>]
diff --git a/docs/ref/contrib/postgres/index.txt b/docs/ref/contrib/postgres/index.txt
index 7ff66d0770..a1536680c7 100644
--- a/docs/ref/contrib/postgres/index.txt
+++ b/docs/ref/contrib/postgres/index.txt
@@ -34,6 +34,7 @@ Psycopg2 2.5 or higher is required.
     aggregates
     fields
     forms
+    functions
     lookups
     operations
     validators
diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt
index f1293ba741..336e4afc05 100644
--- a/docs/ref/models/database-functions.txt
+++ b/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
 ------
 
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index e858838b4e..e1f7439b88 100644
--- a/docs/releases/1.9.txt
+++ b/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`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- 
cgit v1.3