- 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

diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index b8c8c811687b744ff06e87c08f5c639f56c59602..7a3c50549e1caf9ac9e9c672f868cc31f560eb9a 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):