Refs #28643 -- Added NullIf database function.

Thanks Nick Pope, Mariusz Felisiak, and Tim Graham for reviews.

3 files changed, 24 insertions, 0 deletions

diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 04214a6560..0c584f7110 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -899,6 +899,8 @@ occur when an Oracle datatype is used as a column name.  In
 particular, take care to avoid using the names ``date``,
 ``timestamp``, ``number`` or ``float`` as a field name.
 
+.. _oracle-null-empty-strings:
+
 NULL and empty strings
 ----------------------
 
diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt
index f1affb2b6f..2661b65c78 100644
--- a/docs/ref/models/database-functions.txt
+++ b/docs/ref/models/database-functions.txt
@@ -149,6 +149,25 @@ will result in a database error.
     The PostgreSQL behavior can be emulated using ``Coalesce`` if you know
     a sensible maximum value to provide as a default.
 
+``NullIf``
+----------
+
+.. class:: NullIf(expression1, expression2)
+
+.. versionadded:: 2.2
+
+Accepts two expressions and returns ``None`` if they are equal, otherwise
+returns ``expression1``.
+
+.. admonition:: Caveats on Oracle
+
+    Due to an :ref:`Oracle convention<oracle-null-empty-strings>`, this
+    function returns the empty string instead of ``None`` when the expressions
+    are of type :class:`~django.db.models.CharField`.
+
+    Passing ``Value(None)`` to ``expression1`` is prohibited on Oracle since
+    Oracle doesn't accept ``NULL`` as the first argument.
+
 .. _date-functions:
 
 Date functions
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 843aadd24f..bc950eb88e 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -220,6 +220,9 @@ Models
 
 * Added many :ref:`math database functions <math-functions>`.
 
+* The new :class:`~django.db.models.functions.NullIf` database function
+  returns ``None`` if the two expressions are equal.
+
 * Setting the new ``ignore_conflicts`` parameter of
   :meth:`.QuerySet.bulk_create` to ``True`` tells the database to ignore
   failure to insert rows that fail uniqueness constraints or other checks.