Merge pull request pallets-eco#829 from pallets/deprecate-commit-on-teardown

deprecate COMMIT_ON_TEARDOWN

Author: davidism

CHANGES.rst

@@ -1,10 +1,21 @@
+Version 2.4.3
+-------------
+
+Unreleased
+
+-   Deprecate ``SQLALCHEMY_COMMIT_ON_TEARDOWN`` as it can cause various
+    design issues that are difficult to debug. Call
+    ``db.session.commit()`` directly instead. :issue:`216`
+
+
 Version 2.4.2
 -------------
 
 Released 2020-05-25
 
 -   Fix bad pagination when records are de-duped. :pr:`812`
 
+
 Version 2.4.1
 -------------
 

docs/config.rst

@@ -98,15 +98,17 @@ A list of configuration keys currently understood by the extension:
    ``SQLALCHEMY_TRACK_MODIFICATIONS`` will warn if unset.
 
 .. versionchanged:: 2.4
+    * ``SQLALCHEMY_ENGINE_OPTIONS`` configuration key was added.
+    * Deprecated keys
 
-* ``SQLALCHEMY_ENGINE_OPTIONS`` configuration key was added.
-* Deprecated keys
+      * ``SQLALCHEMY_NATIVE_UNICODE``
+      * ``SQLALCHEMY_POOL_SIZE``
+      * ``SQLALCHEMY_POOL_TIMEOUT``
+      * ``SQLALCHEMY_POOL_RECYCLE``
+      * ``SQLALCHEMY_MAX_OVERFLOW``
 
-  * ``SQLALCHEMY_NATIVE_UNICODE``
-  * ``SQLALCHEMY_POOL_SIZE``
-  * ``SQLALCHEMY_POOL_TIMEOUT``
-  * ``SQLALCHEMY_POOL_RECYCLE``
-  * ``SQLALCHEMY_MAX_OVERFLOW``
+.. versionchanged:: 2.4.3
+    Deprecated ``SQLALCHEMY_COMMIT_ON_TEARDOWN``.
 
 
 Connection URI Format

flask_sqlalchemy/__init__.py

@@ -694,6 +694,10 @@ class to be used in place of :class:`Model`.
 
     .. versionchanged:: 2.4
        The `use_native_unicode` parameter was deprecated.
+
+    .. versionchanged:: 2.4.3
+        ``COMMIT_ON_TEARDOWN`` is deprecated and will be removed in
+        version 3.1. Call ``db.session.commit()`` directly instead.
     """
 
     #: Default query class used by :attr:`Model.query` and other queries.
@@ -843,6 +847,13 @@ def init_app(self, app):
         @app.teardown_appcontext
         def shutdown_session(response_or_exc):
             if app.config['SQLALCHEMY_COMMIT_ON_TEARDOWN']:
+                warnings.warn(
+                    "'COMMIT_ON_TEARDOWN' is deprecated and will be"
+                    " removed in version 3.1. Call"
+                    " 'db.session.commit()'` directly instead.",
+                    DeprecationWarning,
+                )
+
                 if response_or_exc is None:
                     self.session.commit()
 

tests/test_commit_on_teardown.py

@@ -22,12 +22,16 @@ def create():
 
 
 def test_commit_on_success(client):
-    resp = client.post('/create')
+    with pytest.warns(DeprecationWarning, match="COMMIT_ON_TEARDOWN"):
+        resp = client.post('/create')
+
     assert resp.status_code == 200
     assert client.get('/').data == b'Test one'
 
 
 def test_roll_back_on_failure(client):
-    resp = client.post('/create', data={'fail': 'on'})
+    with pytest.warns(DeprecationWarning, match="COMMIT_ON_TEARDOWN"):
+        resp = client.post('/create', data={'fail': 'on'})
+
     assert resp.status_code == 500
     assert client.get('/').data == b''