16. API: AsyncConnectionPool Objects

An AsyncConnectionPool object can be created with oracledb.create_pool_async(). This object is an extension to the DB API.

Added in version 2.0.0.

Note

AsyncConnectionPool objects are only supported in the python-oracledb Thin mode.

16.1. AsyncConnectionPool Methods

AsyncConnectionPool.acquire(user=None, password=None, cclass=None, purity=oracledb.PURITY_DEFAULT, tag=None, matchanytag=False, shardingkey=[], supershardingkey=[])

Acquires a connection from the pool and returns an asynchronous connection object.

If the pool is homogeneous, the user and password parameters cannot be specified. If they are, an exception will be raised.

The cclass parameter, if specified, should be a string corresponding to the connection class for Database Resident Connection Pooling (DRCP).

The purity parameter is expected to be one of PURITY_NEW, PURITY_SELF, or PURITY_DEFAULT.

The tag, matchanytag, shardingkey, and supershardingkey parameters are ignored in python-oracledb Thin mode.

AsyncConnectionPool.close(force=False)

Closes the pool now, rather than when the last reference to it is released, which makes it unusable for further work.

If any connections have been acquired and not released back to the pool, this method will fail unless the force parameter is set to True.

AsyncConnectionPool.drop(connection): Drops the connection from the pool which is useful if the connection is no longer usable (such as when the session is killed).

AsyncConnectionPool.release(connection, tag=None)

Releases the connection back to the pool now, rather than whenever __del__ is called. The connection will be unusable from this point forward; an Error exception will be raised if any operation is attempted with the connection. Any cursors or LOBs created by the connection will also be marked unusable and an Error exception will be raised if any operation is attempted with them.

Internally, references to the connection are held by cursor objects, LOB objects, and so on. Once all of these references are released, the connection itself will be released back to the pool automatically. Either control references to these related objects carefully or explicitly release connections back to the pool in order to ensure sufficient resources are available.

The tag parameter is ignored in python-oracledb Thin mode.

16.2. AsyncConnectionPool Attributes

AsyncConnectionPool.busy: This read-only attribute returns the number of connections currently acquired.

AsyncConnectionPool.dsn: This read-only attribute returns the TNS entry of the database to which a connection has been established.

AsyncConnectionPool.getmode: This read-write attribute determines how connections are returned from the pool. If POOL_GETMODE_FORCEGET is specified, a new connection will be returned even if there are no free connections in the pool. POOL_GETMODE_NOWAIT will raise an exception if there are no free connections are available in the pool. If POOL_GETMODE_WAIT is specified and there are no free connections in the pool, the caller will wait until a free connection is available. POOL_GETMODE_TIMEDWAIT uses the value of wait_timeout to determine how long the caller should wait for a connection to become available before returning an error.

AsyncConnectionPool.homogeneous: This read-only boolean attribute indicates whether the pool is considered homogeneous or not. If the pool is not homogeneous, different authentication can be used for each connection acquired from the pool.

AsyncConnectionPool.increment: This read-only attribute returns the number of connections that will be established when additional connections need to be created.

AsyncConnectionPool.max: This read-only attribute returns the maximum number of connections that the pool can control.

AsyncConnectionPool.max_lifetime_session: This read-write attribute returns the maximum length of time (in seconds) that a pooled connection may exist. Connections that are in use will not be closed. They become candidates for termination only when they are released back to the pool and have existed for longer than max_lifetime_session seconds. Note that termination only occurs when the pool is accessed. A value of 0 means that there is no maximum length of time that a pooled connection may exist. This attribute is only available in Oracle Database 12.1 or later.

AsyncConnectionPool.max_sessions_per_shard: This read-write attribute returns the number of sessions that can be created per shard in the pool. This attribute cannot be used in python-oracledb Thin mode.

AsyncConnectionPool.min: This read-only attribute returns the number of connections with which the connection pool was created and the minimum number of connections that will be controlled by the connection pool.

AsyncConnectionPool.name: This read-only attribute returns the name assigned to the pool by Oracle.

AsyncConnectionPool.opened: This read-only attribute returns the number of connections currently opened by the pool.

AsyncConnectionPool.ping_interval

This read-write integer attribute specifies the pool ping interval in seconds. When a connection is acquired from the pool, a check is first made to see how long it has been since the connection was put into the pool. If this idle time exceeds ping_interval, then a round-trip ping to the database is performed. If the connection is unusable, it is discarded and a different connection is selected to be returned by AsyncConnectionPool.acquire(). Setting ping_interval to a negative value disables pinging. Setting it to 0 forces a ping for every AsyncConnectionPool.acquire() and is not recommended.

Prior to cx_Oracle 8.2, the ping interval was fixed at 60 seconds.

AsyncConnectionPool.soda_metadata_cache: This read-write boolean attribute returns whether the SODA metadata cache is enabled or not. This attribute cannot be used in python-oracledb Thin mode.

AsyncConnectionPool.stmtcachesize

This read-write attribute specifies the size of the statement cache that will be used for connections obtained from the pool. Once a connection is created, that connection’s statement cache size can only be changed by setting the stmtcachesize attribute on the connection itself.

See Statement Caching for more information.

AsyncConnectionPool.thin: This attribute returns a boolean which indicates the python-oracledb mode in which the pool was created. If the value of this attribute is True, it indicates that the pool was created in the python-oracledb Thin mode. If the value of this attribute is False, it indicates that the pool was created in the python-oracledb Thick mode.

AsyncConnectionPool.timeout: This read-write attribute specifies the time (in seconds) after which idle connections will be terminated in order to maintain an optimum number of open connections. A value of 0 means that no idle connections are terminated.

AsyncConnectionPool.username: This read-only attribute returns the name of the user which established the connection to the database.

AsyncConnectionPool.wait_timeout: This read-write attribute specifies the time (in milliseconds) that the caller should wait for a connection to become available in the pool before returning with an error. This value is only used if the getmode parameter to oracledb.create_pool_async() was the value oracledb.POOL_GETMODE_TIMEDWAIT.