Preparing to release cx_Oracle 6.0.
This commit is contained in:
Anthony Tuininga
parent
f1f5ead2a4
commit
b30e66fa8a
89
README.md
89
README.md
|
|
@ -4,35 +4,41 @@ cx_Oracle is a Python extension module that enables access to Oracle Database.
|
|||
It conforms to the [Python database API 2.0 specification][1] with a
|
||||
considerable number of additions and a couple of exclusions.
|
||||
|
||||
cx_Oracle is licensed under a [BSD license] which you can find [here][3].
|
||||
cx_Oracle is licensed under a BSD license which you can find [here][3].
|
||||
|
||||
cx_Oracle 6 has been tested with Python version 2.7, and with versions 3.4 and
|
||||
higher. You can use cx_Oracle with Oracle 11.2, 12.1 and 12.2 client libraries,
|
||||
allowing connection to multiple Oracle Database versions. Oracle's standard
|
||||
client-server version interoperability allows connection to both older and
|
||||
newer databases, for example Oracle 12.2 client libraries can connect to Oracle
|
||||
cx_Oracle 6 has been tested with Python version 2.7, and with versions
|
||||
3.4 and higher. You can use cx_Oracle with Oracle 11.2, 12.1 and 12.2
|
||||
client libraries. Oracle's standard client-server version
|
||||
interoperability allows connection to both older and newer databases,
|
||||
for example Oracle 12.2 client libraries can connect to Oracle
|
||||
Database 11.2 or later.
|
||||
|
||||
## Documentation
|
||||
|
||||
See the [cx_Oracle Documentation][2] and [Release Notes][14].
|
||||
|
||||
## Help
|
||||
|
||||
Issues and questions can be raised with the cx_Oracle community on
|
||||
[GitHub][9] or on the [mailing list][5].
|
||||
|
||||
## Documentation
|
||||
|
||||
See the [cx_Oracle Documentation][2] and [Release Notes][14].
|
||||
|
||||
## Installation
|
||||
|
||||
See [cx_Oracle Installation][15] for detailed instructions.
|
||||
|
||||
- The simplest way to install cx_Oracle 6 RC2 is with pip:
|
||||
- The simplest way to install cx_Oracle 6 is with pip:
|
||||
|
||||
`python -m pip install cx_Oracle --pre`
|
||||
```
|
||||
python -m pip install cx_Oracle --upgrade
|
||||
```
|
||||
|
||||
If a binary wheel package is not available on [PyPI][6] for your platform, the
|
||||
source package will be used.
|
||||
|
||||
Note that if you download a source zip file directly from GitHub
|
||||
that you will also need to download an [ODPI-C][10] source zip file
|
||||
and extract it inside the directory called "odpi".
|
||||
|
||||
- After cx_Oracle is installed, Oracle client libraries must also be installed
|
||||
and configured. These can be from Oracle Instant Client, from a local Oracle
|
||||
Database, or from a full Oracle Client installation.
|
||||
|
|
@ -42,44 +48,40 @@ See [cx_Oracle Installation][15] for detailed instructions.
|
|||
platform-specific library path loading environment. See
|
||||
the [installation notes for ODPI-C][13] for help.
|
||||
|
||||
Versions 11.2, 12.1 and 12.2 of the Oracle Client libraries on Linux,
|
||||
Windows and macOS are supported. Users have also reported success
|
||||
with other platforms.
|
||||
Versions 11.2, 12.1 and 12.2 of the Oracle Client libraries on Linux,
|
||||
Windows and macOS are supported. Users have also reported success
|
||||
with other platforms.
|
||||
|
||||
Note that if you download a source zip file directly from GitHub that
|
||||
you will also need to download an [ODPI-C][10] source zip file and
|
||||
extract it inside the directory called "odpi".
|
||||
If you require cx_Oracle 5.3, download a Windows installer from
|
||||
[PyPI][16] or use `python -m pip install cx-oracle==5.3` to
|
||||
install from source.
|
||||
|
||||
Very old versions of cx_Oracle can be found in the files section at
|
||||
[SourceForce][17].
|
||||
|
||||
## Usage Example
|
||||
|
||||
## Example
|
||||
|
||||
```python
|
||||
from __future__ import print_function # needed for Python 2.x
|
||||
from __future__ import print_function
|
||||
|
||||
import cx_Oracle
|
||||
|
||||
# connect via SQL*Net string or by each segment in a separate argument
|
||||
#connection = cx_Oracle.connect("user/password@TNS")
|
||||
connection = cx_Oracle.connect("user", "password", "TNS")
|
||||
connection = cx_Oracle.connect("hr", "welcome", "localhost/orclpdb")
|
||||
|
||||
cursor = connection.cursor()
|
||||
cursor.execute("""
|
||||
select Col1, Col2, Col3
|
||||
from SomeTable
|
||||
where Col4 = :arg_1
|
||||
and Col5 between :arg_2 and :arg_3""",
|
||||
arg_1 = "VALUE",
|
||||
arg_2 = 5,
|
||||
arg_3 = 15)
|
||||
for column_1, column_2, column_3 in cursor:
|
||||
print("Values:", column_1, column_2, column_3)
|
||||
SELECT first_name, last_name
|
||||
FROM employees
|
||||
WHERE department_id = :did AND employee_id > :eid""",
|
||||
did = 50,
|
||||
eid = 190)
|
||||
for fname, lname in cursor:
|
||||
print("Values:", fname, lname)
|
||||
```
|
||||
|
||||
|
||||
For more examples, please see the [test suite][11] and the
|
||||
[samples][12]. You can also look at the scripts in the [cx_OracleTools][7] and
|
||||
the modules in the [cx_PyOracleLib][8] projects.
|
||||
[samples][12]. You can also look at the scripts in [cx_OracleTools][7] and
|
||||
the modules in [cx_PyOracleLib][8].
|
||||
|
||||
## Features
|
||||
|
||||
|
|
@ -94,15 +96,10 @@ the modules in the [cx_PyOracleLib][8] projects.
|
|||
- Connect to Oracle Database 9.2, 10, 11 or 12 (depending on the
|
||||
Oracle Client version used).
|
||||
|
||||
- SQL and PL/SQL Execution, with full support for OCI features like
|
||||
statement caching and statement caching auto-tuning. Oracle OCI
|
||||
(which is the database access layer used by cx_Oracle) has
|
||||
significant optimizations, including compressed fetch, pre-fetching,
|
||||
client and server result set caching, and statement caching.
|
||||
cx_Oracle applications can additionally make full use of PL/SQL to
|
||||
keep business logic near the data in the database, where it can be
|
||||
processed without having to ship large volumes of data to the
|
||||
application.
|
||||
- SQL and PL/SQL Execution. The underlying Oracle Client libraries
|
||||
have significant optimizations including compressed fetch,
|
||||
pre-fetching, client and server result set caching, and statement
|
||||
caching with auto-tuning.
|
||||
|
||||
- Full use of Oracle Network Service infrastructure, including
|
||||
encrypted network traffic and security features.
|
||||
|
|
@ -182,3 +179,5 @@ for more information.
|
|||
[13]: https://oracle.github.io/odpi/doc/installation.html
|
||||
[14]: http://cx-oracle.readthedocs.io/en/latest/releasenotes.html
|
||||
[15]: http://cx-oracle.readthedocs.io/en/latest/installation.html
|
||||
[16]: https://pypi.python.org/pypi/cx_Oracle/5.3
|
||||
[17]: https://sourceforge.net/projects/cx-oracle/files/
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ author = 'Oracle'
|
|||
# The short X.Y version.
|
||||
version = '6.0'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '6.0rc2'
|
||||
release = '6.0'
|
||||
|
||||
# There are two options for replacing |today|: either, you set today to some
|
||||
# non-false value, then it is used:
|
||||
|
|
|
|||
|
|
@ -11,16 +11,33 @@ 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.
|
||||
|
||||
The simplest method of installation is to `Install Using Pip`_. You can also
|
||||
`Install Using GitHub`_. If you run into trouble, check out the section on
|
||||
`Troubleshooting`_.
|
||||
The simplest method of installing cx_Oracle is to `Install Using Pip`_. You
|
||||
can also `Install Using GitHub`_. If you run into trouble, check out the
|
||||
section on `Troubleshooting`_. cx_Oracle uses `ODPI-C
|
||||
<https://github.com/oracle/odpi>`__, which means that the `ODPI-C installation
|
||||
instructions <https://oracle.github.io/odpi/doc/installation.html>`__ can be
|
||||
useful to review.
|
||||
|
||||
After cx_Oracle has been installed, you must also `Install Oracle Client`_, if
|
||||
that has not been done already. Oracle Client versions 12.2, 12.1 and 11.2
|
||||
are supported.
|
||||
|
||||
Note installation has changed from cx_Oracle 5. When using Oracle
|
||||
Instant Client, you should not set ``ORACLE_HOME``.
|
||||
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.
|
||||
|
||||
|
||||
Upgrading from cx_Oracle 5
|
||||
==========================
|
||||
|
||||
If you are upgrading from cx_Oracle 5 note these installation changes:
|
||||
|
||||
- When using Oracle Instant Client, you should not set ``ORACLE_HOME``.
|
||||
|
||||
- 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.
|
||||
|
||||
|
||||
Install Using Pip
|
||||
=================
|
||||
|
|
@ -29,17 +46,17 @@ 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/>`__.
|
||||
|
||||
The command to install the current Release Candidate of cx_Oracle 6 using pip
|
||||
on all platforms is::
|
||||
The command to install cx_Oracle 6 using pip on all platforms is::
|
||||
|
||||
python -m pip install cx_Oracle --upgrade --pre
|
||||
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.
|
||||
available for Windows and Linux. See
|
||||
`PyPI <https://pypi.python.org/pypi/cx_Oracle>`__.
|
||||
|
||||
If a pre-compiled binary is not available, the source will be
|
||||
downloaded, compiled, and the resulting binary installed. On Linux if
|
||||
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.
|
||||
|
|
@ -106,13 +123,13 @@ 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
|
||||
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>`__.
|
||||
|
||||
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
|
||||
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
|
||||
|
|
@ -138,15 +155,6 @@ errors. These include:
|
|||
- when attempting to get array DML row counts with Oracle Client
|
||||
11.2 you will get the error "DPI-1013: not supported"
|
||||
|
||||
cx_Oracle is an `ODPI-C <https://github.com/oracle/odpi>`__ application, which
|
||||
means that the installation instructions for
|
||||
`Linux <https://oracle.github.io/odpi/doc/installation.html#linux>`__,
|
||||
`Windows <https://oracle.github.io/odpi/doc/installation.html#windows>`__
|
||||
and `macOS <https://oracle.github.io/odpi/doc/installation.html#macos>`__
|
||||
are applicable. For other platforms like Solaris or AIX, follow the same
|
||||
general directions as for Linux.
|
||||
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
|
|
|
|||
|
|
@ -4,6 +4,44 @@ cx_Oracle Release Notes
|
|||
6.x releases
|
||||
############
|
||||
|
||||
Version 6.0 (August 2017)
|
||||
-------------------------
|
||||
|
||||
#) Update to `ODPI-C 2.0 <https://oracle.github.io/odpi/doc/releasenotes.html
|
||||
#version-2-0-august-14-2017>`__.
|
||||
|
||||
- Prevent closing the connection when there are any open statements or
|
||||
LOBs and add new error "DPI-1054: connection cannot be closed when open
|
||||
statements or LOBs exist" when this situation is detected; this is
|
||||
needed to prevent crashes under certain conditions when statements or
|
||||
LOBs are being acted upon while at the same time (in another thread) a
|
||||
connection is being closed; it also prevents leaks of statements and
|
||||
LOBs when a connection is returned to a session pool.
|
||||
- On platforms other than Windows, if the regular method for loading the
|
||||
Oracle Client libraries fails, try using $ORACLE_HOME/lib/libclntsh.so
|
||||
(`ODPI-C issue 20 <https://github.com/oracle/odpi/issues/20>`__).
|
||||
- Use the environment variable DPI_DEBUG_LEVEL at runtime, not compile
|
||||
time.
|
||||
- Added support for DPI_DEBUG_LEVEL_ERRORS (reports errors and has the
|
||||
value 8) and DPI_DEBUG_LEVEL_SQL (reports prepared SQL statement text
|
||||
and has the value 16) in order to further improve the ability to debug
|
||||
issues.
|
||||
- Correct processing of :meth:`Cursor.scroll()` in some circumstances.
|
||||
|
||||
#) Delay initialization of the ODPI-C library until the first standalone
|
||||
connection or session pool is created so that manipulation of the
|
||||
environment variable NLS_LANG can be performed after the module has been
|
||||
imported; this also has the added benefit of reducing the number of errors
|
||||
that can take place when the module is imported.
|
||||
#) Prevent binding of null values from generating the exception "ORA-24816:
|
||||
Expanded non LONG bind data supplied after actual LONG or LOB column" in
|
||||
certain circumstances
|
||||
(`issue 50 <https://github.com/oracle/python-cx_Oracle/issues/50>`__).
|
||||
#) Added information on how to run the test suite
|
||||
(`issue 33 <https://github.com/oracle/python-cx_Oracle/issues/33>`__).
|
||||
#) Documentation improvements.
|
||||
|
||||
|
||||
Version 6.0 rc 2 (July 2017)
|
||||
----------------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue