Codebase list python-cx-oracle / 7751ccf
Documentation improvements. Anthony Tuininga 3 years ago
6 changed file(s) with 95 addition(s) and 47 deletion(s). Raw diff Collapse all Expand all
+6
-3
doc/src/api_manual/module.rst less more
230230 number of connections opened when the pool is created. The increment is the
231231 number of connections that are opened whenever a connection request exceeds
232232 the number of currently open connections. The max parameter is the maximum
233 number of connections that can be open in the connection pool. Note that
234 when :ref:`external authentication <extauth>` or :ref:`heterogeneous pools
235 <connpooltypes>` are used, the pool growth behavior is different.
233 number of connections that can be open in the connection pool.
234
235 Note that when using :ref:`external authentication <extauth>`,
236 :ref:`heterogeneous pools <connpooltypes>`, or :ref:`drcp`, then the pool
237 growth behavior is different. In these cases the number of connections
238 created at pool startup is always zero, and the increment is always one.
236239
237240 If the connectiontype parameter is specified, all calls to
238241 :meth:`~SessionPool.acquire()` will create connection objects of that type,
+1
-1
doc/src/index.rst less more
44 **cx_Oracle** is a module that enables access to Oracle Database and conforms
55 to the Python database API specification. This module is currently tested
66 against Oracle Client 19c, 18c, 12c, and 11.2, and Python 3.5, 3.6, 3.7 and
7 3.8.
7 3.8. Older versions of cx_Oracle may be used with previous Python releases.
88
99 **cx_Oracle** is distributed under an open-source :ref:`license <license>`
1010 (the BSD license). A detailed description of cx_Oracle changes can be found in
+1
-0
doc/src/release_notes.rst less more
1111 <https://oracle.github.io/odpi/doc/releasenotes.html#
1212 version-4-0-2-TBD>`__. This includes the fix for
1313 (`issue 459 <https://github.com/oracle/python-cx_Oracle/issues/459>`__).
14 #) Documentation improvements.
1415
1516
1617 Version 8.0 (June 2020)
+83
-40
doc/src/user_guide/connection_handling.rst less more
2121
2222 * **Pooled connections**
2323
24 Connection pooling is important for performance when applications
25 frequently connect and disconnect from the database. Oracle high
26 availability features in the pool implementation mean that small
27 pools can also be useful for applications that want a few
28 connections available for infrequent use. Pools are created with
29 :meth:`cx_Oracle.SessionPool()` and then
30 :meth:`SessionPool.acquire()` can be called to obtain a connection
31 from a pool.
24 :ref:`Connection pooling <connpool>` is important for performance when
25 applications frequently connect and disconnect from the database. Pools
26 support Oracle's :ref:`high availability <highavailability>` features and are
27 recommended for applications that must be reliable. Small pools can also be
28 useful for applications that want a few connections available for infrequent
29 use. Pools are created with :meth:`cx_Oracle.SessionPool()` at application
30 initialization time, and then :meth:`SessionPool.acquire()` can be called to
31 obtain a connection from a pool.
3232
3333 Many connection behaviors can be controlled by cx_Oracle options. Other
3434 settings can be configured in :ref:`optnetfiles` or in :ref:`optclientfiles`.
5656 :meth:`Connection.close()`. Alternatively, you may prefer to let connections
5757 be automatically cleaned up when references to them go out of scope. This lets
5858 cx_Oracle close dependent resources in the correct order. One other approach is
59 the use of a "with" block, which ensures that a connection is closed once the
60 block is completed. For example:
59 the use of a "with" block, for example:
6160
6261 .. code-block:: python
6362
7170 This code ensures that, once the block is completed, the connection is closed
7271 and resources have been reclaimed by the database. In addition, any attempt to
7372 use the variable ``connection`` outside of the block will simply fail.
73
74 Prompt closing of connections is important when using connection pools so
75 connections are available for reuse by other pool users.
7476
7577 .. _connstr:
7678
247249 ==================
248250
249251 cx_Oracle's connection pooling lets applications create and maintain a pool of
250 connections to the database. The internal implementation uses Oracle's
251 `session pool technology <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
252 id=GUID-F9662FFB-EAEF-495C-96FC-49C6D1D9625C>`__.
253 In general, each connection in a cx_Oracle connection pool corresponds to one
254 Oracle session.
252 connections to the database. Connection pooling is important for performance
253 when applications frequently connect and disconnect from the database. The pool
254 implementation uses Oracle's `session pool technology
255 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
256 id=GUID-F9662FFB-EAEF-495C-96FC-49C6D1D9625C>`__ which supports Oracle's
257 :ref:`high availability <highavailability>` features and is recommended for
258 applications that must be reliable. This also means that small pools can be
259 useful for applications that want a few connections available for infrequent
260 use.
255261
256262 A connection pool is created by calling :meth:`~cx_Oracle.SessionPool()`. This
257 is generally called during application initialization. Connections can then be
258 obtained from a pool by calling :meth:`~SessionPool.acquire()`. The initial
259 pool size and the maximum pool size are provided at the time of pool creation.
260 When the pool needs to grow, new connections are created automatically. The
261 pool can shrink back to the minimum size when connections are no longer in use.
263 is generally called during application initialization. The initial pool size
264 and the maximum pool size are provided at the time of pool creation. When the
265 pool needs to grow, new connections are created automatically. The pool can
266 shrink back to the minimum size when connections are no longer in use. For
267 pools created with :ref:`external authentication <extauth>`, with
268 :ref:`homogeneous <connpooltypes>` set to False, or when using :ref:`drcp`, then
269 the number of connections initially created is zero even if a larger value is
270 specified for ``min``. Also in these cases the pool increment is always 1,
271 regardless of the value of ``increment``.
272
273 After a pool has been created, connections can be obtained from it by calling
274 :meth:`~SessionPool.acquire()`. These connections can be used in the same way
275 that standalone connections are used.
262276
263277 Connections acquired from the pool should be released back to the pool using
264278 :meth:`SessionPool.release()` or :meth:`Connection.close()` when they are no
265279 longer required. Otherwise, they will be released back to the pool
266280 automatically when all of the variables referencing the connection go out of
267 scope. The session pool can be completely closed using
268 :meth:`SessionPool.close()`.
281 scope. This make connections available for other users of the pool.
282
283 The session pool can be completely closed using :meth:`SessionPool.close()`.
269284
270285 The example below shows how to connect to Oracle Database using a
271286 connection pool:
290305 # Close the pool
291306 pool.close()
292307
308 Other :meth:`cx_Oracle.SessionPool()` options can be used at pool creation. For
309 example the ``getmode`` value can be set so that any ``aquire()`` call will wait
310 for a connection to become available if all are currently in use, for example:
311
312 .. code-block:: python
313
314 # Create the session pool
315 pool = cx_Oracle.SessionPool("hr", userpwd, "dbhost.example.com/orclpdb1",
316 min=2, max=5, increment=1, getmode=cx_Oracle.SPOOL_ATTRVAL_WAIT, encoding="UTF-8")
317
318
293319 Applications that are using connections concurrently in multiple threads should
294320 set the ``threaded`` parameter to *True* when creating a connection pool:
295321
298324 # Create the session pool
299325 pool = cx_Oracle.SessionPool("hr", userpwd, "dbhost.example.com/orclpdb1",
300326 min=2, max=5, increment=1, threaded=True, encoding="UTF-8")
327
301328
302329 See `ConnectionPool.py
303330 <https://github.com/oracle/python-cx_Oracle/tree/master/samples/ConnectionPool.py>`__
313340 is about to return a connection that was unused in the pool for 60 seconds. If
314341 the ping fails, the connection will be discarded and another one obtained before
315342 :meth:`~SessionPool.acquire()` returns to the application. Because this full
316 ping is time based, it won't catch every failure. Also since network timeouts
317 and session kills may occur after :meth:`~SessionPool.acquire()` and before
318 :meth:`Cursor.execute()`, applications need to check for errors after each
319 :meth:`~Cursor.execute()` and make application-specific decisions about retrying
320 work if there was a connection failure. Note both the lightweight and full ping
321 connection checks can mask configuration issues, for example firewalls killing
322 connections, so monitor the connection rate in AWR for an unexpected value. You
323 can explicitly initiate a full ping to check connection liveness with
324 :meth:`Connection.ping()` but overuse will impact performance and scalability.
343 ping is time based, it won't catch every failure. Also network timeouts and
344 session kills may occur after :meth:`~SessionPool.acquire()` and before
345 :meth:`Cursor.execute()`. To handle these cases, applications need to check
346 for errors after each :meth:`~Cursor.execute()` and make application-specific
347 decisions about retrying work if there was a connection failure. Oracle's
348 :ref:`Application Continuity <highavailability>` can do this automatically in
349 some cases. Note both the lightweight and full ping connection checks can mask
350 performance-impacting configuration issues, for example firewalls killing
351 connections, so monitor the connection rate in `AWR
352 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-56AEF38E-9400-427B-A818-EDEC145F7ACD>`__
353 for an unexpected value. You can explicitly initiate a full ping to check
354 connection liveness with :meth:`Connection.ping()` but overuse will impact
355 performance and scalability.
356
357 Connection Pool Sizing
358 ----------------------
325359
326360 The Oracle Real-World Performance Group's recommendation is to use fixed size
327 connection pools. The values of min and max should be the same (and the
328 increment equal to zero). The :ref:`firewall <hanetwork>`, `resource manager
329 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-2BEF5482-CF97-4A85-BD90-9195E41E74EF>`__
330 or user profile `IDLE_TIME
331 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-ABC7AE4D-64A8-4EA9-857D-BEF7300B64C3>`__
332 should not expire idle sessions. This avoids connection storms which can
333 decrease throughput. See `Guideline for Preventing Connection Storms: Use
334 Static Pools
361 connection pools. The values of ``min`` and ``max`` should be the same (and the
362 ``increment`` equal to zero). This avoids connection storms which can decrease
363 throughput. See `Guideline for Preventing Connection Storms: Use Static Pools
335364 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-7DFBA826-7CC0-4D16-B19C-31D168069B54>`__,
336 which contains details about sizing of pools.
365 which contains more details about sizing of pools. Having a fixed size will
366 guarantee that the database can handle the upper pool size. For example, if a
367 pool needs to grow but the database resources are limited, then
368 :meth:`SessionPool.acquire()` may return errors such as ORA-28547. With a fixed
369 pool size, this class of error will occur when the pool is created, allowing you
370 to change the size before users access the application. With a dynamically
371 growing pool, the error may occur much later after the pool has been in use for
372 some time.
337373
338374 The Real-World Performance Group also recommends keeping pool sizes small, as
339375 they may perform better than larger pools. The pool attributes should be
340376 adjusted to handle the desired workload within the bounds of available resources
341377 in cx_Oracle and the database.
378
379 Make sure the :ref:`firewall <hanetwork>`, `resource manager
380 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-2BEF5482-CF97-4A85-BD90-9195E41E74EF>`__
381 or user profile `IDLE_TIME
382 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-ABC7AE4D-64A8-4EA9-857D-BEF7300B64C3>`__
383 do not expire idle sessions, since this will require connections be recreated,
384 which will impact performance and scalability.
342385
343386 .. _sessioncallback:
344387
+1
-1
doc/src/user_guide/ha.rst less more
118118 Database technologies that record application interaction with the database and,
119119 in the event of a database instance outage, attempt to replay the interaction on
120120 a surviving database instance. If successful, users will be unaware of any
121 database issue.
121 database issue. AC and TAC are best suited for OLTP applications.
122122
123123 When AC or TAC are configured on the database service, they are transparently
124124 available to cx_Oracle applications.
+3
-2
src/cxoConnection.c less more
18521852
18531853
18541854 //-----------------------------------------------------------------------------
1855 // cxoConnection_commit()
1856 // Commit the transaction on the connection.
1855 // cxoConnection_getSodaDatabase()
1856 // Create and return a new SODA database object associated with the
1857 // connection.
18571858 //-----------------------------------------------------------------------------
18581859 static PyObject *cxoConnection_getSodaDatabase(cxoConnection *conn,
18591860 PyObject *args)