17. API: AsyncConnection Objects

17.1. AsyncConnection Class

class oracledb.AsyncConnection(dsn: str, pool: AsyncConnectionPool, params: ConnectParams, kwargs: dict)

Constructor for creating an asynchronous connection to the database.

An AsyncConnection object should be created with oracledb.connect_async() or with AsyncConnectionPool.acquire(). AsyncConnections support use of concurrent programming with asyncio.

This object is an extension to the DB API definition.

Added in version 2.0.0.

Note

AsyncConnection objects are only supported in python-oracledb Thin mode.

Note

Any outstanding database transaction will be rolled back when the connection object is destroyed or closed. You must perform a commit first if you want data to persist in the database, see Managing Transactions Using Asynchronous Methods.

17.2. AsyncConnection Methods

async AsyncConnection.__aenter__(): The entry point for the asynchronous connection as a context manager. It returns itself.

async AsyncConnection.__aexit__(*exc_info): The exit point for the asynchronous connection as a context manager. This will close the connection and roll back any uncommitted transaction.

async AsyncConnection.begin_sessionless_transaction(transaction_id: str | bytes | None = None, timeout: int = 60, defer_round_trip: bool = False) → bytes

Begins a new sessionless transaction. This method returns the transaction identifier specified by the user or generated by python-oracledb.

The transaction_id parameter should be of type string or bytes. If specified, it represents a unique identifier for the transaction. If a string is passed, then it will be UTF-8 encoded to bytes. If this value is not specified, then python-oracledb generates a a random universally-unique identifier (UUID) value when this function is called. An example is “36b8f84d-df4e-4d49-b662-bcde71a8764f”. The user-chosen value cannot exceed 64 bytes in length.

The timeout parameter is the number of seconds that this transaction can stay suspended when suspend_sessionless_transaction() is later called, or if the transaction is automatically suspended when the suspend_on_success parameter is set to to True in AsyncCursor.execute() or AsyncCursor.executemany(). The default value is 60 seconds. If a transaction is not resumed within this specified duration, the transaction will be rolled back.

The defer_round_trip parameter is a boolean that determines whether the request to start a transaction is to be sent immediately or with the next database operation. If set to False, the request is sent immediately. If set to True, the request is included with the next database operation on the connection. The default value is False.

See Sessionless Transactions.

Added in version 3.3.0.

async AsyncConnection.callfunc(name: str, return_type: Any, parameters: list | tuple | None = None, keyword_parameters: dict | None = None) → Any

Calls a PL/SQL function with the given name.

This is a shortcut for calling cursor(), AsyncCursor.callfunc(), and then AsyncCursor.close().

async AsyncConnection.callproc(name: str, parameters: list | tuple | None = None, keyword_parameters: dict | None = None) → list

Calls a PL/SQL procedure with the given name.

This is a shortcut for calling cursor(), AsyncCursor.callproc(), and then AsyncCursor.close().

AsyncConnection.cancel() → None: Breaks a long-running statement.

async AsyncConnection.changepassword(old_password: str, new_password: str) → None: Changes the password for the user to which the connection is connected.

async AsyncConnection.close() → None: Closes the connection.

Note

Asynchronous connections are not automatically closed at the end of scope. This is different to synchronous connection behavior. Asynchronous connections should either be explicitly closed, or have been initially created via a context manager with block.

async AsyncConnection.commit() → None: Commits any pending transaction to the database.

async AsyncConnection.createlob(lob_type: DbType, data: str | bytes | None = None) → AsyncLOB: Creates and returns a new temporary LOB of the specified type.

AsyncConnection.cursor(scrollable: bool = False) → AsyncCursor: Returns an AsyncCursor object associated with the connection.

AsyncConnection.decode_oson(data: bytes) → Any: Decodes OSON-encoded bytes and returns the object encoded in those bytes. This is useful for fetching columns which have the check constraint IS JSON FORMAT OSON enabled.

