- [feature] Added new for_update/with_lockmode()

options for Postgresql: for_update="read"/
with_lockmode("read"),
for_update="read_nowait"/
with_lockmode("read_nowait").
These emit "FOR SHARE" and "FOR SHARE NOWAIT",
respectively.  Courtesy Diana Clarke
[ticket:2445]

3 files changed, 26 insertions, 7 deletions

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index e87c0426e..c31c23885 100644
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -675,6 +675,10 @@ class PGCompiler(compiler.SQLCompiler):
     def for_update_clause(self, select):
         if select.for_update == 'nowait':
             return " FOR UPDATE NOWAIT"
+        elif select.for_update == 'read':
+            return " FOR SHARE"
+        elif select.for_update == 'read_nowait':
+            return " FOR SHARE NOWAIT"
         else:
             return super(PGCompiler, self).for_update_clause(select)
 
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 56d377f18..66d7f6eb4 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1105,10 +1105,17 @@ class Query(object):
             ``FOR UPDATE`` (standard SQL, supported by most dialects)
 
             ``'update_nowait'`` - passes ``for_update='nowait'``, which
-            translates to ``FOR UPDATE NOWAIT`` (supported by Oracle)
+            translates to ``FOR UPDATE NOWAIT`` (supported by Oracle, 
+            PostgreSQL)
 
             ``'read'`` - passes ``for_update='read'``, which translates to
-            ``LOCK IN SHARE MODE`` (supported by MySQL).
+            ``LOCK IN SHARE MODE`` (for MySQL), and ``FOR SHARE`` (for 
+            PostgreSQL)
+
+            ``'read_nowait'`` - passes ``for_update='read_nowait'``, which 
+            translates to ``FOR SHARE NOWAIT`` (supported by PostgreSQL).
+            
+            New in 0.7.7: ``FOR SHARE`` and ``FOR SHARE NOWAIT`` (PostgreSQL)
         """
 
         self._lockmode = mode
@@ -2837,6 +2844,7 @@ class Query(object):
         if self._lockmode:
             try:
                 for_update = {'read': 'read',
+                              'read_nowait': 'read_nowait',
                               'update': True,
                               'update_nowait': 'nowait',
                               None: False}[self._lockmode]
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 6e16d01f8..f37faa801 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -244,11 +244,18 @@ def select(columns=None, whereclause=None, from_obj=[], **kwargs):
 
     :param for_update=False:
       when ``True``, applies ``FOR UPDATE`` to the end of the
-      resulting statement.  Certain database dialects also support
-      alternate values for this parameter, for example mysql
-      supports "read" which translates to ``LOCK IN SHARE MODE``,
-      and oracle supports "nowait" which translates to ``FOR UPDATE
-      NOWAIT``.
+      resulting statement.  
+      
+      Certain database dialects also support
+      alternate values for this parameter:
+      
+      * With the MySQL dialect, the value ``"read"`` translates to 
+        ``LOCK IN SHARE MODE``.
+      * With the Oracle and Postgresql dialects, the value ``"nowait"``
+        translates to ``FOR UPDATE NOWAIT``.
+      * With the Postgresql dialect, the values "read" and ``"read_nowait"``
+        translate to ``FOR SHARE`` and ``FOR SHARE NOWAIT``, respectively
+        (new in 0.7.7).
 
     :param group_by:
       a list of :class:`.ClauseElement` objects which will comprise the