From e6e1c02c96b077700187420019194989ea55a646 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 20 Apr 2018 13:31:45 -0400 Subject: [PATCH] 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 --- lib/sqlalchemy/dialects/oracle/cx_oracle.py | 31 +++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py index 9ae7101f85..1605c3a67b 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: -- 2.47.2