cx_Oracle: Error after setting NLS_LANG

I am working with a database containing Unicode data in NVARCHAR2 fields. Selecting rows that contain those fields just works with current cx_Oracle and SQLAlchemy as long as I don’t actually try to limit my result set by one of those in the query (like '%ü%'). I tried it with PL/SQL Developer and like unistr('%\00fc%') worked.

The SQLAlchemy documentation says that with cx_Oracle >= 5 everything should just work, but earlier versions needed NLS_LANG set in the environment. Unfortunately they do not tell you anywhere near that paragraph that SQLALchemy <= 0.5.x needs it too. It took me another hour to find that information here. So set NLS_LANG to something like this and go selecting:

export NLS_LANG='AMERICAN_AMERICA.UTF8'

There is one trap however. Do not set ‘AL32UTF8′! Reading Oracle docs lead me to believe ‘UTF8′ or ‘AL32UTF8′ were valid values for NLS_LANG. They are not (so it seems) and setting them caused my app to crash with the following when connecting (which is not a very helpful message, if you do have ORACLE_HOME set properly):

sqlalchemy.exc.InterfaceError: (InterfaceError) Unable to acquire Oracle environment handle None None

More about valid values here.