Added in version 2.1.0.

async AsyncConnection.direct_path_load(schema_name: str, table_name: str, column_names: list[str], data: Any, *, batch_size: int = 2**32 - 1) → None

Load data into Oracle Database using the Direct Path Load interface. It is available only in python-oracledb Thin mode.

The data parameter can be a list of sequences, a DataFrame, or a third-party DataFrame instance that supports the Apache Arrow PyCapsule Interface.

The batch_size parameter is used to split large data sets into smaller pieces for sending to the database. It is the number of records in each batch. This parameter can be used to tune performance.

See Direct Path Loads.

Added in version 3.4.0.

This method is an extension to the DB API definition.

AsyncConnection.encode_oson(value: Any) → bytes: Encodes a Python value into OSON-encoded bytes and returns them. This is useful for inserting into columns which have the check constraint IS JSON FORMAT OSON enabled.

Added in version 2.1.0.

async AsyncConnection.execute(statement: str, parameters: list | tuple | dict | None = None) → None

Executes a statement against the database.

This is a shortcut for calling cursor(), AsyncCursor.execute(), and then AsyncCursor.close()

async AsyncConnection.executemany(statement: str | None, parameters: Any) → None

Executes a SQL statement once using all bind value mappings or sequences found in the sequence parameters. This can be used to insert, update, or delete multiple rows in a table with a single python-oracledb call. It can also invoke a PL/SQL procedure multiple times.

The parameters parameter can be a list of tuples, where each tuple item maps to one bind variable placeholder in statement. It can also be a list of dictionaries, where the keys match the bind variable placeholder names in statement. If there are no bind values, or values have previously been bound, the parameters value can be an integer specifying the number of iterations.

This is a shortcut for calling cursor(), AsyncCursor.executemany(), and then AsyncCursor.close().

Executes a query and returns all of the rows.

The default value for arraysize is oracledb.defaults.arraysize.

Internally, this method’s AsyncCursor.prefetchrows size is set to the value of the explicit or default arraysize parameter value.

This is a shortcut for calling cursor(), AsyncCursor.fetchall(), and then AsyncCursor.close().

Changed in version 3.4.0: The fetch_lobs and fetch_decimals parameters were added.

Fetches all rows of the SQL query statement, returning them in a DataFrame object. An empty DataFrame is returned if there are no rows available.

The parameters parameter can be a list of tuples, where each tuple item maps to one bind variable placeholder in statement. It can also be a list of dictionaries, where the keys match the bind variable placeholder names in statement.

The arraysize parameter can be specified to tune performance of fetching data across the network. It defaults to oracledb.defaults.arraysize. Internally, the fetch_df_all()’s Cursor.prefetchrows size is always set to the value of the explicit or default arraysize parameter value.

The fetch_decimals parameter specifies whether to return decimal values when fetching columns of type NUMBER that are capable of being represented in Apache Arrow Decimal128 format. The default value is oracledb.defaults.fetch_decimals.

The requested_schema parameter specifies an object that implements the Apache Arrow PyCapsule schema interface. The DataFrame returned by fetch_df_all() will have the data types and names of the schema.

See Working with Data Frames for the supported data types and examples.

Changed in version 3.4.0: The fetch_decimals and requested_schema parameters were added.

Added in version 3.0.0.

This returns an iterator yielding the next size rows of the SQL query statement in each iteration as a DataFrame object. An empty DataFrame is returned if there are no rows available.

The parameters parameter can be a list of tuples, where each tuple item maps to one bind variable placeholder in statement. It can also be a list of dictionaries, where the keys match the bind variable placeholder names in statement.

The size parameter controls the number of records fetched in each batch. It defaults to oracledb.defaults.arraysize. Internally, the fetch_df_batches()’s Cursor.arraysize and Cursor.prefetchrows sizes are always set to the value of the explicit or default size parameter value.

