Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 079927c

Browse filesBrowse files
anthony-tuiningaanthony-tuininga
committed
Various documentation and tutorial improvements.
1 parent 3f06ea3 commit 079927c
Copy full SHA for 079927c
Expand file treeCollapse file tree

12 files changed

+266
-141
lines changed

‎doc/src/api_manual/module.rst

Copy file name to clipboardExpand all lines: doc/src/api_manual/module.rst
+49-28Lines changed: 49 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -208,23 +208,34 @@ Module Interface
208208
edition=None, timeout=0, waitTimeout=0, maxLifetimeSession=0, \
209209
sessionCallback=None, maxSessionsPerShard=0)
210210

211-
Create and return a :ref:`session pool object <sesspool>`.
211+
Create and return a :ref:`session pool object <sesspool>`. Session pooling
212+
(also known as connection pooling) creates a pool of available connections
213+
to the database, allowing applications to acquire a connection very quickly.
214+
It is of primary use in a server where connections are requested in rapid
215+
succession and used for a short period of time, for example in a web server.
216+
See :ref:`connpool` for more information.
217+
212218
Connection pooling in cx_Oracle is handled by Oracle's
213219
`Session pooling <https://www.oracle.com/pls/topic/lookup?
214220
ctx=dblatest&id=GUID-F9662FFB-EAEF-495C-96FC-49C6D1D9625C>`__
215221
technology. This allows cx_Oracle applications to support features
216222
like `Application Continuity <https://www.oracle.com/pls/topic/lookup?
217223
ctx=dblatest&id=GUID-A8DD9422-2F82-42A9-9555-134296416E8F>`__.
218224

219-
See :ref:`connpool` for information on connection pooling.
225+
The user, password and dsn parameters are the same as for
226+
:meth:`cx_Oracle.connect()`
220227

221-
Session pooling creates a pool of available connections to the
222-
database, allowing applications to acquire a connection very quickly.
223-
It is of primary use in a server where connections are requested
224-
in rapid succession and used for a short period of time, for example in a
225-
web server.
228+
The min, max and increment parameters control pool growth behavior. A fixed
229+
pool size where min equals max is recommended to help prevent connection
230+
storms and to help overall system stability. The min parameter is the
231+
number of connections opened when the pool is created. The increment is the
232+
number of connections that are opened whenever a connection request exceeds
233+
the number of currently open connections. The max parameter is the maximum
234+
number of connections that can be open in the connection pool. Note that
235+
when :ref:`external authentication <extauth>` or :ref:`heterogeneous pools
236+
<connpooltypes>` are used, the pool growth behavior is different.
226237

227-
If the connection type is specified, all calls to
238+
If the connectiontype parameter is specified, all calls to
228239
:meth:`~SessionPool.acquire()` will create connection objects of that type,
229240
rather than the base type defined at the module level.
230241

@@ -233,6 +244,10 @@ Module Interface
233244
Doing so in single threaded applications imposes a performance penalty of
234245
about 10-15% which is why the default is False.
235246

247+
The getmode parameter indicates whether or not future
248+
:func:`SessionPool.acquire()` calls will wait for available connections. It
249+
can be one of the :ref:`Session Pool Get Modes <sesspoolmodes>` values.
250+
236251
The events parameter is expected to be a boolean expression which indicates
237252
whether or not to initialize Oracle in events mode. This is required for
238253
continuous query notification and high availability event notifications.
@@ -241,22 +256,26 @@ Module Interface
241256
indicates whether or not to create a homogeneous pool. A homogeneous pool
242257
requires that all connections in the pool use the same credentials. As such
243258
proxy authentication and external authentication is not possible with a
244-
homogeneous pool.
259+
homogeneous pool. See :ref:`Heterogeneous and Homogeneous Connection Pools
260+
<connpooltypes>`.
245261

246262
The externalauth parameter is expected to be a boolean expression which
247263
indicates whether or not external authentication should be used. External
248264
authentication implies that something other than the database is
249265
authenticating the user to the database. This includes the use of operating
250-
system authentication and Oracle wallets.
266+
system authentication and Oracle wallets. See :ref:`Connecting Using
267+
External Authentication <extauth>`.
251268

252-
See the :ref:`globalization <globalization>` section for details on the
253-
encoding and nencoding parameters. Note the default encoding and nencoding
254-
values changed to "UTF-8" in cx_Oracle 8, and any character set in NLS_LANG
255-
is ignored.
269+
The encoding and nencoding parameters set the encodings used for string
270+
values transferred between cx_Oracle and Oracle Database, see
271+
:ref:`Character Sets and Globalization <globalization>`. Note the default
272+
encoding and nencoding values changed to "UTF-8" in cx_Oracle 8, and any
273+
character set in NLS_LANG is ignored.
256274

