From 76ec285ba452acf36d725799896904477a9c2dbd Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 19 Oct 2016 12:52:55 -0400 Subject: Rewrite migration notes for [ticket:3514] The change to "evaluates none" datatypes in the ORM was not fully described in the migration notes, missing the key behavioral change that a column which is missing a default entirely will not receive a value for a missing JSON column now. The issue here touched upon a revisit of the assumptions in [ticket:3514], but overall the old behavior "worked" mostly because the ORM wants to explicitly render NULL into an INSERT for column values that are missing, which itself is a legacy behavior which should be considered for possible removal in a future major release. Given that "missing ORM value + no column default set up == dont put it in the INSERT" would be the most intuitive behavior, the move in [ticket:3514] represents a step in this direction. Change-Id: I454d5bb0773bd73d9864925dcc47f1f0810e33ba Fixes: #3830 --- lib/sqlalchemy/sql/sqltypes.py | 7 +++++++ lib/sqlalchemy/sql/type_api.py | 7 +++++++ 2 files changed, 14 insertions(+) (limited to 'lib/sqlalchemy/sql') diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py index 118c26070..cae23902b 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -1796,6 +1796,13 @@ class JSON(Indexable, TypeEngine): from sqlalchemy import null conn.execute(table.insert(), data=null()) + .. note:: + + :paramref:`.JSON.none_as_null` does **not** apply to the + values passed to :paramref:`.Column.default` and + :paramref:`.Column.server_default`; a value of ``None`` passed for + these parameters means "no default present". + .. seealso:: :attr:`.types.JSON.NULL` diff --git a/lib/sqlalchemy/sql/type_api.py b/lib/sqlalchemy/sql/type_api.py index 217f7016b..689b4c79b 100644 --- a/lib/sqlalchemy/sql/type_api.py +++ b/lib/sqlalchemy/sql/type_api.py @@ -182,6 +182,13 @@ class TypeEngine(Visitable): the :obj:`~.expression.null` SQL construct in an INSERT statement or associated with an ORM-mapped attribute. + .. note:: + + The "evaulates none" flag does **not** apply to a value + of ``None`` passed to :paramref:`.Column.default` or + :paramref:`.Column.server_default`; in these cases, ``None`` + still means "no default". + .. versionadded:: 1.1 .. seealso:: -- cgit v1.2.1