- changelog, migration

2 files changed, 56 insertions, 0 deletions

diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst
index d118684d3..8de8487ce 100644
--- a/doc/build/changelog/changelog_09.rst
+++ b/doc/build/changelog/changelog_09.rst
@@ -15,6 +15,36 @@
     :version: 0.9.0b2
 
     .. change::
+        :tags: feature, sql
+        :pullreq: github:42
+
+        A new API for specifying the ``FOR UPDATE`` clause of a ``SELECT``
+        is added with the new :meth:`.SelectBase.with_for_update` method.
+        This method supports a more straightforward system of setting
+        dialect-specific options compared to the ``for_update`` keyword
+        argument of :func:`.select`, and also includes support for the
+        SQL standard ``FOR UPDATE OF`` clause.   The ORM also includes
+        a new corresponding method :meth:`.Query.with_for_update`.
+        Pull request courtesy Mario Lassnig.
+
+        .. seealso::
+
+            :ref:`feature_github_42`
+
+    .. change::
+        :tags: feature, orm
+        :pullreq: github:42
+
+        A new API for specifying the ``FOR UPDATE`` clause of a ``SELECT``
+        is added with the new :meth:`.Query.with_for_update` method,
+        to complement the new :meth:`.SelectBase.with_for_update` method.
+        Pull request courtesy Mario Lassnig.
+
+        .. seealso::
+
+            :ref:`feature_github_42`
+
+    .. change::
         :tags: bug, engine
         :tickets: 2873
 
diff --git a/doc/build/changelog/migration_09.rst b/doc/build/changelog/migration_09.rst
index e5e6e4612..cb1462b77 100644
--- a/doc/build/changelog/migration_09.rst
+++ b/doc/build/changelog/migration_09.rst
@@ -908,6 +908,32 @@ rendering::
 
 :ticket:`722`
 
+.. _feature_github_42:
+
+New FOR UPDATE support on ``select()``, ``Query()``
+---------------------------------------------------
+
+An attempt is made to simplify the specification of the ``FOR UPDATE``
+clause on ``SELECT`` statements made within Core and ORM, and support is added
+for the ``FOR UPDATE OF`` SQL supported by Postgresql and Oracle.
+
+Using the core :meth:`.SelectBase.with_for_update`, options like ``FOR SHARE`` and
+``NOWAIT`` can be specified individually, rather than linking to arbitrary
+string codes::
+
+    stmt = select([table]).with_for_update(read=True, nowait=True, of=table)
+
+On Posgtresql the above statement might render like::
+
+    SELECT table.a, table.b FROM table FOR SHARE OF table NOWAIT
+
+The :class:`.Query` object gains a similar method :meth:`.Query.with_for_update`
+which behaves in the same way.  This method supersedes the existing
+:meth:`.Query.with_lockmode` method, which translated ``FOR UPDATE`` clauses
+using a different system.   At the moment, the "lockmode" string argument is still
+accepted by the :meth:`.Session.refresh` method.
+
+
 .. _feature_2867:
 
 Floating Point String-Conversion Precision Configurable for Native Floating Point Types