257-
The edition parameter is expected to be a string, if specified, and sets
258-
the edition to use for the sessions in the pool. It is only relevant if
259-
both the client and the server are at least Oracle Database 11.2.
275+
The edition parameter is expected to be a string, if specified, and sets the
276+
edition to use for the sessions in the pool. It is only relevant if both the
277+
client and the server are at least Oracle Database 11.2. See
278+
:ref:`Edition-Based Redefinition (EBR) <ebr>`.
260279

261280
The timeout parameter is expected to be an integer, if specified, and sets
262281
the length of time (in seconds) after which idle sessions in the pool are
@@ -279,17 +298,18 @@ Module Interface
279298
may exist.
280299

281300
The sessionCallback parameter is expected to be either a string or a
282-
callable. If the parameter is a string, this refers to a PL/SQL procedure
283-
that will be called when :func:`SessionPool.acquire()` requests a tag and
284-
that tag does not match the connection's actual tag. Support for the PL/SQL
285-
procedure requires Oracle Client libraries 12.2 or later. See the
286-
`OCI documentation <https://www.oracle.com/pls/topic/lookup?
287-
ctx=dblatest&id=GUID-B853A020-752F-494A-8D88-D0396EF57177>`__ for more
288-
information. If the sessionCallback parameter is a callable, however, it
289-
will be called when a newly created connection is returned from the pool
290-
or when a tag is requested and that tag does not match the connection's
291-
actual tag. The callable will be invoked with the connection and the
292-
requested tag as its only parameters.
301+
callable. If the sessionCallback parameter is a callable, it will be called
302+
when a newly created connection is returned from the pool, or when a tag is
303+
requested and that tag does not match the connection's actual tag. The
304+
callable will be invoked with the connection and the requested tag as its
305+
only parameters. If the parameter is a string, it should be the name of a
306+
PL/SQL procedure that will be called when :func:`SessionPool.acquire()`
307+
requests a tag and that tag does not match the connection's actual tag. See
308+
:ref:`Session CallBacks for Setting Pooled Connection State
309+
<sessioncallback>`. Support for the PL/SQL procedure requires Oracle Client
310+
libraries 12.2 or later. See the `OCI documentation
311+
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
312+
id=GUID-B853A020-752F-494A-8D88-D0396EF57177>`__ for more information.
293313

294314
The maxSessionsPerShard parameter is expected to be an integer, if
295315
specified, and sets the maximum number of sessions in the pool that can be
@@ -823,6 +843,7 @@ also used by the :attr:`MessageTable.operation` or
823843
This constant is used to specify that messages should be sent when data is
824844
updated, or that the message identifies a row that has been updated.
825845

846+
.. _sesspoolmodes:
826847

827848
Session Pool Get Modes
828849
----------------------

‎doc/src/api_manual/session_pool.rst

Copy file name to clipboardExpand all lines: doc/src/api_manual/session_pool.rst
+5-3Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -150,9 +150,11 @@ SessionPool Object
150150

151151
This read-write attribute specifies the size of the statement cache that
152152
will be used as the starting point for any connections that are created by
153-
the session pool. Once created, the connection's statement cache size can
154-
only be changed by setting the stmtcachesize attribute on the connection
155-
itself.
153+
the session pool. Once a connection is created, that connection's statement
154+
cache size can only be changed by setting the
155+
:attr:`Connection.stmtcachesize` attribute on the connection itself.
156+
157+
See :ref:`Statement Caching <stmtcache>` for more information.
156158

157159
.. versionadded:: 6.0
158160

‎doc/src/license.rst

Copy file name to clipboardExpand all lines: doc/src/license.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ License
1010

1111
.. centered:: **LICENSE AGREEMENT FOR CX_ORACLE**
1212

13-
Copyright |copy| 2016, 2018, Oracle and/or its affiliates. All rights reserved.
13+
Copyright |copy| 2016, 2020, Oracle and/or its affiliates. All rights reserved.
1414

1515
Copyright |copy| 2007-2015, Anthony Tuininga. All rights reserved.
1616

‎doc/src/user_guide/connection_handling.rst

Copy file name to clipboardExpand all lines: doc/src/user_guide/connection_handling.rst
+8-3Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -324,9 +324,9 @@ connections, so monitor the connection rate in AWR for an unexpected value. You
324324
can explicitly initiate a full ping to check connection liveness with
325325
:meth:`Connection.ping()` but overuse will impact performance and scalability.
326326

