19. Deprecated and Desupported Features

The following tables contain the deprecated and desupported features of the python-oracledb API, and the replacement to be used instead, if applicable. The desupported API feature is a previous deprecation that has been removed and is no longer available in python-oracledb. The most recent deprecated and desupported features are listed first.

Table 19.1 Desupported in python-oracledb 2.0
Name	Comments
`oracledb.__future__.old_json_col_as_obj`	VARCHAR2 and LOB columns created with the `IS JSON` check constraint are now always fetched as JSON. Use an output type handler if the old behavior is required.
Parameters `encoding` and `nencoding` of `oracledb.connect()` and `oracledb.create_pool()`, and the related attributes on the objects created	The driver encodings are always UTF-8. Remove uses of `encoding` and `nencoding` from your code.
Parameter `threaded` of `oracledb.connect()` and `oracledb.create_pool()`	Threading is always used. Remove uses of `threaded` from your code.
Parameter `waitTimeout` of `oracledb.create_pool()` and `oracledb.SessionPool()`	Replace with parameter `wait_timeout`
Parameter `maxLifetimeSession` of `oracledb.create_pool()` and `oracledb.SessionPool()`	Replace with parameter `max_lifetime_session`
Parameter `sessionCallback` of `oracledb.create_pool()` and `oracledb.SessionPool()`	Replace with parameter `session_callback`
Parameter `maxSessionsPerShard` of `oracledb.create_pool()` and `oracledb.SessionPool()`	Replace with parameter `max_sessions_per_shard`
Attribute `maxBytesPerCharacter` of the connection object	The driver encodings are always UTF-8 so this attribute can be replaced by the constant value 4
`Connection.tnsentry`	Replace with `Connection.dsn`
`SessionPool.tnsentry`	Replace with `ConnectionPool.dsn`

Table 19.2 Deprecated in python-oracledb 2.0
Name	Comments
Calling `Variable.setvalue()` with a string value when the variable type is one of `oracledb.DB_TYPE_BLOB`, `oracledb.DB_TYPE_CLOB` or `oracledb.DB_TYPE_NCLOB`.	Call `Connection.createlob()` with the value instead and pass the result to `Variable.setvalue()`.
Setting an attribute of type `oracledb.DB_TYPE_BLOB`, `oracledb.DB_TYPE_CLOB` or `oracledb.DB_TYPE_NCLOB` on a database object to a string value.	Call `Connection.createlob()` with the value instead and set the attribute with the result.

Table 19.3 Deprecated in python-oracledb 1.4
Name	Comments
Output type handler with arguments `handler(cursor, name, default_type, length, precision, scale)`	Replace with `handler(cursor, metadata)`. See Changing Fetched Data Types with Output Type Handlers.

Table 19.4 Deprecated in python-oracledb 1.0
Name	Comments
SessionPool class and use of cx_Oracle.SessionPool()	Replace by the equivalent ConnectionPool Class. Use the new method `oracledb.create_pool()` to create connection pools.
`Connection.begin()`	Replace by the new Two-Phase Commits (TPC) functionality.
`Connection.prepare()`	Replace by the new Two-Phase Commits (TPC) functionality.
Parameters `encoding` and `nencoding` of the `oracledb.connect()`, `oracledb.create_pool()` and `oracledb.SessionPool()` methods	The encodings in use are always UTF-8.
Parameter `threaded` of the `oracledb.connect()` method	This was used to allow the Oracle Client libraries to support threaded applications. This value is ignored in python-oracledb because the threaded OCI is always enabled in the Thick mode, and the option is not relevant to the Thin mode. The equivalent parameter was already deprecated for cx_Oracle.SessionPool() in cx_Oracle 8.2.
Attribute `Connection.maxBytesPerCharacter` of the Connection object	This was previously deprecated. In python-oracledb 1.0 it will return a constant value of 4 since encodings are always UTF-8.
Size argument, `numRows` of the `Cursor.fetchmany()` method	Rename the parameter to `size`.
cx_Oracle.makedsn()	Pass the connection string components as connection creation, or pool creation, parameters. Or use a ConnectParams Class object.
oracledb.Connection()	This method is no longer recommended for creating connections. Use the equivalent function `oracledb.connect()` instead.
Attribute `Cursor.bindarraysize` of the Cursor object	Remove this attribute since it is no longer needed.
Constant `ATTR_PURITY_DEFAULT`	Replace by `PURITY_DEFAULT`.
Constant `ATTR_PURITY_NEW`	Replace by `PURITY_NEW`.
Constant `ATTR_PURITY_SELF`	Replace by `PURITY_SELF`.
Constant `SPOOL_ATTRVAL_WAIT`	Replace by `POOL_GETMODE_WAIT`.
Constant `SPOOL_ATTRVAL_NOWAIT`	Replace by `POOL_GETMODE_NOWAIT`.
Constant `SPOOL_ATTRVAL_FORCEGET`	Replace by `POOL_GETMODE_FORCEGET`.
Constant `SPOOL_ATTRVAL_TIMEDWAIT`	Replace by `POOL_GETMODE_TIMEDWAIT`.
Constant `DEFAULT_AUTH`	Replace by `AUTH_MODE_DEFAULT`.
Constant `SYSASM`	Replace by `AUTH_MODE_SYSASM`.
Constant `SYSBKP`	Replace by `AUTH_MODE_SYSBKP`.
Constant `SYSDBA`	Replace by `AUTH_MODE_SYSDBA`.
Constant `SYSDGD`	Replace by `AUTH_MODE_SYSDGD`.
Constant `SYSKMT`	Replace by `AUTH_MODE_SYSKMT`.
Constant `SYSOPER`	Replace by `AUTH_MODE_SYSOPER`.
Constant `SYSRAC`	Replace by `AUTH_MODE_SYSRAC`.
Constant `PRELIM_AUTH`	Replace by `AUTH_MODE_PRELIM`.
Constant `SUBSCR_PROTO_OCI`	Replace by `SUBSCR_PROTO_CALLBACK`.
Class name ObjectType	Replace by the equivalent DbObjectType.
Class name Object	Replace by the equivalent DbObject.

Many of the usages deprecated in cx_Oracle (see tables below) are still supported by python-oracledb to ease upgrade from cx_Oracle. However, these previous cx_Oracle deprecation announcements remain in force for python-oracledb. The relevant functionality may be removed in a future version of python-oracledb.

Some of the previous deprecations that have been removed and are not available in python-oracledb are listed below:

Table 19.5 Desupported in python-oracledb 1.0
Name	Comments
Cursor.fetchraw()	Use one of the other fetch methods such as `Cursor.fetchmany()` instead.
Cursor.executemanyprepared()	Use `Cursor.executemany()` instead.
Previously deprecated Advanced Queuing (AQ) API	Use the new AQ API instead. AQ is only available in the python-oracledb Thick mode.
Connection.deq()	Replace with `Queue.deqone()` or `Queue.deqmany()`
Connection.deqoptions()	Replace with `Queue.deqoptions`
Connection.enq()	Replace with `Queue.enqone()` or `Queue.enqmany()`
Connection.enqoptions()	Replace with `Queue.enqoptions`

Table 19.6 Deprecated in cx_Oracle 8.2
Name	Comments
`encoding` parameter to cx_Oracle.connect()	No longer needed as the use of encodings other than UTF-8 is deprecated. Encoding is handled internally between python-oracledb and Oracle Database.
`nencoding` parameter to cx_Oracle.connect()	No longer needed as the use of encodings other than UTF-8 is deprecated.
`encoding` parameter to cx_Oracle.SessionPool()	No longer needed as the use of encodings other than UTF-8 is deprecated.
`nencoding` parameter to cx_Oracle.SessionPool()	No longer needed as the use of encodings other than UTF-8 is deprecated.
Connection.maxBytesPerCharacter	No longer needed as the use of encodings other than UTF-8 is deprecated. The constant value 4 can be used instead.
Positional parameters to cx_Oracle.connect()	Replace with keyword parameters in order to comply with the Python database API.
Positional parameters to cx_Oracle.SessionPool()	Replace with keyword parameters in order to comply with the Python database API.
`threaded` parameter to cx_Oracle.SessionPool()	The value of this parameter is ignored. Threading is now always used.
`waitTimeout` parameter to cx_Oracle.SessionPool()	Replace with parameter name `wait_timeout`
`maxLifetimeSession` parameter to cx_Oracle.SessionPool()	Replace with parameter name `max_lifetime_session`
`sessionCallback` parameter to cx_Oracle.SessionPool()	Replace with parameter name `session_callback`
`maxSessionsPerShard` parameter to cx_Oracle.SessionPool()	Replace with parameter name `max_sessions_per_shard`
`SessionPool.tnsentry`	Replace with `ConnectionPool.dsn`
`payloadType` parameter to Connection.queue()	Replace with parameter name `payload_type` if using keyword parameters.
`ipAddress` parameter to Connection.subscribe()	Replace with parameter name `ip_address`
`groupingClass` parameter to Connection.subscribe()	Replace with parameter name `grouping_class`
`groupingValue` parameter to Connection.subscribe()	Replace with parameter name `grouping_value`
`groupingType` parameter to Connection.subscribe()	Replace with parameter name `grouping_type`
`clientInitiated` parameter to Connection.subscribe()	Replace with parameter name `client_initiated`
`Connection.callTimeout`	Replace with Connection.call_timeout
`Connection.tnsentry`	Replace with `Connection.dsn`
keywordParameters parameter to Cursor.callfunc()	Replace with parameter name `keyword_parameters`
`keywordParameters` parameter to Cursor.callproc()	Replace with parameter name `keyword_parameters`
`encodingErrors` parameter to Cursor.var()	Replace with parameter name `encoding_errors`
`Cursor.fetchraw()`	Replace with Cursor.fetchmany()
`newSize` parameter to LOB.trim()	Replace with parameter name `new_size`
`Queue.deqMany`	Replace with Queue.deqmany()
`Queue.deqOne`	Replace with Queue.deqone()
`Queue.enqMany`	Replace with Queue.enqmany()
`Queue.enqOne`	Replace with Queue.enqone()
`Queue.deqOptions`	Replace with Queue.deqoptions
`Queue.enqOptions`	Replace with Queue.enqoptions
`Queue.payloadType`	Replace with Queue.payload_type
`Subscription.ipAddress`	Replace with Subscription.ip_address
`Message.consumerName`	Replace with Message.consumer_name
`Message.queueName`	Replace with Message.queue_name
`Variable.actualElements`	Replace with Variable.actual_elements
`Variable.bufferSize`	Replace with Variable.buffer_size
`Variable.numElements`	Replace with Variable.num_elements

