Various improvements to installation documentation.
This commit is contained in:
Anthony Tuininga
parent
65580226cd
commit
7e2663606d
@ -33,7 +33,7 @@ master_doc = 'index'
|
||||
|
||||
# General substitutions.
|
||||
project = 'cx_Oracle'
|
||||
copyright = u'2016, 2017, Oracle and/or its affiliates. All rights reserved. Portions Copyright © 2007-2015, Anthony Tuininga. All rights reserved. Portions Copyright © 2001-2007, Computronix (Canada) Ltd., Edmonton, Alberta, Canada. All rights reserved'
|
||||
copyright = u'2016, 2018, Oracle and/or its affiliates. All rights reserved. Portions Copyright © 2007-2015, Anthony Tuininga. All rights reserved. Portions Copyright © 2001-2007, Computronix (Canada) Ltd., Edmonton, Alberta, Canada. All rights reserved'
|
||||
author = 'Oracle'
|
||||
|
||||
# The default replacements for |version| and |release|, also used in various
|
||||
|
||||
@ -4,15 +4,15 @@
|
||||
cx_Oracle 6 Installation
|
||||
************************
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
To connect Python and Oracle Database you need:
|
||||
To use cx_Oracle 6 with Python and Oracle Database you need:
|
||||
|
||||
- Python 2.7 or 3.4 and higher.
|
||||
|
||||
- The cx_Oracle module, which is available on `PyPI
|
||||
<https://pypi.python.org/pypi/cx_Oracle>`__.
|
||||
- Python 2.7 or 3.4 and higher. Older versions of cx_Oracle may work
|
||||
with older versions of Python.
|
||||
|
||||
- Oracle client libraries. These can be from the free `Oracle Instant
|
||||
Client
|
||||
@ -26,20 +26,21 @@ To connect Python and Oracle Database you need:
|
||||
interoperability allows cx_Oracle to connect to both older and newer
|
||||
databases.
|
||||
|
||||
|
||||
Quick Start cx_Oracle Installation
|
||||
==================================
|
||||
|
||||
- An installation of `Python <https://www.python.org/downloads>`__ is
|
||||
needed. Python 2.7 and Python 3.4 and higher are supported.
|
||||
needed. Python 2.7 and Python 3.4 and higher are supported by cx_Oracle 6.
|
||||
|
||||
- Install cx_Oracle from `PyPI
|
||||
<https://pypi.python.org/pypi/cx_Oracle>`__ with::
|
||||
|
||||
python -m pip install cx_Oracle --upgrade
|
||||
|
||||
If a binary wheel package is not available for your platform, the
|
||||
source package will be downloaded, compiled, and the resulting
|
||||
binary installed.
|
||||
Note: if a binary wheel package is not available for your platform,
|
||||
the source package will be downloaded instead. This will be compiled
|
||||
and the resulting binary installed.
|
||||
|
||||
- Add Oracle 12.2, 12.1 or 11.2 client libraries to your operating
|
||||
system library search path such as ``PATH`` on Windows or
|
||||
@ -68,6 +69,18 @@ Quick Start cx_Oracle Installation
|
||||
10.2 or greater. Version 11.2 client libraries can connect to Oracle
|
||||
Database 9.2 or greater.
|
||||
|
||||
- After installation, your Python applications will be able to connect
|
||||
to your database. The database can be on the same machine as
|
||||
Python, or on a remote machine. cx_Oracle does not install or
|
||||
create a database.
|
||||
|
||||
You will need to know user credentials and the connection string for
|
||||
the database.
|
||||
|
||||
You can learn how to use cx_Oracle from the API documentation and
|
||||
`samples
|
||||
<https://github.com/oracle/python-cx_Oracle/blob/master/samples>`__.
|
||||
|
||||
If you run into trouble, check out the section on `Troubleshooting`_.
|
||||
|
||||
The database abstraction layer in cx_Oracle is `ODPI-C
|
||||
@ -77,45 +90,406 @@ installation instructions
|
||||
to review.
|
||||
|
||||
|
||||
Upgrading from cx_Oracle 5
|
||||
==========================
|
||||
Oracle Client and Oracle Database Interoperability
|
||||
==================================================
|
||||
|
||||
If you are upgrading from cx_Oracle 5 note these installation changes:
|
||||
cx_Oracle requires Oracle Client libraries. The libraries provide the
|
||||
necessary network connectivity to access an Oracle Database instance.
|
||||
They also provide basic and advanced connection management and data
|
||||
features to cx_Oracle.
|
||||
|
||||
- When using Oracle Instant Client, you should not set ``ORACLE_HOME``.
|
||||
The simplest way to get Oracle Client libraries is to install the free
|
||||
`Oracle Instant Client
|
||||
<http://www.oracle.com/technetwork/database/features/instant-client/
|
||||
index.html>`__ "Basic" or "Basic Light" package. The libraries are
|
||||
also available in any Oracle Database installation or full Oracle
|
||||
Client installation.
|
||||
|
||||
- On Linux, cx_Oracle 6 no longer uses Instant Client RPMs automatically.
|
||||
You must set ``LD_LIBRARY_PATH`` or use ``ldconfig`` to locate the Oracle
|
||||
client library.
|
||||
Oracle's standard client-server network interoperability allows
|
||||
connections between different versions of Oracle Client libraries and
|
||||
Oracle Database. For certified configurations see Oracle Support's
|
||||
`Doc ID 207303.1
|
||||
<https://support.oracle.com/epmos/faces/DocumentDisplay?id=207303.1>`__.
|
||||
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. The technical restrictions on creating connections may be
|
||||
more flexible. For example Oracle Client 12.2 can successfully
|
||||
connect to Oracle Database 10.2.
|
||||
|
||||
- PyPI no longer allows Windows installers or Linux RPMs to be
|
||||
hosted. Use the supplied cx_Oracle Wheels instead.
|
||||
cx_Oracle uses the shared library loading mechanism available on each
|
||||
supported platform to load the Oracle Client libraries at runtime. It
|
||||
does not need to be rebuilt for different versions of the libraries.
|
||||
Since a single cx_Oracle binary can use different client versions and
|
||||
also access multiple database versions, it is important your
|
||||
application is tested in your intended release environments. 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.
|
||||
|
||||
Install Using Pip
|
||||
=================
|
||||
The cx_Oracle 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:
|
||||
|
||||
Pip is the generic tool for installing Python packages. If you do not have pip,
|
||||
see the `pip installation documentation
|
||||
<http://pip.readthedocs.io/en/latest/installing/>`__.
|
||||
- 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"
|
||||
|
||||
The command to install cx_Oracle 6 using pip on all platforms is::
|
||||
- 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"
|
||||
|
||||
|
||||
Installing cx_Oracle on Linux
|
||||
=============================
|
||||
|
||||
Install cx_Oracle
|
||||
-----------------
|
||||
|
||||
Use Python's `Pip <http://pip.readthedocs.io/en/latest/installing/>`__
|
||||
package to install cx_Oracle from `PyPI
|
||||
<https://pypi.python.org/pypi/cx_Oracle>`__::
|
||||
|
||||
python -m pip install cx_Oracle --upgrade
|
||||
|
||||
This will download and install a pre-compiled binary matching your platform
|
||||
and architecture automatically, if one is available. Pre-compiled binaries are
|
||||
available for Windows and Linux. See
|
||||
`PyPI <https://pypi.python.org/pypi/cx_Oracle>`__.
|
||||
This will download and install a pre-compiled binary `if one is
|
||||
available <https://pypi.python.org/pypi/cx_Oracle>`__ for your
|
||||
architecture. If a pre-compiled binary is not available, the source
|
||||
will be downloaded, compiled, and the resulting binary installed. If
|
||||
you are using the default python package, you will need the
|
||||
``python-devel`` package or equivalent, which provides the `Python.h`
|
||||
header file.
|
||||
|
||||
If a pre-compiled binary is not available, the source will be
|
||||
downloaded, compiled, and the resulting binary installed. 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.
|
||||
Install Oracle Client
|
||||
---------------------
|
||||
|
||||
On macOS make sure you are not using the bundled Python - use `Homebrew
|
||||
<https://brew.sh>`__ or `Python.org <https://www.python.org/downloads>`__
|
||||
instead.
|
||||
Using cx_Oracle requires Oracle Client libraries to be installed.
|
||||
These provide the necessary network connectivity allowing cx_Oracle
|
||||
to access an Oracle Database instance. Oracle Client versions 12.2,
|
||||
12.1 and 11.2 are supported.
|
||||
|
||||
- If your database is remote, then download the free `Oracle
|
||||
Instant Client
|
||||
<http://www.oracle.com/technetwork/database/features/instant-client/
|
||||
index.html>`__ "Basic" or "Basic Light" package for your
|
||||
operating system architecture. Use the RPM or ZIP packages,
|
||||
based on your preferences.
|
||||
|
||||
- Alternatively use the client libraries already available in a
|
||||
locally installed database such as the free `Oracle XE
|
||||
<http://www.oracle.com/technetwork/database/database-technologies/express-edition/overview/index.html>`__
|
||||
release.
|
||||
|
||||
Oracle Instant Client Zip Files
|
||||
+++++++++++++++++++++++++++++++
|
||||
|
||||
To use cx_Oracle with Oracle Instant Client zip files:
|
||||
|
||||
1. Download an Oracle 11.2, 12.1 or 12.2 "Basic" or "Basic Light" zip file: `64-bit
|
||||
<http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html>`__
|
||||
or `32-bit
|
||||
<http://www.oracle.com/technetwork/topics/linuxsoft-082809.html>`__, matching your
|
||||
Python architecture.
|
||||
|
||||
2. Unzip the package into a single directory that is accessible to your
|
||||
application. For example::
|
||||
|
||||
mkdir -p /opt/oracle
|
||||
cd /opt/oracle
|
||||
unzip instantclient-basic-linux.x64-12.2.0.1.0.zip
|
||||
|
||||
3. Install the ``libaio`` package with sudo or as the root user. For example::
|
||||
|
||||
sudo yum install libaio
|
||||
|
||||
On some Linux distributions this package is called ``libaio1`` instead.
|
||||
|
||||
4. If there is no other Oracle software on the machine that will be
|
||||
impacted, permanently add Instant Client to the runtime link
|
||||
path. For example, with sudo or as the root user::
|
||||
|
||||
sudo sh -c "echo /opt/oracle/instantclient_12_2 > /etc/ld.so.conf.d/oracle-instantclient.conf"
|
||||
sudo ldconfig
|
||||
|
||||
Alternatively, set the environment variable ``LD_LIBRARY_PATH`` to
|
||||
the appropriate directory for the Instant Client version. For
|
||||
example::
|
||||
|
||||
export LD_LIBRARY_PATH=/opt/oracle/instantclient_12_2:$LD_LIBRARY_PATH
|
||||
|
||||
5. If you intend to co-locate optional Oracle configuration files such
|
||||
as ``tnsnames.ora``, ``sqlnet.ora`` or ``oraaccess.xml`` with
|
||||
Instant Client, then create a ``network/admin`` subdirectory. For
|
||||
example::
|
||||
|
||||
mkdir -p /opt/oracle/instantclient_12_2/network/admin
|
||||
|
||||
This is the default Oracle configuration directory for executables
|
||||
linked with this Instant Client.
|
||||
|
||||
Alternatively, Oracle configuration files can be put in another,
|
||||
accessible directory. Then set the environment variable
|
||||
``TNS_ADMIN`` to that directory name.
|
||||
|
||||
Oracle Instant Client RPMs
|
||||
++++++++++++++++++++++++++
|
||||
|
||||
To use cx_Oracle with Oracle Instant Client RPMs:
|
||||
|
||||
1. Download an Oracle 11.2, 12.1 or 12.2 "Basic" or "Basic Light" RPM: `64-bit
|
||||
<http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html>`__
|
||||
or `32-bit
|
||||
<http://www.oracle.com/technetwork/topics/linuxsoft-082809.html>`__, matching your
|
||||
Python architecture.
|
||||
|
||||
2. Install the downloaded RPM with sudo or as the root user. For example::
|
||||
|
||||
sudo yum install oracle-instantclient12.2-basic-12.2.0.1.0-1.x86_64.rpm
|
||||
|
||||
Yum will automatically install required dependencies, such as ``libaio``.
|
||||
|
||||
3. If there is no other Oracle software on the machine that will be
|
||||
impacted, permanently add Instant Client to the runtime link
|
||||
path. For example, with sudo or as the root user::
|
||||
|
||||
sudo sh -c "echo /usr/lib/oracle/12.2/client64/lib > /etc/ld.so.conf.d/oracle-instantclient.conf"
|
||||
sudo ldconfig
|
||||
|
||||
Alternatively, set the environment variable ``LD_LIBRARY_PATH`` to
|
||||
the appropriate directory for the Instant Client version. For
|
||||
example::
|
||||
|
||||
export LD_LIBRARY_PATH=/usr/lib/oracle/12.2/client64/lib:$LD_LIBRARY_PATH
|
||||
|
||||
4. If you intend to co-locate optional Oracle configuration files such
|
||||
as ``tnsnames.ora``, ``sqlnet.ora`` or ``oraaccess.xml`` with
|
||||
Instant Client, then create a ``network/admin`` subdirectory under
|
||||
``lib/``. For example::
|
||||
|
||||
sudo mkdir -p /usr/lib/oracle/12.2/client64/lib/network/admin
|
||||
|
||||
This is the default Oracle configuration directory for executables
|
||||
linked with this Instant Client.
|
||||
|
||||
Alternatively, Oracle configuration files can be put in another,
|
||||
accessible directory. Then set the environment variable
|
||||
``TNS_ADMIN`` to that directory name.
|
||||
|
||||
Local Database or Full Oracle Client
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
|
||||
cx_Oracle applications can use Oracle Client 11.2, 12.1 or 12.2 libraries
|
||||
from a local Oracle Database or full Oracle Client installation.
|
||||
|
||||
The libraries must be either 32-bit or 64-bit, matching your
|
||||
Python architecture.
|
||||
|
||||
1. Set required Oracle environment variables by running the Oracle environment
|
||||
script. For example::
|
||||
|
||||
source /usr/local/bin/oraenv
|
||||
|
||||
For Oracle Database XE, run::
|
||||
|
||||
source /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh
|
||||
|
||||
2. Optional Oracle configuration files such as ``tnsnames.ora``,
|
||||
``sqlnet.ora`` or ``oraaccess.xml`` can be placed in
|
||||
``$ORACLE_HOME/network/admin``.
|
||||
|
||||
Alternatively, Oracle configuration files can be put in another,
|
||||
accessible directory. Then set the environment variable
|
||||
``TNS_ADMIN`` to that directory name.
|
||||
|
||||
|
||||
Installing cx_Oracle on Windows
|
||||
===============================
|
||||
|
||||
Install cx_Oracle
|
||||
-----------------
|
||||
|
||||
Use Python's `Pip <http://pip.readthedocs.io/en/latest/installing/>`__
|
||||
package to install cx_Oracle from `PyPI
|
||||
<https://pypi.python.org/pypi/cx_Oracle>`__::
|
||||
|
||||
python -m pip install cx_Oracle --upgrade
|
||||
|
||||
This will download and install a pre-compiled binary `if one is
|
||||
available <https://pypi.python.org/pypi/cx_Oracle>`__ for your
|
||||
architecture. If a pre-compiled binary is not available, the source
|
||||
will be downloaded, compiled, and the resulting binary installed.
|
||||
|
||||
Install Oracle Client
|
||||
---------------------
|
||||
|
||||
Using cx_Oracle requires Oracle Client libraries to be installed.
|
||||
These provide the necessary network connectivity allowing cx_Oracle
|
||||
to access an Oracle Database instance. Oracle Client versions 12.2,
|
||||
12.1 and 11.2 are supported.
|
||||
|
||||
- If your database is remote, then download the free `Oracle
|
||||
Instant Client
|
||||
<http://www.oracle.com/technetwork/database/features/instant-client/
|
||||
index.html>`__ "Basic" or "Basic Light" package for your
|
||||
operating system architecture.
|
||||
|
||||
- Alternatively use the client libraries already available in a
|
||||
locally installed database such as the free `Oracle XE
|
||||
<http://www.oracle.com/technetwork/database/database-technologies/express-edition/overview/index.html>`__
|
||||
release.
|
||||
|
||||
|
||||
Oracle Instant Client Zip Files
|
||||
+++++++++++++++++++++++++++++++
|
||||
|
||||
To use cx_Oracle with Oracle Instant Client zip files:
|
||||
|
||||
1. Download an Oracle 11.2, 12.1 or 12.2 "Basic" or "Basic Light" zip
|
||||
file: `64-bit
|
||||
<http://www.oracle.com/technetwork/topics/winx64soft-089540.html>`__
|
||||
or `32-bit
|
||||
<http://www.oracle.com/technetwork/topics/winsoft-085727.html>`__, matching your
|
||||
Python architecture.
|
||||
|
||||
2. Unzip the package into a single directory that is accessible to your
|
||||
application, for example ``C:\oracle\instantclient_12_2``.
|
||||
|
||||
3. Set the environment variable ``PATH`` to include the path that you
|
||||
created in step 2. For example, on Windows 7, update ``PATH`` in
|
||||
Control Panel -> System -> Advanced System Settings -> Advanced ->
|
||||
Environment Variables -> System Variables -> PATH.
|
||||
|
||||
Restart any open command prompt windows.
|
||||
|
||||
4. If you intend to co-locate optional Oracle configuration files such
|
||||
as ``tnsnames.ora``, ``sqlnet.ora`` or ``oraaccess.xml`` with
|
||||
Instant Client, then create a ``network\admin`` subdirectory, for example
|
||||
``C:\oracle\instantclient_12_2\network\admin``.
|
||||
|
||||
This is the default Oracle configuration directory for executables
|
||||
linked with this Instant Client.
|
||||
|
||||
Alternatively, Oracle configuration files can be put in another,
|
||||
accessible directory. Then set the environment variable
|
||||
``TNS_ADMIN`` to that directory name.
|
||||
|
||||
5. Oracle Instant Client libraries require the presence of the correct
|
||||
Visual Studio redistributable.
|
||||
|
||||
- 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>`__
|
||||
|
||||
Local Database or Full Oracle Client
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
|
||||
cx_Oracle applications can use Oracle Client 11.2, 12.1 or 12.2
|
||||
libraries libraries from a local Oracle Database or full Oracle
|
||||
Client.
|
||||
|
||||
The Oracle libraries must be either 32-bit or 64-bit, matching your
|
||||
Python architecture.
|
||||
|
||||
1. Set the environment variable ``PATH`` to include the path that
|
||||
contains OCI.dll, if it is not already set. For example, on Windows
|
||||
7, update ``PATH`` in Control Panel -> System -> Advanced System
|
||||
Settings -> Advanced -> Environment Variables -> System Variables
|
||||
-> PATH.
|
||||
|
||||
Restart any open command prompt windows.
|
||||
|
||||
2. Optional Oracle configuration files such as ``tnsnames.ora``,
|
||||
``sqlnet.ora`` or ``oraaccess.xml`` can be placed in the
|
||||
``network/admin`` subdirectory of the Oracle Database software
|
||||
installation.
|
||||
|
||||
Alternatively, Oracle configuration files can be put in another,
|
||||
accessible directory. Then set the environment variable
|
||||
``TNS_ADMIN`` to that directory name.
|
||||
|
||||
|
||||
Installing cx_Oracle on macOS
|
||||
=============================
|
||||
|
||||
Make sure you are not using the bundled Python. This has restricted
|
||||
entitlements and will fail to load Oracle client libraries. Instead
|
||||
use `Homebrew <https://brew.sh>`__ or `Python.org
|
||||
<https://www.python.org/downloads>`__.
|
||||
|
||||
Install cx_Oracle
|
||||
-----------------
|
||||
|
||||
Use Python's `Pip <http://pip.readthedocs.io/en/latest/installing/>`__
|
||||
package to install cx_Oracle from `PyPI
|
||||
<https://pypi.python.org/pypi/cx_Oracle>`__::
|
||||
|
||||
python -m pip install cx_Oracle --upgrade
|
||||
|
||||
The source will be downloaded, compiled, and the resulting binary
|
||||
installed.
|
||||
|
||||
|
||||
Install Oracle Instant Client
|
||||
-----------------------------
|
||||
|
||||
cx_Oracle requires Oracle Client libraries, which are found in Oracle
|
||||
Instant Client for macOS. These provide the necessary network
|
||||
connectivity allowing cx_Oracle to access an Oracle Database
|
||||
instance. Oracle Client versions 12.2, 12.1 and 11.2 are supported.
|
||||
|
||||
To use cx_Oracle with Oracle Instant Client zip files:
|
||||
|
||||
1. Download the 11.2, 12.1 or 12.2 "Basic" or "Basic Light" zip file from `here
|
||||
<http://www.oracle.com/technetwork/topics/intel-macsoft-096467.html>`__.
|
||||
Choose either a 64-bit or 32-bit package, matching your
|
||||
Python architecture.
|
||||
|
||||
2. Unzip the package into a single directory that is accessible to your
|
||||
application. For example::
|
||||
|
||||
mkdir -p /opt/oracle
|
||||
unzip instantclient-basic-macos.x64-12.2.0.1.0.zip
|
||||
|
||||
3. Add links to ``$HOME/lib`` or ``/usr/local/lib`` to enable
|
||||
applications to find the library. For example::
|
||||
|
||||
mkdir ~/lib
|
||||
ln -s /opt/oracle/instantclient_12_2/libclntsh.dylib.12.1 ~/lib/
|
||||
|
||||
Alternatively, copy the required OCI libraries. For example::
|
||||
|
||||
mkdir ~/lib
|
||||
cp /opt/oracle/instantclient_12_2/{libclntsh.dylib.12.1,libclntshcore.dylib.12.1,libons.dylib,libnnz12.dylib,libociei.dylib} ~/lib/
|
||||
|
||||
For Instant Client 11.2, the OCI libraries must be copied. For example::
|
||||
|
||||
mkdir ~/lib
|
||||
cp /opt/oracle/instantclient_11_2/{libclntsh.dylib.11.1,libnnz11.dylib,libociei.dylib} ~/lib/
|
||||
|
||||
4. If you intend to co-locate optional Oracle configuration files such
|
||||
as ``tnsnames.ora``, ``sqlnet.ora`` or ``oraaccess.xml`` with
|
||||
Instant Client, then create a ``network/admin`` subdirectory. For
|
||||
example::
|
||||
|
||||
mkdir -p /opt/oracle/instantclient_12_2/network/admin
|
||||
|
||||
This is the default Oracle configuration directory for executables
|
||||
linked with this Instant Client.
|
||||
|
||||
Alternatively, Oracle configuration files can be put in another,
|
||||
accessible directory. Then set the environment variable
|
||||
``TNS_ADMIN`` to that directory name.
|
||||
|
||||
|
||||
Install Using GitHub
|
||||
@ -145,80 +519,19 @@ which the following commands should be run::
|
||||
python setup.py build
|
||||
python setup.py install
|
||||
|
||||
Upgrading from cx_Oracle 5
|
||||
==========================
|
||||
|
||||
Install Oracle Client
|
||||
=====================
|
||||
If you are upgrading from cx_Oracle 5 note these installation changes:
|
||||
|
||||
Using cx_Oracle requires Oracle Client libraries to be installed. The libraries
|
||||
provide the necessary network connectivity allowing applications to access an
|
||||
Oracle Database instance. They also provide basic and advanced connection
|
||||
management and data features to cx_Oracle. cx_Oracle uses the shared library
|
||||
loading mechanism available on each supported platform to load the Oracle
|
||||
Client library at runtime. Oracle Client versions 12.2, 12.1 and 11.2 are
|
||||
supported.
|
||||
- When using Oracle Instant Client, you should not set ``ORACLE_HOME``.
|
||||
|
||||
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. Oracle
|
||||
Client libraries are also available in any Oracle Database installation or
|
||||
full Oracle Client installation.
|
||||
|
||||
Make sure your library loading path, such as ``PATH`` on Windows, or
|
||||
``LD_LIBRARY_PATH`` on Linux, is set to the location of the Oracle
|
||||
Client libraries. On macOS the libraries should be in ``~/lib`` or
|
||||
``/usr/local/lib``.
|
||||
|
||||
On Windows, `Microsoft Windows Redistributables
|
||||
<https://oracle.github.io/odpi/doc/installation.html#windows>`__
|
||||
matching the version of the Oracle client libraries need to be
|
||||
installed.
|
||||
|
||||
See `ODPI-C installation instructions
|
||||
<https://oracle.github.io/odpi/doc/installation.html>`__ for details
|
||||
on configuration.
|
||||
|
||||
Oracle Database
|
||||
===============
|
||||
|
||||
Oracle's standard client-server network interoperability allows
|
||||
connections between different versions of Oracle Client and Oracle
|
||||
Database. For certified configurations see Oracle Support's `Doc ID
|
||||
207303.1 <https://support.oracle.com/epmos/faces/DocumentDisplay?id=207303.1>`__.
|
||||
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. The technical restrictions on creating connections may be more
|
||||
flexible. For example Oracle Client 12.2 can successfully connect to Oracle
|
||||
Database 10.2.
|
||||
|
||||
Since a single cx_Oracle binary can use multiple client versions and access
|
||||
multiple database versions, it is important your application is tested in your
|
||||
intended release environments. 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"
|
||||
- On Linux, cx_Oracle 6 no longer uses Instant Client RPMs automatically.
|
||||
You must set ``LD_LIBRARY_PATH`` or use ``ldconfig`` to locate the Oracle
|
||||
client library.
|
||||
|
||||
- PyPI no longer allows Windows installers or Linux RPMs to be
|
||||
hosted. Use the supplied cx_Oracle Wheels instead.
|
||||
|
||||
Installing cx_Oracle 5.3
|
||||
========================
|
||||
|
||||
@ -8,7 +8,7 @@ License
|
||||
|
||||
.. centered:: **LICENSE AGREEMENT FOR CX_ORACLE**
|
||||
|
||||
Copyright |copy| 2016-2017, Oracle and/or its affiliates. All rights reserved.
|
||||
Copyright |copy| 2016-2018, Oracle and/or its affiliates. All rights reserved.
|
||||
|
||||
Copyright |copy| 2007-2015, Anthony Tuininga. All rights reserved.
|
||||
|
||||
|
||||
@ -1,24 +1,29 @@
|
||||
This directory contains samples for cx_Oracle.
|
||||
|
||||
The schemas and SQL objects that are referenced in the samples can be
|
||||
created by running the SQL script
|
||||
[sql/SetupSamples.sql][1]. The
|
||||
syntax is:
|
||||
1. The schemas and SQL objects that are referenced in the samples can be
|
||||
created by running the SQL script
|
||||
[sql/SetupSamples.sql][1]. The
|
||||
syntax is:
|
||||
|
||||
sqlplus / as sysdba @sql/SetupSamples.sql
|
||||
sqlplus / as sysdba @sql/SetupSamples.sql
|
||||
|
||||
The script will create users pythondemo and pythoneditions and will create an
|
||||
edition called python_e1. If you wish to change the names of the users or the
|
||||
name of the edition you can edit the file [sql/SampleEnv.sql][2]. You will also
|
||||
need to edit the file [SampleEnv.py][4] or set environment variables as documented
|
||||
in it.
|
||||
The script will create users `pythondemo` and `pythoneditions` and
|
||||
will create an edition called `python_e1`.
|
||||
|
||||
After running the samples, the schemas and SQL objects can be dropped by
|
||||
running the SQL script [sql/DropSamples.sql][3]. The syntax is
|
||||
If you wish to change the names of the users or the name of the
|
||||
edition you can edit the file [sql/SampleEnv.sql][2]. You will also
|
||||
need to edit the file [SampleEnv.py][4] or set environment variables
|
||||
as documented in it.
|
||||
|
||||
sqlplus / as sysdba @sql/DropSamples.sql
|
||||
2. Run a Python script, for example:
|
||||
|
||||
python Query.py
|
||||
|
||||
3. After running cx_Oracle samples, the schemas and SQL objects can be
|
||||
dropped by running the SQL script [sql/DropSamples.sql][3]. The
|
||||
syntax is
|
||||
|
||||
sqlplus / as sysdba @sql/DropSamples.sql
|
||||
|
||||
[1]: https://github.com/oracle/python-cx_Oracle/blob/master/samples/sql/SetupSamples.sql
|
||||
[2]: https://github.com/oracle/python-cx_Oracle/blob/master/samples/sql/SampleEnv.sql
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user