The fetch_decimals parameter specifies whether to return decimal values when fetching columns of type NUMBER that are capable of being represented in Arrow Decimal128 format. The default value is oracledb.defaults.fetch_decimals.

The requested_schema parameter specifies an object that implements the Apache Arrow PyCapsule schema interface. The DataFrame returned by fetch_df_all() will have the data types and names of the schema.

See Working with Data Frames for the supported data types and examples.

Changed in version 3.4.0: The fetch_decimals and requested_schema parameters were added.

Added in version 3.0.0.

Executes a query and returns up to the specified number of rows.

The default value for num_rows is the value of oracledb.defaults.arraysize.

Internally, this method’s AsyncCursor.prefetchrows size is set to the value of the explicit or default num_rows parameter, allowing all rows to be fetched in one round-trip

Since only one fetch is performed for a query, consider adding a FETCH NEXT clause to the statement to prevent the database processing rows that will never be fetched, see Limiting Rows.

This a shortcut for calling cursor(), AsyncCursor.fetchmany(), and then AsyncCursor.close().

Changed in version 3.4.0: The fetch_lobs and fetch_decimals parameters were added.

Executes a query and returns the first row of the result set if one exists (or None if no rows exist).

Internally, this method’s Cursor.prefetchrows and Cursor.arraysize sizes will be set to 1.

Since only one fetch is performed for a query, consider adding a WHERE condition or using a FETCH NEXT clause in the statement to prevent the database processing rows that will never be fetched, see Limiting Rows.

This a shortcut for calling cursor(), AsyncCursor.fetchone(), and then AsyncCursor.close().

Changed in version 3.4.0: The fetch_lobs and fetch_decimals parameters were added.

async AsyncConnection.gettype(name: str) → DbObjectType: Returns a type object given its name. This can then be used to create objects which can be bound to cursors created by this connection.

AsyncConnection.is_healthy() → bool

This function returns a boolean indicating the health status of a connection.

Connections may become unusable in several cases, such as, if the network socket is broken, if an Oracle error indicates the connection is unusable, or, after receiving a planned down notification from the database.

This function is best used before starting a new database request on an existing standalone connections. For pooled connections, the ConnectionPool.acquire() method internally performs this check before returning a connection to the application, see Pool Connection Health.

If this function returns False, the connection should be not be used by the application and a new connection should be established instead.

This function performs a local check. To fully check a connection’s health, use ping() which performs a round-trip to the database.

Returns an object specifying the properties of messages used in advanced queuing.

Each of the parameters are optional. If specified, they act as a shortcut for setting each of the equivalently named properties.

Added in version 3.1.0.

async AsyncConnection.ping(): Pings the database to verify if the connection is valid.

AsyncConnection.queue(name: str, payload_type: DbObjectType | str | None = None, *, payloadType: DbObjectType | None = None) → Queue | AsyncQueue

Creates a queue which is used to enqueue and dequeue messages in Advanced Queuing.

The name parameter is expected to be a string identifying the queue in which messages are to be enqueued or dequeued.

The payload_type parameter, if specified, is expected to be an object type that identifies the type of payload the queue expects. If the string “JSON” is specified, JSON data is enqueued and dequeued. If not specified, RAW data is enqueued and dequeued.

For consistency and compliance with the PEP 8 naming style, the parameter payloadType was renamed to payload_type. The old name will continue to work as a keyword parameter for a period of time.

Added in version 3.1.0.

async AsyncConnection.resume_sessionless_transaction(transaction_id: str | bytes, timeout: int = 60, defer_round_trip: bool = False) → bytes

Resumes an existing sessionless transaction using the specified transaction identifier. This method returns the transaction identifier used to resume the sessionless transaction.

The transaction_id parameter should be a string or bytes value that uniquely identifies an existing sessionless transaction that is to be resumed.

