- Document the most transparent way to set JSON.NULL for

a column default.

The JSON.NULL value is special in that while it is a Python-side
value, it represents "do this special behavior", and is not at all
like any other Python-side value for which normally, that's exactly
the type of data we want back.   So in this case, encourage the user
to use a SQL expression that is exact, so in the ORM context, you get
back what was actually persisted in the column.  There's some variants
of this such as literal(JSON.NULL, JSON) but text("'null'") is simpler.

Change-Id: I0339fafdc03e4b2f533d53970b2f74c774f2687b
Fixes: #3923
(cherry picked from commit 4d4ea792e7ea7945de9c9b1e005ce09b2feb45b5)

diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index 8a114ece60ec7a6fc8bb2dc662caba8441644640..4ceee1bd6bbad6a82f6b1861946c0b7132cd4eb4 100644 (file)
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -1911,6 +1911,22 @@ class JSON(Indexable, TypeEngine):
         session.add_all([obj1, obj2])
         session.commit()
 
+    In order to set JSON NULL as a default value for a column, the most
+    transparent method is to use :func:`.text`::
+
+        Table(
+            'my_table', metadata,
+            Column('json_data', JSON, default=text("'null'"))
+        )
+
+    While it is possible to use :attr:`.JSON.NULL` in this context, the
+    :attr:`.JSON.NULL` value will be returned as the value of the column,
+    which in the context of the ORM or other repurposing of the default
+    value, may not be desirable.  Using a SQL expression means the value
+    will be re-fetched from the database within the context of retrieving
+    generated defaults.
+
+
     """
 
     def __init__(self, none_as_null=False):