added docs to case() illusrtating usage of `literal_column()`, can't implement #809 directly

1 files changed, 11 insertions, 1 deletions

diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 9324ed6a0..4b49dc0bc 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -437,7 +437,8 @@ def case(whens, value=None, else_=None):
     The expressions used for THEN and ELSE,
     when specified as strings, will be interpreted
     as bound values. To specify textual SQL expressions
-    for these, use the text(<string>) construct.
+    for these, use the literal_column(<string>) or 
+    text(<string>) construct. 
 
     The expressions used for the WHEN criterion
     may only be literal strings when "value" is
@@ -457,6 +458,15 @@ def case(whens, value=None, else_=None):
               'manager':  emp.c.salary * 3,
           })
 
+    Using ``literal_column()``, to allow for databases that
+    do not support bind parameters in the `then` clause.  The type
+    can be specified which determines the type of the `case()` construct
+    overall::
+    
+        case([(orderline.c.qty > 100, literal_column("'greaterthan100'", String)),
+              (orderline.c.qty > 10, literal_column("'greaterthan10'", String))
+            ], else_=literal_column("'lethan10'", String))
+
     """
     
     return _Case(whens, value=value, else_=else_)