The timeout parameter is the number of seconds that the current connection waits to resume a transaction if another connection is using it. When defer_round_trip is set to False, the wait happens in the resume_sessionless_transaction() call itself, and the function blocks until the transaction becomes available or the timeout expires. When defer_round_trip is set to True, the resume is deferred and the wait occurs at the time of the next database operation instead. At the start of the wait period, if the transaction is not in use by any other connection, the resume happens immediately. If the transaction remains in use by the other connection after the timeout period, the error ORA-25351 is raised. If another connection completes the transaction, the error ORA-24756 is raised. These error messages are only thrown for non-RAC instances. For information on using Oracle RAC, see Sessionless Transactions with Oracle RAC. The default value is 60 seconds.

The defer_round_trip parameter is a boolean that determines whether the request to resume a transaction is to be sent immediately or with the next database operation. If set to False, the request is sent immediately. If set to True, the request is included with the next database operation on the connection. The default value is False.

See Sessionless Transactions.

Added in version 3.3.0.

async AsyncConnection.rollback() → None: Rolls back any pending transaction.

async AsyncConnection.run_pipeline(pipeline: Pipeline, continue_on_error: bool = False) → list[PipelineOpResult]

Runs all of the operations in the pipeline and returns a list of PipelineOpResult, each entry corresponding to an operation executed in the pipeline.

The continue_on_error parameter determines whether operations should continue to run after an error has occurred. If this parameter is set to True, then the PipelineOpResult.error attribute will be populated with an _Error instance which identifies the error that occurred. If this parameter is set to False, then an exception will be raised as soon as an error is detected and all subsequent operations will be terminated. The default value is False.

See Pipelining Database Operations for more information.

Note

True pipelining requires Oracle Database 26ai, or later.

When you connect to an older database, operations are sequentially executed by python-oracledb. Each operation concludes before the next is sent to the database. There is no reduction in round-trips and no performance benefit. This usage is only recommended for code portability such as when preparing for a database upgrade.

Added in version 2.4.0.

async AsyncConnection.suspend_sessionless_transaction() → None

Suspends the currently active sessionless transaction immediately.

This detaches the transaction from the connection, allowing it to be resumed later with the transaction identifier that was specified during creation of the sessionless transaction. The timeout previously passed to AsyncConnection.begin_sessionless_transaction() determines how long the transaction can stay suspended before it is automatically rolled back.

See Sessionless Transactions.

Added in version 3.3.0.

async AsyncConnection.tpc_begin(xid: Xid, flags: int = oracledb.TPC_BEGIN_NEW, timeout: int = 0) → None

Begins a Two-Phase Commit (TPC) on a global transaction using the specified transaction identifier (xid).

The xid parameter should be an object returned by the xid() method.

The flags parameter is one of the constants oracledb.TPC_BEGIN_JOIN, oracledb.TPC_BEGIN_NEW, oracledb.TPC_BEGIN_PROMOTE, or oracledb.TPC_BEGIN_RESUME. The default is oracledb.TPC_BEGIN_NEW.

The timeout parameter is the number of seconds to wait for a transaction to become available for resumption when TPC_BEGIN_RESUME is specified in the flags parameter. When TPC_BEGIN_NEW is specified in the flags parameter, the timeout parameter indicates the number of seconds the transaction can be inactive before it is automatically terminated by the system. A transaction is inactive between the time it is detached with AsyncConnection.tpc_end() and the time it is resumed with AsyncConnection.tpc_begin().The default is 0 seconds.

The following code sample demonstrates the tpc_begin() function:

x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
await connection.tpc_begin(xid=x, flags=oracledb.TPC_BEGIN_NEW, timeout=30)

See Using Two-Phase Commits (TPC) for information on TPC.

Added in version 2.3.0.

async AsyncConnection.tpc_commit(xid: Xid | None = None, one_phase: bool = False) → None

Commits a global transaction. When called with no arguments, this method commits a transaction previously prepared with tpc_begin() and optionally prepared with tpc_prepare(). If tpc_prepare() is not called, a single phase commit is performed. A transaction manager may choose to do this if only a single resource is participating in the global transaction.

