Added installation notes for cx_Oracle 5.x.
This commit is contained in:
Anthony Tuininga
parent
b03a6520d7
commit
9311ab9c4e
@ -14,6 +14,7 @@ Contents:
|
|||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
|
installation.rst
|
||||||
module.rst
|
module.rst
|
||||||
connection.rst
|
connection.rst
|
||||||
cursor.rst
|
cursor.rst
|
||||||
|
|||||||
130
doc/src/installation.rst
Normal file
130
doc/src/installation.rst
Normal file
@ -0,0 +1,130 @@
|
|||||||
|
.. _installation:
|
||||||
|
|
||||||
|
************************
|
||||||
|
cx_Oracle 5 Installation
|
||||||
|
************************
|
||||||
|
|
||||||
|
Overview
|
||||||
|
========
|
||||||
|
|
||||||
|
Before cx_Oracle can be installed, an installation of
|
||||||
|
`Python <https://www.python.org/downloads>`__ 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
|
||||||
|
<http://www.oracle.com/technetwork/database/features/instant-client/
|
||||||
|
index.html>`__. 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 <https://pypi.python.org/pypi/cx_Oracle/5.3>`__ 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
|
||||||
|
<https://github.com/oracle/python-cx_Oracle/blob/v5.x/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
|
||||||
|
<https://support.oracle.com/epmos/faces/DocumentDisplay?id=207303.1>`__.
|
||||||
|
|
||||||
|
Newer Oracle clients support new features, such as the `oraaccess.xml
|
||||||
|
<https://docs.oracle.com/database/122/LNOCI/
|
||||||
|
more-oci-advanced-topics.htm#LNOCI73052>`__ external configuration file
|
||||||
|
available with 12.1 or later clients, and `session pool enhancements
|
||||||
|
<http://docs.oracle.com/database/122/LNOCI/release-changes.htm#LNOCI005>`__
|
||||||
|
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 <https://brew.sh>`__ or `Python.org
|
||||||
|
<https://www.python.org/downloads>`__ 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 <https://www.microsoft.com/en-us/download/details.aspx?id=18471>`__ or `VS 2005 32-bit <https://www.microsoft.com/en-ca/download/details.aspx?id=3387>`__
|
||||||
|
- 12.1 : `VS 2010 <https://support.microsoft.com/en-us/kb/2977003#bookmark-vs2010>`__
|
||||||
|
- 12.2 : `VS 2013 <https://support.microsoft.com/en-us/kb/2977003#bookmark-vs2013>`__
|
||||||
|
|
||||||
|
- If you have both Python 2 and 3 installed, make sure you are
|
||||||
|
using the correct python and pip (or python3 and pip3)
|
||||||
|
executables.
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user