bulk_save->return_defaults does not populate server defaults

it fetches them but doesn't put them on the objects, which
is likely a bug, however i have no intention of working
on the bulk methods.   Add more documentation to strongly
discourage these methods in favor of more explicit bulk
approaches, e.g. using an insert() construct directly.

Fixes: #6273
Change-Id: I83eac9319f4e35111302cc81471ecaf19514ce86

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index a93684126b5c6b7366cc5104239e29008b72ab46..0368bf83a39bc4c0f9b3cdd5e012dfadeefaa239 100644 (file)
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -3467,11 +3467,14 @@ class Session(_SessionClassMethods):
         SQL expressions.
 
         The objects as given are not added to the session and no additional
-        state is established on them, unless the ``return_defaults`` flag
-        is also set, in which case primary key attributes and server-side
-        default values will be populated.
-
-        .. versionadded:: 1.0.0
+        state is established on them. If the
+        :paramref:`_orm.Session.bulk_save_objects.return_defaults` flag is set,
+        then server-generated primary key values will be assigned to the
+        returned objects, but **not server side defaults**; this is a
+        limitation in the implementation. If stateful objects are desired,
+        please use the standard :meth:`_orm.Session.add_all` approach or
+        as an alternative newer mass-insert features such as
+        :ref:`orm_dml_returning_objects`.
 
         .. warning::
 
@@ -3481,6 +3484,14 @@ class Session(_SessionClassMethods):
             and SQL clause support are **silently omitted** in favor of raw
             INSERT/UPDATES of records.
 
+            Please note that newer versions of SQLAlchemy are **greatly
+            improving the efficiency** of the standard flush process. It is
+            **strongly recommended** to not use the bulk methods as they
+            represent a forking of SQLAlchemy's functionality and are slowly
+            being moved into legacy status.  New features such as
+            :ref:`orm_dml_returning_objects` are both more efficient than
+            the "bulk" methods and provide more predictable functionality.
+
             **Please read the list of caveats at**
             :ref:`bulk_operations_caveats` **before using this method, and
             fully test and confirm the functionality of all code developed
@@ -3512,7 +3523,9 @@ class Session(_SessionClassMethods):
          and other multi-table mappings to insert correctly without the need
          to provide primary key values ahead of time; however,
          :paramref:`.Session.bulk_save_objects.return_defaults` **greatly
-         reduces the performance gains** of the method overall.
+         reduces the performance gains** of the method overall.  It is strongly
+         advised to please use the standard :meth:`_orm.Session.add_all`
+         approach.
 
         :param update_changed_only: when True, UPDATE statements are rendered
          based on those attributes in each state that have logged changes.
@@ -3582,6 +3595,14 @@ class Session(_SessionClassMethods):
             and SQL clause support are **silently omitted** in favor of raw
             INSERT of records.
 
+            Please note that newer versions of SQLAlchemy are **greatly
+            improving the efficiency** of the standard flush process. It is
+            **strongly recommended** to not use the bulk methods as they
+            represent a forking of SQLAlchemy's functionality and are slowly
+            being moved into legacy status.  New features such as
+            :ref:`orm_dml_returning_objects` are both more efficient than
+            the "bulk" methods and provide more predictable functionality.
+
             **Please read the list of caveats at**
             :ref:`bulk_operations_caveats` **before using this method, and
             fully test and confirm the functionality of all code developed
@@ -3675,6 +3696,14 @@ class Session(_SessionClassMethods):
             and SQL clause support are **silently omitted** in favor of raw
             UPDATES of records.
 
+            Please note that newer versions of SQLAlchemy are **greatly
+            improving the efficiency** of the standard flush process. It is
+            **strongly recommended** to not use the bulk methods as they
+            represent a forking of SQLAlchemy's functionality and are slowly
+            being moved into legacy status.  New features such as
+            :ref:`orm_dml_returning_objects` are both more efficient than
+            the "bulk" methods and provide more predictable functionality.
+
             **Please read the list of caveats at**
             :ref:`bulk_operations_caveats` **before using this method, and
             fully test and confirm the functionality of all code developed