HackBase/python-cx_Oracle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation and sample updates for clarity and to note the fact that

Browse Source 
connection pools now always enable threading.
This commit is contained in:
Anthony Tuininga 2021-04-23 14:21:45 -06:00
parent fa36066875
commit ab6e6f06ef
8 changed files with 27 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
doc/src/api_manual/deprecations.rst
View File

@ -18,7 +18,8 @@ if applicable. The most recent deprecations are listed first.
- Comments
* - `encoding` parameter to :meth:`cx_Oracle.connect()`
- No longer needed as the use of encodings other than UTF-8 is
deprecated.
deprecated. Encoding is handled internally between cx_Oracle and Oracle
Database.
* - `nencoding` parameter to :meth:`cx_Oracle.connect()`
- No longer needed as the use of encodings other than UTF-8 is
deprecated.
@ -30,13 +31,15 @@ if applicable. The most recent deprecations are listed first.
deprecated.
* - Connection.maxBytesPerCharacter
- No longer needed as the use of encodings other than UTF-8 is
deprecated.
* - positional parmeters to :meth:`cx_Oracle.connect()`
deprecated. The constant value 4 can be used instead.
* - Positional parameters to :meth:`cx_Oracle.connect()`
- Replace with keyword parameters in order to comply with the Python
database API.
* - positional parmeters to :meth:`cx_Oracle.SessionPool()`
* - positional parameters to :meth:`cx_Oracle.SessionPool()`
- Replace with keyword parameters in order to comply with the Python
database API.
* - `threaded` parameter to :meth:`cx_Oracle.SessionPool()`
- The value of this parameter is ignored. Threading is now always used.
* - `waitTimeout` parameter to :meth:`cx_Oracle.SessionPool()`
- Replace with parameter name `wait_timeout`
* - `maxLifetimeSession` parameter to :meth:`cx_Oracle.SessionPool()`
@ -46,7 +49,7 @@ if applicable. The most recent deprecations are listed first.
* - `maxSessionsPerShard` parameter to :meth:`cx_Oracle.SessionPool()`
- Replace with parameter name `max_sessions_per_shard`
* - `payloadType` parameter to :meth:`Connection.queue()`
- Replace with parameter name `payload_type` if using keyword parmeters.
- Replace with parameter name `payload_type` if using keyword parameters.
* - `ipAddress` parameter to :meth:`Connection.subscribe()`
- Replace with parameter name `ip_address`
* - `groupingClass` parameter to :meth:`Connection.subscribe()`

13
doc/src/api_manual/module.rst
View File

@ -78,8 +78,7 @@ Module Interface
The threaded parameter is expected to be a boolean expression which
indicates whether or not Oracle should wrap accesses to connections with a
mutex. Doing so in single threaded applications imposes a performance
penalty of about 10-15% which is why the default is False.
mutex.
The events parameter is expected to be a boolean expression which indicates
whether or not to initialize Oracle in events mode. This is required for
@ -250,11 +249,6 @@ Module Interface
:meth:`~SessionPool.acquire()` will create connection objects of that type,
rather than the base type defined at the module level.
The threaded parameter is expected to be a boolean expression which
indicates whether Oracle should wrap accesses to connections with a mutex.
Doing so in single threaded applications imposes a performance penalty of
about 10-15% which is why the default is False.
The getmode parameter indicates whether or not future
:func:`SessionPool.acquire()` calls will wait for available connections. It
can be one of the :ref:`Session Pool Get Modes <sesspoolmodes>` values.
@ -352,7 +346,8 @@ Module Interface
parameter `sessionCallback` was renamed to `session_callback` and the
parameter `maxSessionsPerShard` was renamed to
`max_sessions_per_shard`. The old names will continue to work as
keyword parameters for a period of time.
keyword parameters for a period of time. The `threaded` parameter value
is ignored and threading is always enabled.
.. function:: Time(hour, minute, second)
@ -429,7 +424,7 @@ General
Note that in order to make use of multiple threads in a program which
intends to connect and disconnect in different threads, the threaded
parameter to :meth:`connect()` or :meth:`SessionPool()` must be true.
parameter to :meth:`connect()` must be `True`.
.. data:: version

16
doc/src/release_notes.rst
View File