Table 19.7 Deprecated in cx_Oracle 8.0
Name	Comments
`cx_Oracle.BFILE`	Replace with cx_Oracle.DB_TYPE_BFILE
`cx_Oracle.BLOB`	Replace with cx_Oracle.DB_TYPE_BLOB
`cx_Oracle.BOOLEAN`	Replace with cx_Oracle.DB_TYPE_BOOLEAN
`cx_Oracle.CLOB`	Replace with cx_Oracle.DB_TYPE_CLOB
`cx_Oracle.CURSOR`	Replace with cx_Oracle.DB_TYPE_CURSOR
`cx_Oracle.FIXED_CHAR`	Replace with cx_Oracle.DB_TYPE_CHAR
`cx_Oracle.FIXED_NCHAR`	Replace with cx_Oracle.DB_TYPE_NCHAR
`cx_Oracle.INTERVAL`	Replace with cx_Oracle.DB_TYPE_INTERVAL_DS
`cx_Oracle.LONG_BINARY`	Replace with cx_Oracle.DB_TYPE_LONG_RAW
`cx_Oracle.LONG_STRING`	Replace with cx_Oracle.DB_TYPE_LONG
`cx_Oracle.NATIVE_FLOAT`	Replace with cx_Oracle.DB_TYPE_BINARY_DOUBLE
`cx_Oracle.NATIVE_INT`	Replace with cx_Oracle.DB_TYPE_BINARY_INTEGER
`cx_Oracle.NCHAR`	Replace with cx_Oracle.DB_TYPE_NVARCHAR
`cx_Oracle.NCLOB`	Replace with cx_Oracle.DB_TYPE_NCLOB
`cx_Oracle.OBJECT`	Replace with cx_Oracle.DB_TYPE_OBJECT
`cx_Oracle.TIMESTAMP`	Replace with cx_Oracle.DB_TYPE_TIMESTAMP

Table 19.8 Deprecated in cx_Oracle 7.2
Name	Comments
`Connection.deq()`	Replace with Queue.deqone() or Queue.deqmany().
`Connection.deqoptions()`	Replace with attribute Queue.deqoptions.
`Connection.enq()`	Replace with Queue.enqone() or Queue.enqmany().
`Connection.enqoptions()`	Replace with attribute Queue.enqoptions.

Table 19.9 Deprecated in cx_Oracle 6.4
Name	Comments
`Cursor.executemanyprepared()`	Replace with ~Cursor.executemany() with None for the statement argument and an integer for the parameters argument.