Document cx_Oracle version constraints. Fixes #172. [skip ci]

doc/db-specific-options.rst

@@ -176,20 +176,37 @@ client_flag
 load_infile
     int, non-zero enables LOAD LOCAL INFILE, zero disables
 
+.. _oracle-adapter-options:
+
 Oracle Adapter Options
 ======================
 
 The Oracle adapter accepts:
 
 driver
-        Other than "auto" the only supported value is "cx_Oracle".
+    Other than "auto" the only supported value is "cx_Oracle".
+
+    .. caution::
+        If you use cx_Oracle 5.2.1 or 5.3 (in general, any version >=
+        5.2 but < 6.0) you must be sure that it is compiled against a
+        version of the Oracle client that is compatible with the
+        Oracle database to which you will be connecting.
+
+        Specifically, if you will be connecting to Oracle database 11
+        or earlier, you must *not* compile against client version 12.
+        (Compiling against an older client and connecting to a newer
+        database is fine.) If you use a client that is too new,
+        RelStorage will fail to commit with the error ``DatabaseError:
+        ORA-03115: unsupported network datatype or representation``.
+
+        For more details, see :issue:`172`.
 
 user
-        The Oracle account name
+    The Oracle account name
 
 password
-        The Oracle account password
+    The Oracle account password
 
 dsn
-        The Oracle data source name.  The Oracle client library will
-        normally expect to find the DSN in ``/etc/oratab``.
+    The Oracle data source name.  The Oracle client library will
+    normally expect to find the DSN in ``/etc/oratab``.

doc/faq.rst

@@ -37,3 +37,9 @@ Q: Can RelStorage replace ZRS (Zope Replication Services)?
 Q: How do I set up an environment to run the RelStorage tests?
 
     A: See :doc:`developing`.
+
+Q: Why do I get ``DatabaseError: ORA-03115: unsupported network
+datatype or representation`` when using Oracle?
+
+    See the "driver" section of :ref:`oracle-adapter-options` for more
+    information.

doc/install.rst

@@ -38,8 +38,8 @@ database.
 
 
 On CPython2, install psycopg2 2.6.1+, mysqlclient 1.3.7+, or cx_Oracle
-5.2+; PyMySQL 0.7, MySQL Connector/Python 2.1.5 and umysql are also
-known to work as is pg8000.
+5.2+ (but use caution with 5.2.1+); PyMySQL 0.7, MySQL
+Connector/Python 2.1.5 and umysql are also known to work as is pg8000.
 
 For CPython3, install psycopg2, mysqlclient or cx_Oracle;
 PyMySQL, MySQL Connector/Python  and pg8000 are also known to work.
@@ -73,7 +73,7 @@ bold** are the recommended adapter.
 mysqlclient, MySQL Connector/Python (without its C extension), pg8000
 and umysql are compatible (cooperative) with gevent.
 
-For additional details, see the "driver" section for each database in
+For additional details and warnings, see the "driver" section for each database in
 :doc:`db-specific-options`.
 
 Memcache Integration

relstorage/adapters/oracle/locker.py

@@ -59,6 +59,8 @@ class OracleLocker(AbstractLocker):
 
         # Alternative:
         #cursor.execute("LOCK TABLE commit_lock IN EXCLUSIVE MODE")
+        # However, this is known to produce slower results. See
+        # https://groups.google.com/d/msg/zodb/IzQoClP5Hgc/8o28J4PkDQAJ
 
         if ensure_current:
             if self.keep_history: