Document how to opt-out of NCHAR for cx_Oracle

Unfortunately, we need to bind Python unicode values as
NCHAR as in the case where non-ascii characters are present,
it's necessary.  We can't know in all cases how this value is being
used, so in those cases where Oracle will not accept NCHAR the
user should explicitly cast a value down to String.

Change-Id: I1a70739033435a7bf5effe2fa810ab064cea9188
Fixes: #4242

1 files changed, 31 insertions, 0 deletions

diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py
index 9ae7101f8..1605c3a67 100644
--- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py
+++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py
@@ -93,6 +93,37 @@ Python 2:
   The above approach will add significant latency to result-set fetches
   of plain string values.
 
+Sending String Values as Unicode or Non-Unicode
+------------------------------------------------
+
+As of SQLAlchemy 1.2.2, the cx_Oracle dialect unconditionally calls
+``setinputsizes()`` for bound values that are passed as Python unicode objects.
+In Python 3, all string values are Unicode; for cx_Oracle, this corresponds to
+``cx_Oracle.NCHAR`` being passed to ``setinputsizes()`` for that parameter.
+In some edge cases, such as passing format specifiers for
+the ``trunc()`` function, Oracle does not accept these as NCHAR::
+
+    from sqlalchemy import func
+
+    conn.execute(
+        func.trunc(func.sysdate(), 'dd')
+    )
+
+In these cases, an error as follows may be raised::
+
+    ORA-01899: bad precision specifier
+
+When this error is encountered, it may be necessary to pass the string value
+with an explicit non-unicode type::
+
+    from sqlalchemy import func
+    from sqlalchemy import literal
+    from sqlalchemy import String
+
+    conn.execute(
+        func.trunc(func.sysdate(), literal('dd', String))
+    )
+
 
 .. _cx_oracle_returning: