From 4b9d72210f0201efeafb9703e166aa3b38c04873 Mon Sep 17 00:00:00 2001
From: Mads Jensen <mje@inducks.org>
Date: Sun, 14 Jan 2018 22:00:16 +0100
Subject: Refs #28643 -- Added NullIf database function.

Thanks Nick Pope, Mariusz Felisiak, and Tim Graham for reviews.
---
 docs/ref/models/database-functions.txt | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

(limited to 'docs/ref/models')

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
-- 
cgit v1.3