From: Mike Bayer Date: Wed, 2 Nov 2022 02:57:16 +0000 (-0400) Subject: scale back warnings for 1.4's bulk methods X-Git-Tag: rel_1_4_43~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e3df120d45f64561013aa2abeba9014fc8be3395;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git scale back warnings for 1.4's bulk methods since these methods have been improved for 2.0, the general idea is not going away, so remove the warnings indicating that these features are being removed. Change-Id: I2c436c2e7f9aeacc9e71c82af4016190314f04ca --- diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst index 09d1948e88..e6d4941f83 100644 --- a/doc/build/orm/persistence_techniques.rst +++ b/doc/build/orm/persistence_techniques.rst @@ -881,18 +881,27 @@ ORM extension. An example of use is at: :ref:`examples_sharding`. Bulk Operations =============== -.. deepalchemy:: Bulk operations are essentially lower-functionality versions +.. tip:: + + Bulk operations are essentially lower-functionality versions of the Unit of Work's facilities for emitting INSERT and UPDATE statements on primary key targeted rows. These routines were added to suit some cases where many rows being inserted or updated could be run into the - database without as much of the usual unit of work overhead, in that - most unit of work features are **disabled**. + database without as much of the usual unit of work overhead, by bypassing + a large portion of the functionality that the unit of work provides. + + SQLAlchemy 2.0 features new and improved bulk techniques with clarified + behavior, better integration with ORM objects as well as INSERT/UPDATE/DELETE + statements, and new capabilities. They additionally repair some long lived + performance issues that plagued both regular unit of work and "bulk" routines, + most notably in the area of INSERT operations. + + For these reasons, the previous bulk methods move into legacy status, which + is revised from the original plan that "bulk" features were to be deprecated + entirely. - There is **usually no need to use these routines, and they are not easy - to use as there are many missing behaviors that are usually expected when - using ORM objects**; for efficient - bulk inserts, it's better to use the Core :class:`_sql.Insert` construct - directly. Please read all caveats at :ref:`bulk_operations_caveats`. + When using the legacy 1.4 versions of these features, please read all + caveats at :ref:`bulk_operations_caveats`, as they are not always obvious. .. note:: Bulk INSERT and UPDATE should not be confused with the more common feature known as :ref:`orm_expression_update_delete`. This @@ -974,11 +983,13 @@ transaction, like any other:: s = Session() objects = [User(name="u1"), User(name="u2"), User(name="u3")] s.bulk_save_objects(objects) + s.commit() For :meth:`.Session.bulk_insert_mappings`, and :meth:`.Session.bulk_update_mappings`, dictionaries are passed:: s.bulk_insert_mappings(User, [dict(name="u1"), dict(name="u2"), dict(name="u3")]) + s.commit() .. seealso:: diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 79b723184d..ac02870d92 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -3595,23 +3595,19 @@ class Session(_SessionClassMethods): as an alternative newer mass-insert features such as :ref:`orm_dml_returning_objects`. - .. warning:: + .. legacy:: The bulk save feature allows for a lower-latency INSERT/UPDATE of rows at the expense of most other unit-of-work features. Features such as object management, relationship handling, - and SQL clause support are **silently omitted** in favor of raw + 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. + In SQLAlchemy 2.0, improved versions of the bulk insert/update + methods are introduced, with clearer behavior and + documentation, new capabilities, and much better performance. - **Please read the list of caveats at** + For 1.4 use, **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 using these systems.** @@ -3716,23 +3712,19 @@ class Session(_SessionClassMethods): .. versionadded:: 1.0.0 - .. warning:: + .. legacy:: The bulk insert feature allows for a lower-latency INSERT of rows at the expense of most other unit-of-work features. Features such as object management, relationship handling, - and SQL clause support are **silently omitted** in favor of raw + 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. + In SQLAlchemy 2.0, improved versions of the bulk insert/update + methods are introduced, with clearer behavior and + documentation, new capabilities, and much better performance. - **Please read the list of caveats at** + For 1.4 use, **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 using these systems.** @@ -3817,23 +3809,19 @@ class Session(_SessionClassMethods): .. versionadded:: 1.0.0 - .. warning:: + .. legacy:: The bulk update feature allows for a lower-latency UPDATE of rows at the expense of most other unit-of-work features. Features such as object management, relationship handling, - and SQL clause support are **silently omitted** in favor of raw + 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. + In SQLAlchemy 2.0, improved versions of the bulk insert/update + methods are introduced, with clearer behavior and + documentation, new capabilities, and much better performance. - **Please read the list of caveats at** + For 1.4 use, **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 using these systems.**