327-
The Oracle Real-World Performance Group's general recommendation for connection
328-
pools is use a fixed sized pool. The values of `min` and `max` should be the
329-
same (and `increment` equal to zero). the firewall, `resource manager
327+
The Oracle Real-World Performance Group's recommendation is to use fixed size
328+
connection pools. The values of min and max should be the same (and the
329+
increment equal to zero). The :ref:`firewall <hanetwork>`, `resource manager
330330
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-2BEF5482-CF97-4A85-BD90-9195E41E74EF>`__
331331
or user profile `IDLE_TIME
332332
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-ABC7AE4D-64A8-4EA9-857D-BEF7300B64C3>`__
@@ -336,6 +336,11 @@ Static Pools
336336
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-7DFBA826-7CC0-4D16-B19C-31D168069B54>`__,
337337
which contains details about sizing of pools.
338338

339+
The Real-World Performance Group also recommends keeping pool sizes small, as
340+
they may perform better than larger pools. The pool attributes should be
341+
adjusted to handle the desired workload within the bounds of available resources
342+
in cx_Oracle and the database.
343+
339344
.. _sessioncallback:
340345

341346
Session CallBacks for Setting Pooled Connection State

‎doc/src/user_guide/initialization.rst

Copy file name to clipboardExpand all lines: doc/src/user_guide/initialization.rst
+3-2Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,9 @@ cx_Oracle looks for the Oracle Client libraries as follows:
3838
database installation, such as Oracle Database "XE" Express Edition, then
3939
you will need to have previously set your environment to use that
4040
software installation, otherwise files such as message files will not be
41-
located. If the Oracle Client libraries cannot be loaded from
42-
``lib_dir``, then an exception is raised.
41+
located. On Windows when the path contains backslashes, use a 'raw'
42+
string like ``lib_dir = r"C:\instantclient_19_6"``. If the Oracle Client
43+
libraries cannot be loaded from ``lib_dir``, then an exception is raised.
4344

4445
- If ``lib_dir`` was not specified, then Oracle Client libraries are looked
4546
for in the directory where the cx_Oracle binary module is installed.

‎doc/src/user_guide/installation.rst

Copy file name to clipboardExpand all lines: doc/src/user_guide/installation.rst
+27-7Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,20 @@ Overview
1010
To use cx_Oracle 8 with Python and Oracle Database you need:
1111

1212
- Python 3.5 and higher. Older versions of cx_Oracle may work with older
13-
versions of Python.
13+
versions of Python, for example see :ref:`Installing cx_Oracle in Python 2
14+
<python2>`
1415

1516
- Oracle Client libraries. These can be from the free `Oracle Instant
1617
Client
1718
<https://www.oracle.com/database/technologies/instant-client.html>`__,
1819
or those included in Oracle Database if Python is on the same
1920
machine as the database. Oracle client libraries versions 19, 18, 12,
2021
and 11.2 are supported on Linux, Windows and macOS. Users have
21-
also reported success with other platforms.
22+
also reported success with other platforms. Use the latest client possible:
23+
Oracle's standard client-server version interoperability allows connection to
24+
both older and newer databases.
2225

23-
- An Oracle Database. Oracle's standard client-server version
24-
interoperability allows cx_Oracle to connect to both older and newer
25-
databases.
26+
- An Oracle Database, either local or remote.
2627

2728
The cx_Oracle module loads Oracle Client libraries which communicate
2829
over Oracle Net to an existing database. Oracle Net is not a separate
@@ -39,8 +40,8 @@ Quick Start cx_Oracle Installation
3940
- Install `Python <https://www.python.org/downloads>`__ 3, if not already
4041
available. On macOS you must always install your own Python.
4142

42-
Python 3.5 and higher are supported by cx_Oracle 8. For Python 2, use
43-
cx_Oracle 7.3.
43+
Python 3.5 and higher are supported by cx_Oracle 8. For Python 2, see
44+
:ref:`Installing cx_Oracle in Python 2 <python2>`.
4445

4546
- Install cx_Oracle from `PyPI
4647
<https://pypi.org/project/cx-Oracle/>`__ with:
@@ -499,6 +500,8 @@ To use cx_Oracle with Oracle Instant Client zip files:
499500
import cx_Oracle
500501
cx_Oracle.init_oracle_client(lib_dir=r"C:\oracle\instantclient_19_6")
501502
503+
Note a 'raw' string is used because backslashes occur in the path.
504+
502505
* Alternatively, add the Oracle Instant Client directory to the ``PATH``
503506
environment variable. The directory must occur in ``PATH`` before any
504507
other Oracle directories. Restart any open command prompt windows.
@@ -786,6 +789,23 @@ If you are upgrading from cx_Oracle 5 note these installation changes:
786789
hosted. Use the supplied cx_Oracle Wheels instead, or use RPMs
787790
from Oracle, see :ref:`oraclelinux`.
788791

792+
.. _python2:
793+
794+
Installing cx_Oracle in Python 2
795+
================================
796+
797+
To install cx_Oracle in Python 2, use a command like::
798+
799+
python -m pip install cx_Oracle==7.3 --upgrade --user
800+
801+
cx_Oracle 7.3 was the last version with support for Python 2.
802+
803+
For other installation options such as installing through a proxy, see
804+
instructions above. Make sure the Oracle Client libraries are in the system
805+
library search path because cx_Oracle 7 does not support the
806+
:meth:`cx_Oracle.init_oracle_client()` method and does not support loading the
807+
Oracle Client libraries from the directory containing the cx_Oracle module
808+
binary.
789809

790810
Installing cx_Oracle 5.3
791811
========================

‎doc/src/user_guide/plsql_execution.rst

Copy file name to clipboardExpand all lines: doc/src/user_guide/plsql_execution.rst
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,7 @@ Data from both the result sets are returned::
234234
(1000, 1, 'BOOKS')
235235
(2000, 2, 'FURNITURE')
236236

237+
.. _ebr:
237238

238239
Edition-Based Redefinition (EBR)
239240
--------------------------------

‎doc/src/user_guide/tuning.rst

Copy file name to clipboardExpand all lines: doc/src/user_guide/tuning.rst
+34-21Lines changed: 34 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Some general tuning tips are:
3737
Make good use of PL/SQL to avoid executing many individual statements from
3838
cx_Oracle.
3939

40-
Tune the Statement Cache with :attr:`Connection.stmtcachesize`.
40+
Tune the :ref:`Statement Cache <stmtcache>`.
4141

4242
Enable :ref:`Client Result Caching <clientresultcache>` for small lookup tables.
4343

@@ -258,20 +258,21 @@ Statement Caching
258258
cx_Oracle's :meth:`Cursor.execute()` and :meth:`Cursor.executemany()` functions
259259
use the `Oracle Call Interface statement cache
260260
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4947CAE8-1F00-4897-BB2B-7F921E495175>`__
261-
to make re-execution of statements efficient. This cache removes most needs for
262-
using the :meth:`Cursor.prepare()` method.
263-
264-
The statement cache size can be set with :attr:`Connection.stmtcachesize`.
265-
266-
Each non-pooled connection and each session in the connection pool has
267-
its own cache of statements with a default size of 20. Statement
268-
caching lets cursors be used without re-parsing the statement.
269-
Statement caching also reduces meta data transfer costs between the
270-
cx_Oracle and the database. Performance and scalability are
271-
improved.
272-
273-
In general, set the statement cache to the size of the working set of
274-
statements being executed by the application.
261+
to make re-execution of statements efficient. Each standalone or pooled
262+
connection has its own cache of statements with a default size of 20. Statement
263+
caching lets cursors be used without re-parsing the statement. Statement
264+
caching also reduces metadata transfer costs between the cx_Oracle and the
265+
database. Performance and scalability are improved.
266+
267+
The statement cache size can be set with :attr:`Connection.stmtcachesize` or
268+
:attr:`SessionPool.stmtcachesize`. In general, set the statement cache size to
269+
the size of the working set of statements being executed by the application. To
270+
manually tune the cache, monitor the general application load and the `Automatic
271+
Workload Repository
272+
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-56AEF38E-9400-427B-A818-EDEC145F7ACD>`__
273+
(AWR) "bytes sent via SQL*Net to client" values. The latter statistic should
274+
benefit from not shipping statement metadata to cx_Oracle. Adjust the statement
275+
cache size to your satisfaction.
275276

276277
Statement caching can be disabled by setting the size to 0. Disabling
277278
the cache may be beneficial when the quantity or order of statements
@@ -283,12 +284,24 @@ be flushed from the cache before the statements are re-executed.
283284
With Oracle Database 12c, or later, the statement cache size can be
284285
automatically tuned using the :ref:`oraaccess.xml <optclientfiles>` file.
285286

286-
To manually tune the statement cache size, monitor general application load and
287-
the `Automatic Workload Repository
288-
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-56AEF38E-9400-427B-A818-EDEC145F7ACD>`__
289-
(AWR) "bytes sent via SQL*Net to client" values. The latter statistic should
290-
benefit from not shipping statement metadata to cx_Oracle. Adjust the statement
291-
cache size to your satisfaction.
287+
When it is inconvenient to pass statement text through an application, the
288+
:meth:`Cursor.prepare()` call can be used to avoid statement re-parsing.
289+
Subsequent ``execute()`` calls use the value ``None`` instead of the SQL text:
290+
291+
.. code-block:: python
292+
293+
cur.prepare("select * from dept where deptno = :id order by deptno")
294+
295+
cur.execute(None, id = 20)
296+
res = cur.fetchall()
297+
print(res)
298+
299+
cur.execute(None, id = 10)
300+
res = cur.fetchall()
301+
print(res)
302+
303+
Statements passed to :meth:`~Cursor.prepare()` are also stored in the statement
304+
cache.
292305

293306
.. _clientresultcache:
294307

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.