If an xid parameter is passed, then an object should be returned by the xid() function. This form should be called outside of a transaction and is intended for use in recovery.

The one_phase parameter is a boolean identifying whether to perform a one-phase or two-phase commit. If one_phase parameter is True, a single-phase commit is performed. The default value is False. This parameter is only examined if a value is provided for the xid parameter. Otherwise, the driver already knows whether tpc_prepare() was called for the transaction and whether a one-phase or two-phase commit is required.

The following code sample demonstrates the tpc_commit() function:

x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
await connection.tpc_commit(xid=x, one_phase=False)

See Using Two-Phase Commits (TPC) for information on TPC.

Added in version 2.3.0.

async AsyncConnection.tpc_end(xid: Xid | None = None, flags: int = oracledb.TPC_END_NORMAL) → None

Ends or suspends work on a global transaction. This function is only intended for use by transaction managers.

If an xid parameter is passed, then an object should be returned by the xid() function. If no xid parameter is passed, then the transaction identifier used by the previous tpc_begin() is used.

The flags parameter is one of the constants oracledb.TPC_END_NORMAL or oracledb.TPC_END_SUSPEND. The default is oracledb.TPC_END_NORMAL.

If the flag is oracledb.TPC_END_SUSPEND then the transaction may be resumed later by calling AsyncConnection.tpc_begin() with the flag oracledb.TPC_BEGIN_RESUME.

The following code sample demonstrates the tpc_end() function:

x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
await connection.tpc_end(xid=x, flags=oracledb.TPC_END_NORMAL)

See Using Two-Phase Commits (TPC) for information on TPC.

Added in version 2.3.0.

async AsyncConnection.tpc_forget(xid: Xid) → None

Causes the database to forget a heuristically completed TPC transaction. This function is only intended to be called by transaction managers.

The xid parameter is mandatory and should be an object should be returned by the xid() function.

The following code sample demonstrates the tpc_forget() function:

x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
await connection.tpc_forget(xid=x)

See Using Two-Phase Commits (TPC) for information on TPC.

Added in version 2.3.0.

async AsyncConnection.tpc_prepare(xid: Xid | None = None) → bool

Prepares a two-phase transaction for commit. After this function is called, no further activity should take place on this connection until either tpc_commit() or tpc_rollback() have been called.

Returns a boolean indicating whether a commit is needed or not. If you attempt to commit when not needed, then it results in the error ORA-24756: transaction does not exist.

If an xid parameter is passed, then an object should be returned by the xid() function. If an xid parameter is not passed, then the transaction identifier used by the previous tpc_begin() is used.

The following code sample demonstrates the tpc_prepare() function:

x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
await connection.tpc_prepare(xid=x)

See Using Two-Phase Commits (TPC) for information on TPC.

Added in version 2.3.0.

async AsyncConnection.tpc_recover() → list

Returns a list of pending transaction identifiers that require recovery. Objects of type Xid (as returned by the xid() function) are returned and these can be passed to tpc_commit() or tpc_rollback() as needed.

This function queries the view DBA_PENDING_TRANSACTIONS and requires SELECT privilege on that view.

The following code sample demonstrates the tpc_recover() function:

await connection.tpc_recover()

See Using Two-Phase Commits (TPC) for information on TPC.

Added in version 2.3.0.

async AsyncConnection.tpc_rollback(xid: Xid | None = None) → None

Rolls back a global transaction.

If an xid parameter is not passed, then it rolls back the transaction that was previously started with tpc_begin().

If an xid parameter is passed, then an object should be returned by xid() and the specified transaction is rolled back. This form should be called outside of a transaction and is intended for use in recovery.

The following code sample demonstrates the tpc_rollback() function:

x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
await connection.tpc_rollback(xid=x)

See Using Two-Phase Commits (TPC) for information on TPC.

Added in version 2.3.0.

AsyncConnection.xid(format_id: int, global_transaction_id: bytes | str, branch_qualifier: bytes | str) → Xid

Returns a global transaction identifier (xid) that can be used with the Two-Phase Commit (TPC) functions.

The xid contains a format identifier, a global transaction identifier, and a branch identifier. There are no checks performed at the Python level. The values are checked by ODPI-C when they are passed to the relevant functions. .. When this functionality is also supported in the thin driver the checks will be performed at the Python level as well.

The format_id parameter should be a positive 32-bit integer. This value identifies the format of the global_transaction_id and branch_qualifier parameters and the value is determined by the Transaction Manager (TM), if one is in use.

The global_transaction_id and branch_qualifier parameters should be of type bytes or string. If a value of type string is passed, then this value will be UTF-8 encoded to bytes. The values cannot exceed 64 bytes in length.

17.3. AsyncConnection Attributes

property AsyncConnection.action: str: This write-only attribute sets the ACTION column in the V$SESSION view. It is a string attribute but the value None is accepted and treated as an empty string.

property AsyncConnection.autocommit: bool: This read-write attribute determines whether autocommit mode is on or off. When autocommit mode is on, all statements are committed as soon as they have completed executing.

property AsyncConnection.call_timeout: int

This read-write attribute specifies the amount of time (in milliseconds) that a single round-trip to the database may take before a timeout will occur. A value of 0 means that no timeout will take place.

In python-oracledb Thick mode, this attribute is only available in Oracle Client 18c or later.

If a timeout occurs, the error DPI-1067 will be returned if the connection is still usable. Alternatively the error DPI-1080 will be returned if the connection has become invalid and can no longer be used.

For consistency and compliance with the PEP 8 naming style, the attribute callTimeout was renamed to call_timeout. The old name will continue to work for a period of time. The error DPI-1080 was also introduced in this release.

property AsyncConnection.client_identifier: str: This write-only attribute sets the CLIENT_IDENTIFIER column in the V$SESSION view.

property AsyncConnection.clientinfo: str: This write-only attribute sets the CLIENT_INFO column in the V$SESSION view.

property AsyncConnection.current_schema: str: This read-write attribute sets the current schema attribute for the session. Setting this value is the same as executing the SQL statement ALTER SESSION SET CURRENT_SCHEMA. The attribute is set (and verified) on the next call that does a round trip to the server. The value is placed before unqualified database objects in SQL statements you then execute.

property AsyncConnection.db_domain: str: This read-only attribute specifies the Oracle Database domain name associated with the connection. It is the same value returned by the SQL SELECT value FROM V$PARAMETER WHERE NAME = 'db_domain'.

property AsyncConnection.db_name: str: This read-only attribute specifies the Oracle Database name associated with the connection. It is the same value returned by the SQL SELECT NAME FROM V$DATABASE.

property AsyncConnection.dbop: str: This write-only attribute sets the database operation that is to be monitored. This can be viewed in the DBOP_NAME column of the V$SQL_MONITOR view.

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

property AsyncConnection.econtext_id: str: This write-only attribute specifies the execution context id. This value can be found as the ECID column in the V$SESSION view and ECONTEXT_ID in the auditing tables. The maximum length is 64 bytes.

property AsyncConnection.edition: str: This read-only attribute gets the session edition and is only available with Oracle Database 11.2, or later.

property AsyncConnection.external_name: str: This read-write attribute specifies the external name that is used by the connection when logging distributed transactions.

property AsyncConnection.inputtypehandler: Callable: This read-write attribute specifies a method called for each value that is bound to a statement executed on any cursor associated with this connection. The method signature is handler(cursor, value, arraysize) and the return value is expected to be a variable object or None in which case a default variable object will be created. If this attribute is None, the default behavior will take place for all values bound to statements.

property AsyncConnection.instance_name: str: This read-only attribute specifies the Oracle Database instance name associated with the connection. It is the same value as the SQL expression sys_context('userenv', 'instance_name').