@ -15,7 +15,7 @@ Version 8.2 (TBD)
pools. This significantly improves the performance of methods
:meth:`SodaDatabase.createCollection()` (when not specifying a value for
the metadata parameter) and :meth:`SodaDatabase.openCollection()`. Caching
is available when using Oracle Client version 19.11 and higher
is available when using Oracle Client version 19.11 and higher.
#) Added support for supplying hints to SODA operations. A new non-terminal
method :meth:`~SodaOperation.hint()` was added and a `hint` parameter was
added to the methods :meth:`SodaCollection.insertOneAndGet()`,
@ -26,20 +26,20 @@ Version 8.2 (TBD)
:meth:`cx_Oracle.SessionPool()` in order to permit specifying the size of
the statement cache during the creation of pools and standalone
connections.
#) Threaded mode is now always enabled when creating connection pools with
:meth:`cx_Oracle.SessionPool()`. Any `threaded` parameter value is ignored.
#) Eliminated a memory leak when calling :meth:`SodaOperation.filter()` with a
dictionary.
#) The distributed transaction handle assosciated with the connection is now
cleared on commit or rollback (`issue 530
<https://github.com/oracle/python-cx_Oracle/issues/530>`__).
#) Stop passing unsupported flags to dpiSodaDocCursor_getNext().
#) Added check to ensure that when setting variables or object attributes, the
type of the temporary LOB must match the expected type.
#) In order to follow the PEP 8 naming style a number of parameter names,
method names and attribute names were modified. The old names will be
removed in a subsequent release of cx_Oracle. In addition, the use of
encodings other than UTF-8 is also deprecated. See
:ref:`_deprecations_8_2` for details.
#) Improved test suite.
#) A small number of parameter, method, and attribute names were updated to
follow the PEP 8 style guide. This brings better consistency to the
cx_Oracle API. The old names are still usable but may be removed in a
future release of cx_Oracle. See :ref:`_deprecations_8_2` for details.
#) Improved the test suite.
Version 8.1 (December 2020)

11
doc/src/user_guide/connection_handling.rst
View File

@ -316,17 +316,6 @@ for a connection to become available if all are currently in use, for example:
pool = cx_Oracle.SessionPool("hr", userpwd, "dbhost.example.com/orclpdb1",
min=2, max=5, increment=1, getmode=cx_Oracle.SPOOL_ATTRVAL_WAIT, encoding="UTF-8")
Applications that are using connections concurrently in multiple threads should
set the ``threaded`` parameter to *True* when creating a connection pool:
.. code-block:: python
# Create the session pool
pool = cx_Oracle.SessionPool("hr", userpwd, "dbhost.example.com/orclpdb1",
min=2, max=5, increment=1, threaded=True, encoding="UTF-8")
See `ConnectionPool.py
<https://github.com/oracle/python-cx_Oracle/tree/master/samples/ConnectionPool.py>`__
for an example.

7
samples/connection_pool.py
View File

@ -12,9 +12,8 @@
# The script uses threading to show multiple users of the pool. One thread
# performs a database sleep while another performs a query. A more typical
# application might be a web service that handles requests from multiple users.
# Applications that use connections concurrently in multiple threads should set
# the 'threaded' parameter to True. Note only one operation (such as an execute
# or fetch) can take place at a time on each connection.
# Note only one operation (such as an execute or fetch) can take place at a time
# on each connection.
#
# Also see session_callback.py.
#
@ -29,7 +28,7 @@ import sample_env
pool = oracledb.SessionPool(user=sample_env.get_main_user(),
password=sample_env.get_main_password(),
dsn=sample_env.get_connect_string(), min=2,
max=5, increment=1, threaded=True)
max=5, increment=1)
def the_long_query():
with pool.acquire() as conn:

2
samples/cqn2.py
View File

@ -61,7 +61,7 @@ def callback(message):
pool = oracledb.SessionPool(user=sample_env.get_main_user(),
password=sample_env.get_main_password(),
dsn=sample_env.get_connect_string(), min=2, max=5,
increment=1, events=True, threaded=True)
increment=1, events=True)
with pool.acquire() as connection:
qos = oracledb.SUBSCR_QOS_QUERY | oracledb.SUBSCR_QOS_ROWIDS
sub = connection.subscribe(callback=callback, timeout=1800, qos=qos)

5
samples/session_callback.py
View File

@ -1,5 +1,5 @@
#------------------------------------------------------------------------------
# Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2019, 2021, Oracle and/or its affiliates. All rights reserved.
#------------------------------------------------------------------------------
#------------------------------------------------------------------------------
@ -81,8 +81,7 @@ def init_session(conn, requested_tag):
pool = oracledb.SessionPool(user=sample_env.get_main_user(),
password=sample_env.get_main_password(),
dsn=sample_env.get_connect_string(), min=2, max=5,
increment=1, threaded=True,
session_callback=init_session)
increment=1, session_callback=init_session)
# acquire session without specifying a tag; since the session returned is
# newly created, the callback will be invoked but since there is no tag

3
samples/session_callback_plsql.py
View File

@ -29,8 +29,7 @@ import sample_env
pool = oracledb.SessionPool(user=sample_env.get_main_user(),
password=sample_env.get_main_password(),
dsn=sample_env.get_connect_string(), min=2, max=5,
increment=1, threaded=True,
session_callback="pkg_SessionCallback.TheCallback")
increment=1, session_callback="pkg_SessionCallback.TheCallback")
# truncate table logging calls to PL/SQL session callback
with pool.acquire() as conn: