diff --git a/doc/src/index.rst b/doc/src/index.rst index 93ad9e1..c6e7b99 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -14,6 +14,7 @@ Contents: .. toctree:: :maxdepth: 2 + installation.rst module.rst connection.rst cursor.rst diff --git a/doc/src/installation.rst b/doc/src/installation.rst new file mode 100644 index 0000000..e7b8366 --- /dev/null +++ b/doc/src/installation.rst @@ -0,0 +1,130 @@ +.. _installation: + +************************ +cx_Oracle 5 Installation +************************ + +Overview +======== + +Before cx_Oracle can be installed, an installation of +`Python `__ is needed first. Python 2.7 and +Python 3.4 and higher are supported. + +You must also install an Oracle Client, if that has not been done already. +Oracle Client versions 12.2, 12.1 and 11.2 are supported. The simplest Oracle +Client is the free `Oracle Instant Client +`__. Only the "Basic" or "Basic Light" package is required at +run-time. If you plan to build cx_Oracle from source, you will also need the +"SDK" package. Oracle Client libraries and the SDK are also available in any +Oracle Database installation or full Oracle Client installation. + +Prebuilt binaries are available on +`PyPI `__ for Windows and Linux. +These can be downloaded and installed directly. + +If no prebuilt binaries are available for your platform or you prefer to build +from source you can download the source package from PyPI instead and run the +following commands: + + python setup.py build + python setup.py install + +You can also use pip, the generic tool for installing Python packages. It will +download the source, compile and install the module for you. The command to use +pip is the following: + + python -m pip install cx_Oracle==5.3 + +If you run into any difficulty building from source, the +`BUILD.txt +`__ file can +be consulted for hints on how to build. The `Troubleshooting`_ section below +may also be of help. On Linux, if cx_Oracle needs to be compiled for the +default python package, you will need the ``python-devel`` package or +equivalent, which provides the ``Python.h`` header file. + +Finally, you need an `Oracle Database`_ for Python to connect to. Oracle's +standard client-server version interoperability allows cx_Oracle to connect to +both older and newer databases. Python can be local or remote to the database. + + +Oracle Database +=============== + +Oracle Client libraries allow connection to older and newer databases. +In summary, Oracle Client 12.2 can connect to Oracle Database 11.2 or +greater. Oracle Client 12.1 can connect to Oracle Database 10.2 or +greater. Oracle Client 11.2 can connect to Oracle Database 9.2 or +greater. For additional information on which Oracle Database releases +are supported by which Oracle client versions, please see `Doc ID 207303.1 +`__. + +Newer Oracle clients support new features, such as the `oraaccess.xml +`__ external configuration file +available with 12.1 or later clients, and `session pool enhancements +`__ +to dead connection detection in 12.2 clients. + +The function :func:`~cx_Oracle.clientversion()` can be used to determine +which Oracle Client version is in use and the attribute +:attr:`Connection.version` can be used to determine which Oracle +Database version a connection is accessing. These can then be used to adjust +application behavior accordingly. Attempts to use some Oracle features that are +not supported by a particular client/server combination may result in runtime +errors. These include: + + - when attempting to access attributes that are not supported by the + current Oracle Client library you will get the error "ORA-24315: illegal + attribute type" + + - when attempting to use implicit results with Oracle Client 11.2 + against Oracle Database 12c you will get the error "ORA-29481: + Implicit results cannot be returned to client" + + - when attempting to get array DML row counts with Oracle Client + 11.2 you will get the error "DPI-1013: not supported" + + +Troubleshooting +=============== + +If installation fails: + + - Use option ``-v`` with pip. Review your output and logs. Try to install + using a different method. **Google anything that looks like an error.** + Try some potential solutions. + + - Was there a network connection error? Do you need to see the environment + variables ``http_proxy`` and/or ``https_proxy``? + + - Do you get the error "``No module named pip``"? The pip module is builtin + to Python from version 2.7.9 but is sometimes removed by the OS. Use the + venv module (builtin to Python 3.x) or virtualenv module (Python 2.x) + instead. + +If importing cx_Oracle fails: + + - Check the ``PATH`` environment variable on Windows. Ensure that you + have restarted your command prompt if you have modified environment + variables. + - Check the ``LD_LIBRARY_PATH`` environment variable on Linux. + - On macOS, make sure Oracle Instant Client is in `~/lib` or + `/usr/local/lib` and that you are not using the bundled Python (use + `Homebrew `__ or `Python.org + `__ instead). + - Check that Python, cx_Oracle and your Oracle Client libraries are all + 64-bit or all 32-bit. + - on Windows, check that the correct Windows redistributables have been + installed. + + - 11.2 : `VS 2005 64-bit `__ or `VS 2005 32-bit `__ + - 12.1 : `VS 2010 `__ + - 12.2 : `VS 2013 `__ + + - If you have both Python 2 and 3 installed, make sure you are + using the correct python and pip (or python3 and pip3) + executables. +