property AsyncConnection.internal_name: str: This read-write attribute specifies the internal name that is used by the connection when logging distributed transactions.

property AsyncConnection.ltxid: bytes

This read-only attribute returns the logical transaction id for the connection. It is used within Oracle Transaction Guard as a means of ensuring that transactions are not duplicated. See Transaction Guard for more information.

This is only available with Oracle Database 12.1 or later. In python-oracledb Thick mode, it also requires Oracle Client libraries 12.1 or later.

property AsyncConnection.max_identifier_length: int: This read-only attribute specifies the maximum database identifier length in bytes supported by the database to which the connection has been established. See Database Object Naming Rules. The value may be None, 30, or 128. The value None indicates the size cannot be reliably determined by python-oracledb, which occurs when using Thick mode with Oracle Client libraries 12.1 (or older) to connect to Oracle Database 12.2, or later.

Added in version 2.5.0.

property AsyncConnection.max_open_cursors: int: This read-only attribute specifies the maximum number of cursors that the database can have open concurrently. It is the same value returned by the SQL SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'. When using python-oracledb Thick mode, Oracle Client libraries 12.1 (or later) are required.

property AsyncConnection.module: str: This write-only attribute sets the MODULE column in the V$SESSION view. The maximum length for this string is 48 and if you exceed this length you will get ORA-24960.

property AsyncConnection.outputtypehandler: Callable

This read-write attribute specifies a method called for each column that is going to be fetched from any cursor associated with this connection. The method signature is handler(cursor, metadata) and the return value is expected to be a variable object or None in which case a default variable object will be created. If this attribute is None, the default behavior will take place for all columns fetched from cursors.

See Changing Fetched Data Types with Output Type Handlers.

property AsyncConnection.sdu: int: This read-only attribute specifies the size of the Session Data Unit (SDU) that is being used by the connection. The value will be the lesser of the requested python-oracledb size and the maximum size allowed by the database network configuration. It is available only in python-oracledb Thin mode. To set the SDU in Thick mode, use a connection string SDU parameter or set a value for DEFAULT_SDU_SIZE in a sqlnet.ora configuration file.

property AsyncConnection.serial_num: int

This read-only attribute specifies the session serial number associated with the connection. It is the same value returned by the SQL SELECT SERIAL# FROM V$SESSION WHERE SID=SYS_CONTEXT('USERENV', 'SID'). It is available only in python-oracledb Thin mode.

For applications using Database Resident Connection Pooling (DRCP), the serial_num attribute may not contain the current session state until a round-trip is made to the database after acquiring a session. It is recommended to not use this attribute if your application uses DRCP but may not perform a round-trip.

Added in version 2.5.0.

property AsyncConnection.service_name: str: This read-only attribute specifies the Oracle Database service name associated with the connection. This is the same value returned by the SQL SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL.

property AsyncConnection.session_id: int

This read-only attribute specifies the session identifier associated with the connection. It is the same value returned by the SQL SELECT SYS_CONTEXT('USERENV', 'SID') FROM DUAL. It is available only in python-oracledb Thin mode.

For applications using Database Resident Connection Pooling (DRCP), the session_id attribute may not contain the current session state until a round-trip is made to the database after acquiring a session. It is recommended to not use this attribute if your application uses DRCP but may not perform a round-trip.

Added in version 2.5.0.

property AsyncConnection.stmtcachesize: int

This read-write attribute specifies the size of the statement cache. This value can make a significant difference in performance if you have a small number of statements that you execute repeatedly.

The default value is 20.

See Statement Caching for more information.

property AsyncConnection.thin: bool: This read-only attribute returns a boolean indicating if python-oracledb is in Thin mode (True) or Thick mode (False).

property AsyncConnection.transaction_in_progress: bool: This read-only attribute specifies whether a transaction is currently in progress on the database associated with the connection.

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

property AsyncConnection.version: str: This read-only attribute returns the version of the database to which a connection has been established.