python-oracledb Module — python-oracledb 3.2.0b1 documentation (original) (raw)

1.1. Oracledb Methods

oracledb.Binary(string)

Constructs an object holding a binary (long) string value.

oracledb.clientversion()

Returns the version of the client library being used as a 5-tuple. The five values are the major version, minor version, update number, patch number, and port update number.

This function can only be called when python-oracledb is in Thick mode. Using it in Thin mode will throw an exception. SeeEnabling python-oracledb Thick mode.

This method is an extension to the DB API definition.

oracledb.connect(dsn=None, pool=None, pool_alias=None, conn_class=None, params=None, user=None, proxy_user=None, password=None, newpassword=None, wallet_password=None, access_token=None, host=None, port=1521, protocol='tcp', https_proxy=None, https_proxy_port=0, service_name=None, instance_name=None, sid=None, server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, connection_id_prefix=None, ssl_context=None, sdu=8192, pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, program=oracledb.defaults.program, machine=oracledb.defaults.machine, terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, driver_name=oracledb.defaults.driver_name, use_sni=False, thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, extra_auth_params=None, handle=0)

Constructor for creating a connection to the database. Returns aConnection Object. All parameters are optional and can be specified as keyword parameters. See Standalone Connectionsinformation about connections.

Not all parameters apply to both python-oracledb Thin and Thick modes.

Some values, such as the database host name, can be specified as parameters, as part of the connect string, and in the params object. If adsn (data source name) parameter is passed, the python-oracledb Thick mode will use the string to connect, otherwise a connection string is internally constructed from the individual parameters and params object values, with the individual parameters having precedence. In python-oracledb’s default Thin mode, a connection string is internally used that contains all relevant values specified. The precedence in Thin mode is that values in any dsn parameter override values passed as individual parameters, which themselves override values set in theparams parameter object. Similar precedence rules also apply to other values.

The dsn (data source name) parameter is an Oracle Net Services Connection String. It can also be a string in the formatuser/password@connect_string.

The pool parameter is expected to be a pool object. This parameter was deprecated in python-oracledb 3.0.0. UseConnectionPool.acquire() instead since the use of this parameter is the equivalent of calling this method.

The pool_alias parameter is expected to be a string which indicates the name of the previously created pool in the connection pool cache from which to acquire the connection. This is identical to calling ConnectionPool.acquire(). When pool_alias is used,connect() supports the same parameters asacquire() and has the same behavior.

The conn_class parameter is expected to be Connection or a subclass of Connection.

The params parameter is expected to be of type ConnectParams and contains connection parameters that will be used when establishing the connection. If this parameter is not specified, the additional keyword parameters will be used to internally create an instance of ConnectParams. If both the params parameter and additional keyword parameters are specified, the values in the keyword parameters have precedence. Note that if a dsn is also supplied in python-oracledb Thin mode, then the values of the parameters specified (if any) within thedsn will override the values passed as additional keyword parameters, which themselves override the values set in the params parameter object.

The user parameter is expected to be a string which indicates the name of the user to connect to. This value is used in both the python-oracledb Thin and Thick modes.

The proxy_user parameter is expected to be a string which indicates the name of the proxy user to connect to. If this value is not specified, it will be parsed out of user if user is in the form “user[proxy_user]”. This value is used in both the python-oracledb Thin and Thick modes.

The password parameter expected to be a string which indicates the password for the user. This value is used in both the python-oracledb Thin and Thick modes.

The newpassword parameter is expected to be a string which indicates the new password for the user. The new password will take effect immediately upon a successful connection to the database. This value is used in both the python-oracledb Thin and Thick modes.

The wallet_password parameter is expected to be a string which indicates the password to use to decrypt the PEM-encoded wallet, if it is encrypted. This value is only used in python-oracledb Thin mode. Thewallet_password parameter is not needed for cwallet.sso files that are used in the python-oracledb Thick mode.

The access_token parameter is expected to be a string or a 2-tuple or a callable. If it is a string, it specifies an Azure AD OAuth2 token used for Open Authorization (OAuth 2.0) token based authentication. If it is a 2-tuple, it specifies the token and private key strings used for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based authentication. If it is a callable, it returns either a string or a 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is useful when the pool needs to expand and create new connections but the current authentication token has expired. This value is used in both the python-oracledb Thin and Thick modes.

The host parameter is expected to be a string which specifies the name or IP address of the machine hosting the listener, which handles the initial connection to the database. This value is used in both the python-oracledb Thin and Thick modes.

The port parameter is expected to be an integer which indicates the port number on which the listener is listening. The default value is_1521_. This value is used in both the python-oracledb Thin and Thick modes.

The protocol parameter is expected to be one of the strings tcp or_tcps_ which indicates whether to use unencrypted network traffic or encrypted network traffic (TLS). The default value is tcp. This value is used in both the python-oracledb Thin and Thick modes.

The https_proxy parameter is expected to be a string which indicates the name or IP address of a proxy host to use for tunneling secure connections. This value is used in both the python-oracledb Thin and Thick modes.

The https_proxy_port parameter is expected to be an integer which indicates the port that is to be used to communicate with the proxy host. The default value is 0. This value is used in both the python-oracledb Thin and Thick modes.

The service_name parameter is expected to be a string which indicates the service name of the database. This value is used in both the python-oracledb Thin and Thick modes.

The instance_name parameter is expected to be a string which indicates the instance name of the database. This value is used in both the python-oracledb Thin and Thick modes.

The sid parameter is expected to be a string which indicates the SID of the database. It is recommended to use service_name instead. This value is used in both the python-oracledb Thin and Thick modes.

The server_type parameter is expected to be a string that indicates the type of server connection that should be established. If specified, it should be one of dedicated, shared, or pooled. This value is used in both the python-oracledb Thin and Thick modes.

The cclass parameter is expected to be a string that identifies the connection class to use for Database Resident Connection Pooling (DRCP). This value is used in both the python-oracledb Thin and Thick modes.

The purity parameter is expected to be one of theoracledb.PURITY_* constants that identifies the purity to use for DRCP. This value is used in both the python-oracledb Thin and Thick modes. The purity will internally default toPURITY_SELF for pooled connections. For standalone connections, the purity will internally default toPURITY_NEW.

The expire_time parameter is expected to be an integer which indicates the number of minutes between the sending of keepalive probes. If this parameter is set to a value greater than zero it enables keepalive. This value is used in both the python-oracledb Thin and Thick modes. The default value is 0.

The retry_count parameter is expected to be an integer that identifies the number of times that a connection attempt should be retried before the attempt is terminated. This value is used in both the python-oracledb Thin and Thick modes. The default value is 0.

The retry_delay parameter is expected to be an integer that identifies the number of seconds to wait before making a new connection attempt. This value is used in both the python-oracledb Thin and Thick modes. The default value is 1.

The tcp_connect_timeout parameter is expected to be a float that indicates the maximum number of seconds to wait for establishing a connection to the database host. This value is used in both the python-oracledb Thin and Thick modes. The default value is 20.0.

The ssl_server_dn_match parameter is expected to be a boolean that indicates whether the server certificate distinguished name (DN) should be matched in addition to the regular certificate verification that is performed. Note that if the ssl_server_cert_dn parameter is not provided, host name matching is performed instead. This value is used in both the python-oracledb Thin and Thick modes. The default value is True.

The ssl_server_cert_dn parameter is expected to be a string that indicates the distinguished name (DN) which should be matched with the server. This value is ignored if the ssl_server_dn_match parameter is not set to the value True. This value is used in both the python-oracledb Thin and Thick modes.

The wallet_location parameter is expected to be a string that identifies the directory where the wallet can be found. In python-oracledb Thin mode, this must be the directory of the PEM-encoded wallet file, ewallet.pem. In python-oracledb Thick mode, this must be the directory of the file, cwallet.sso. This value is used in both the python-oracledb Thin and Thick modes.

The events parameter is expected to be a boolean that specifies whether the events mode should be enabled. This value is only used in the python-oracledb Thick mode and is ignored in the Thin mode. This parameter is needed for continuous query notification and high availability event notifications. The default value is False.

The externalauth parameter is a boolean that specifies whether external authentication should be used. This value is only used in the python-oracledb Thick mode and is ignored in the Thin mode. The default value is False. For standalone connections, external authentication occurs when the user and password attributes are not used. If these attributes are not used, you can optionally set the externalauthattribute to True, which may aid code auditing.

If the mode parameter is specified, it must be one of theconnection authorization modeswhich are defined at the module level. This value is used in both the python-oracledb Thin and Thick modes. The default value isoracledb.AUTH_MODE_DEFAULT.

The disable_oob parameter is expected to be a boolean that indicates whether out-of-band breaks should be disabled. This value is only used in the python-oracledb Thin mode and has no effect on Windows which does not support this functionality. The default value is False.

The stmtcachesize parameter is expected to be an integer which specifies the initial size of the statement cache. This value is used in both the python-oracledb Thin and Thick modes. The default is the value ofdefaults.stmtcachesize.

The edition parameter is expected to be a string that indicates the edition to use for the connection. It requires Oracle Database 11.2, or later. This parameter cannot be used simultaneously with the cclassparameter.

The tag parameter is expected to be a string that identifies the type of connection that should be returned from a pool. This value is only used in the python-oracledb Thick mode and is ignored in the Thin mode.

The matchanytag parameter is expected to be a boolean specifying whether any tag can be used when acquiring a connection from the pool. This value is only used in the python-oracledb Thick mode when acquiring a connection from a pool. This value is ignored in the python-oracledb Thin mode. The default value is False.

The config_dir parameter is expected to be a string that indicates the directory in which optional configuration files are found. The default is the value of defaults.config_dir.

The appcontext parameter is expected to be a list of 3-tuples that identifies the application context used by the connection. This parameter should contain namespace, name, and value and each entry in the tuple should be a string.

The shardingkey parameter and supershardingkey parameters, if specified, are expected to be a sequence of values which identifies the database shard to connect to. The key values can be a list of strings, numbers, bytes, or dates. These values are only used in the python-oracledb Thick mode and are ignored in the Thin mode. SeeConnecting to Oracle Globally Distributed Database.

The debug_jdwp parameter is expected to be a string with the formathost=;port= that specifies the host and port of the PL/SQL debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug PL/SQL code called by python-oracledb. This value is only used in the python-oracledb Thin mode. For python-oracledb Thick mode, set theORA_DEBUG_JDWP environment variable which has the same syntax. For more information, see Application Tracing.

The connection_id_prefix parameter is expected to be a string and is added to the beginning of the generated connection_id that is sent to the database for tracing. This value is only used in the python-oracledb Thin mode.

The ssl_context parameter is expected to be an SSLContext object which is used for connecting to the database using TLS. This SSL context will be modified to include the private key or any certificates found in a separately supplied wallet. This parameter should only be specified if the default SSLContext object cannot be used. This value is only used in the python-oracledb Thin mode.

The sdu parameter is expected to be an integer that returns the requested size of the Session Data Unit (SDU), in bytes. The value tunes internal buffers used for communication to the database. Bigger values can increase throughput for large queries or bulk data loads, but at the cost of higher memory use. The SDU size that will actually be used is negotiated down to the lower of this value and the database network SDU configuration value. See the Database Net Services documentation for more details. This value is used in both the python-oracledb Thin and Thick modes. The default value is 8192 bytes.

The pool_boundary parameter is expected to be one of the strings_statement_ or transaction which indicates when pooled DRCPor PRCP connections can be returned to the pool. If the value is_statement_, then pooled DRCP or PRCP connections are implicitly released back to the DRCP or PRCP pool when the connection is stateless (that is, there are no active cursors, active transactions, temporary tables, or temporary LOBs). If the value is transaction, then pooled DRCP or PRCP connections are implicitly released back to the DRCP or PRCP pool when either one of the methods Connection.commit() orConnection.rollback() are called. This parameter requires the use of DRCP or PRCP with Oracle Database 23ai (or later). SeeImplicit Connection Pooling for more information. This value is used in both the python-oracledb Thin and Thick modes.

The use_tcp_fast_open parameter is expected to be a boolean which indicates whether to use TCP Fast Open which is an Oracle Autonomous Database Serverless (ADB-S) specific feature that can reduce the latency in round-trips to the database after a connection has been established. This feature is only available with certain versions of ADB-S. This value is used in both python-oracledb Thin and Thick modes. The default value is False.

The ssl_version parameter is expected to be one of the constants_ssl.TLSVersion.TLSv1_2_ or ssl.TLSVersion.TLSv1_3 which identifies the TLS protocol version used. These constants are defined in the Pythonssl module. This parameter can be specified when establishing connections with the protocol_tcps_. This value is used in both python-oracledb Thin and Thick modes. The value ssl.TLSVersion.TLSv1_3 requires Oracle Database 23ai. If you are using python-oracledb Thick mode, Oracle Client 23ai is additionally required.

The use_sni parameter is expected to be a boolean which indicates whether to use the TLS Server Name Indication (SNI) extension to bypass the second TLS negotiation that would otherwise be required. This parameter is used in both python-oracledb Thin and Thick modes. This parameter requires Oracle Database 23.7. The default value is False. See the Database Net Services documentation for more details.

The program parameter is expected to be a string which specifies the name of the executable program or application connected to Oracle Database. This value is only used in the python-oracledb Thin mode. The default is the value of defaults.program.

The machine parameter is expected to be a string which specifies the machine name of the client connecting to Oracle Database. This value is only used in the python-oracledb Thin mode. The default is the value ofdefaults.machine.

The terminal parameter is expected to be a string which specifies the terminal identifier from which the connection originates. This value is only used in the python-oracledb Thin mode. The default is the value ofdefaults.terminal.

The osuser parameter is expected to be a string which specifies the operating system user that initiates the database connection. This value is only used in the python-oracledb Thin mode. The default value is the value of defaults.osuser.

The driver_name parameter is expected to be a string which specifies the driver used by the client to connect to Oracle Database. This value is used in both the python-oracledb Thin and Thick modes. The default is the value of defaults.driver_name.

The thick_mode_dsn_passthrough parameter is expected to be a boolean which indicates whether the connect string should be passed unchanged to the Oracle Client libraries for parsing when using python-oracledb Thick mode. If this parameter is set to False in Thick mode, connect strings are parsed by python-oracledb itself and a generated connect descriptor is sent to the Oracle Client libraries. This value is only used in the python-oracledb Thick mode. The default value is the value ofdefaults.thick_mode_dsn_passthrough. For more information, seeUsing Optional Oracle Configuration Files.

The extra_auth_params parameter is expected to be a dictionary containing the configuration parameters necessary for Oracle Database authentication using OCI or Azure cloud native authentication plugins. This value is used in both the python-oracledb Thin and Thick modes. SeeToken-Based Authentication.

If the handle parameter is specified, it must be of type OCISvcCtx* and is only of use when embedding Python in an application (like PowerBuilder) which has already made the connection. The connection thus created should never be used after the source handle has been closed or destroyed. This value is only used in the python-oracledb Thick mode and is ignored in the Thin mode. It should be used with extreme caution. The default value is 0.

Changed in version 3.0.0: The pool_alias, instance_name, use_sni,thick_mode_dsn_passthrough, and extra_auth_params parameters were added. The pool parameter was deprecated: useConnectionPool.acquire() instead.

Changed in version 2.5.0: The program, machine, terminal, osuser, anddriver_name parameters were added. Support for edition andappcontext was added to python-oracledb Thin mode.

Changed in version 2.3.0: The default value of the retry_delay parameter was changed from 0 seconds to 1 second. The default value of the tcp_connect_timeoutparameter was changed from 60.0 seconds to 20.0 seconds. Thessl_version parameter was added.

Changed in version 2.1.0: The pool_boundary and use_tcp_fast_open parameters were added.

Changed in version 2.0.0: The ssl_context and sdu parameters were added.

Changed in version 1.4.0: The connection_id_prefix parameter was added.

oracledb.connect_async(dsn=None, pool=None, pool_alias=None, conn_class=None, params=None, user=None, proxy_user=None, password=None, newpassword=None, wallet_password=None, access_token=None, host=None, port=1521, protocol='tcp', https_proxy=None, https_proxy_port=0, service_name=None, instance_name=None, sid=None, server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, connection_id_prefix=None, ssl_context=None, sdu=8192, pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, program=oracledb.defaults.program, machine=oracledb.defaults.machine, terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, driver_name=oracledb.defaults.driver_name, use_sni=False, thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, extra_auth_params=None, handle=0)

Constructor for creating a connection to the database. Returns anAsyncConnection Object. All parameters are optional and can be specified as keyword parameters. SeeStandalone Connections information about connections.

This method can only be used in python-oracledb Thin mode.

When connecting to Oracle Autonomous Database, use Python 3.11, or later.

Added in version 2.0.0.

Some values, such as the database host name, can be specified as parameters, as part of the connect string, and in the params object. The precedence is that values in the dsn parameter override values passed as individual parameters, which themselves override values set in the params parameter object. Similar precedence rules also apply to other values.

The dsn (data source name) parameter is an Oracle Net Services Connection String. It can also be a string in the formatuser/password@connect_string.

The pool parameter is expected to be an AsyncConnectionPool object. This parameter was deprecated in python-oracledb 3.0.0. UseAsyncConnectionPool.acquire() instead since the use of this parameter is the equivalent of calling this method.

The pool_alias parameter is expected to be a string which indicates the name of the previously created pool in the connection pool cache from which to acquire the connection. This is identical to calling AsyncConnectionPool.acquire(). When pool_alias is used,connect_async() supports the same parameters asacquire() and has the same behavior.

The conn_class parameter is expected to be AsyncConnection or a subclass of AsyncConnection.

The params parameter is expected to be of type ConnectParams and contains connection parameters that will be used when establishing the connection. If this parameter is not specified, the additional keyword parameters will be used to create an instance of ConnectParams. If both the params parameter and additional keyword parameters are specified, the values in the keyword parameters have precedence. Note that if a dsn is also supplied, then the values of the parameters specified (if any) within the dsn will override the values passed as additional keyword parameters, which themselves override the values set in the params parameter object.

The user parameter is expected to be a string which indicates the name of the user to connect to.

The password parameter expected to be a string which indicates the password for the user.

The newpassword parameter is expected to be a string which indicates the new password for the user. The new password will take effect immediately upon a successful connection to the database.

The wallet_password parameter is expected to be a string which indicates the password to use to decrypt the PEM-encoded wallet, if it is encrypted.

The host parameter is expected to be a string which specifies the name or IP address of the machine hosting the listener, which handles the initial connection to the database.

The port parameter is expected to be an integer which indicates the port number on which the listener is listening. The default value is_1521_.

The protocol parameter is expected to be one of the strings tcp or_tcps_ which indicates whether to use unencrypted network traffic or encrypted network traffic (TLS). The default value is tcp.

The https_proxy parameter is expected to be a string which indicates the name or IP address of a proxy host to use for tunneling secure connections.

The https_proxy_port parameter is expected to be an integer which indicates the port that is to be used to communicate with the proxy host. The default value is 0.

The service_name parameter is expected to be a string which indicates the service name of the database.

The instance_name parameter is expected to be a string which indicates the instance name of the database.

The sid parameter is expected to be a string which indicates the SID of the database. It is recommended to use service_name instead.

The server_type parameter is expected to be a string that indicates the type of server connection that should be established. If specified, it should be one of dedicated, shared, or pooled.

The cclass parameter is expected to be a string that identifies the connection class to use for Database Resident Connection Pooling (DRCP).

The purity parameter is expected to be one of theoracledb.PURITY_* constants that identifies the purity to use for DRCP. The purity will internally default toPURITY_SELF for pooled connections. For standalone connections, the purity will internally default toPURITY_NEW.

The retry_count parameter is expected to be an integer that identifies the number of times that a connection attempt should be retried before the attempt is terminated. The default value is 0.

The retry_delay parameter is expected to be an integer that identifies the number of seconds to wait before making a new connection attempt. The default value is 1.

The tcp_connect_timeout parameter is expected to be a float that indicates the maximum number of seconds to wait for establishing a connection to the database host. The default value is 20.0.

The events parameter is ignored in the python-oracledb Thin mode.

The externalauth parameter is ignored in the python-oracledb Thin mode.

If the mode parameter is specified, it must be one of theconnection authorization modeswhich are defined at the module level. The default value isoracledb.AUTH_MODE_DEFAULT.

The disable_oob parameter is expected to be a boolean that indicates whether out-of-band breaks should be disabled. This value has no effect on Windows which does not support this functionality. The default value is_False_.

The stmtcachesize parameter is expected to be an integer which specifies the initial size of the statement cache. The default is the value of defaults.stmtcachesize.

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

The matchanytag parameter is ignored in the python-oracledb Thin mode.

The config_dir parameter is expected to be a string that indicates the directory in which optional configuration files are found. The default is the value of defaults.config_dir.

The shardingkey parameter and supershardingkey parameters are ignored in the python-oracledb Thin mode.

The connection_id_prefix parameter is expected to be a string and is added to the beginning of the generated connection_id that is sent to the database for tracing.

The ssl_context parameter is expected to be an SSLContext object used for connecting to the database using TLS. This SSL context will be modified to include the private key or any certificates found in a separately supplied wallet. This parameter should only be specified if the default SSLContext object cannot be used.

The pool_boundary parameter is expected to be one of the strings_statement_ or transaction which indicates when pooled DRCPor PRCP connections can be returned to the pool. If the value is_statement_, then pooled DRCP or PRCP connections are implicitly released back to the DRCP or PRCP pool when the connection is stateless (that is, there are no active cursors, active transactions, temporary tables, or temporary LOBs). If the value is transaction, then pooled DRCP or PRCP connections are implicitly released back to the DRCP or PRCP pool when either one of the methods AsyncConnection.commit() orAsyncConnection.rollback() are called. This parameter requires the use of DRCP or PRCP with Oracle Database 23ai (or later). SeeImplicit Connection Pooling for more information. This value is used in both the python-oracledb Thin and Thick modes.

The thick_mode_dsn_passthrough and handle parameters are ignored in python-oracledb Thin mode.

Changed in version 2.5.0: The program, machine, terminal, osuser, anddriver_name parameters were added. Support for edition andappcontext was added.

Changed in version 2.1.0: The pool_boundary and use_tcp_fast_open parameters were added.

Changed in version 2.0.0: The ssl_context and sdu parameters were added.

Changed in version 1.4.0: The connection_id_prefix parameter was added.

oracledb.ConnectParams(user=None, proxy_user=None, password=None, newpassword=None, wallet_password=None, access_token=None, host=None, port=1521, protocol='tcp', https_proxy=None, https_proxy_port=0, service_name=None, instance_name=None, sid=None, server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, connection_id_prefix=None, ssl_context=None, sdu=8192, pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, program=oracledb.defaults.program, machine=oracledb.defaults.machine, terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, driver_name=oracledb.defaults.driver_name, use_sni=False, thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, extra_auth_params=None, handle=0)

Contains all the parameters that can be used to establish a connection to the database.

Creates and returns a ConnectParams Object. The object can be passed to oracledb.connect().

All the parameters are optional.

The user parameter is expected to be a string which indicates the name of the user to connect to. This value is used in both the python-oracledb Thin and Thick modes.

The password parameter expected to be a string which indicates the password for the user. This value is used in both the python-oracledb Thin and Thick modes.

The service_name parameter is expected to be a string which indicates the service name of the database. This value is used in both the python-oracledb Thin and Thick modes.

The instance_name parameter is expected to be a string which indicates the instance name of the database. This value is used in both the python-oracledb Thin and Thick modes.

The purity parameter is expected to be one of theoracledb.PURITY_* constants that identifies the purity to use for DRCP. This value is used in both the python-oracledb Thin and Thick modes. The purity will internally default toPURITY_SELF for pooled connections . For standalone connections, the purity will internally default toPURITY_NEW.

The events parameter is expected to be a boolean that specifies whether the events mode should be enabled. This value is only used in the python-oracledb Thick mode. This parameter is needed for continuous query notification and high availability event notifications. The default value is False.

The externalauth parameter is a boolean that specifies whether external authentication should be used. This value is only used in the python-oracledb Thick mode. The default value is False. For standalone connections, external authentication occurs when the user andpassword attributes are not used. If these attributes are not used, you can optionally set the externalauth attribute to True, which may aid code auditing.

The mode parameter is expected to be an integer that identifies the authorization mode to use. This value is used in both the python-oracledb Thin and Thick modes.The default value isoracledb.AUTH_MODE_DEFAULT.

The stmtcachesize parameter is expected to be an integer that identifies the initial size of the statement cache. This value is used in both the python-oracledb Thin and Thick modes. The default is the value ofdefaults.stmtcachesize.

The tag parameter is expected to be a string that identifies the type of connection that should be returned from a pool. This value is only used in the python-oracledb Thick mode.

The config_dir parameter is expected to be a string that indicates the directory in which the tnsnames.ora configuration file is located.

The debug_jdwp parameter is expected to be a string with the formathost=;port= that specifies the host and port of the PL/SQL debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug PL/SQL code invoked by python-oracledb. This value is only used in the python-oracledb Thin mode. For python-oracledb Thick mode, set theORA_DEBUG_JDWP environment variable which has the same syntax. For more information, see Application Tracing.

The ssl_version parameter is expected to be one of the constants_ssl.TLSVersion.TLSv1_2_ or ssl.TLSVersion.TLSv1_3 which identifies the TLS protocol version used. These constants are defined in the Pythonssl module. This parameter can be specified when establishing connections with the protocol “tcps”. This value is used in both python-oracledb Thin and Thick modes. The value ssl.TLSVersion.TLSv1_3 requires Oracle Database 23ai. If you are using python-oracledb Thick mode, Oracle Client 23ai is additionally required.

The handle parameter is expected to be an integer which represents a pointer to a valid service context handle. This value is only used in the python-oracledb Thick mode. It should be used with extreme caution. The default value is 0.

Changed in version 3.0.0: The instance_name, use_sni, thick_mode_dsn_passthrough andextra_auth_params parameters were added.

Changed in version 2.5.0: The program, machine, terminal, osuser, anddriver_name parameters were added. Support for edition andappcontext was added to python-oracledb Thin mode.

Changed in version 2.1.0: The pool_boundary and use_tcp_fast_open parameters were added.

Changed in version 2.0.0: The ssl_context and sdu parameters were added.

Changed in version 1.4.0: The connection_id_prefix parameter was added.

oracledb.create_pipeline()

Creates a pipeline object which can be used to process a set of operations against a database.

Added in version 2.4.0.

oracledb.create_pool(dsn=None, pool_class=oracledb.ConnectionPool, pool_alias=None, params=None, min=1, max=2, increment=1, connectiontype=oracledb.Connection, getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, wait_timeout=0, max_lifetime_session=0, session_callback=None, max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, ping_timeout=5000, user=None, proxy_user=None, password=None, newpassword=None, wallet_password=None, access_token=None, host=None, port=1521, protocol='tcp', https_proxy=None, https_proxy_port=0, service_name=None, instance_name=None, sid=None, server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, connection_id_prefix=None, ssl_context=None, sdu=8192, pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, program=oracledb.defaults.program, machine=oracledb.defaults.machine, terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, driver_name=oracledb.defaults.driver_name, use_sni=False, thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, extra_auth_params=None, handle=0)

Creates a connection pool with the supplied parameters and returns theConnectionPool object for the pool. See Connection pooling for more information.

This function is the equivalent of the cx_Oracle.SessionPool()function. The use of SessionPool() has been deprecated in python-oracledb.

Not all parameters apply to both python-oracledb Thin and Thick modes.

Python-oracledb connection pools must be created, used and closed within the same process. Sharing pools or connections across processes has unpredictable behavior. Using connection pools in multi-threaded architectures is supported. Multi-process architectures that cannot be converted to threading may get some benefit from Database Resident Connection Pooling (DRCP).

In python-oracledb Thick mode, connection pooling is handled by Oracle’sSession pooling technology. This allows python-oracledb applications to support features likeApplication Continuity.

The user, password, and dsn parameters are the same as fororacledb.connect().

The pool_class parameter is expected to be aConnectionPool Object or a subclass of ConnectionPool.

The pool_alias parameter is expected to be a string representing the name used to store and reference the pool in the python-oracledb connection pool cache. If this parameter is not specified, then the pool will not be added to the cache. The value of this parameter can be used with theoracledb.get_pool() and oracledb.connect() methods to access the pool. See Using the Connection Pool Cache.

The params parameter is expected to be of type PoolParams and contains parameters that are used to create the pool. If this parameter is not specified, the additional keyword parameters will be used to create an instance of PoolParams. If both the params parameter and additional keyword parameters are specified, the values in the keyword parameters have precedence. Note that if a dsn is also supplied, then in the python-oracledb Thin mode, the values of the parameters specified (if any) within the dsn will override the values passed as additional keyword parameters, which themselves override the values set in theparams parameter object.

The min, max and increment parameters control pool growth behavior. A fixed pool size where min equals max isrecommended to help prevent connection storms and to help overall system stability. The min parameter is the number of connections opened when the pool is created. The default value of themin parameter is 1. The increment parameter is the number of connections that are opened whenever a connection request exceeds the number of currently open connections. The default value of theincrement parameter is 1. The max parameter is the maximum number of connections that can be open in the connection pool. The default value of the max parameter is 2.

If the connectiontype parameter is specified, all calls toConnectionPool.acquire() will create connection objects of that type, rather than the base type defined at the module level.

The getmode parameter determines the behavior ofConnectionPool.acquire(). One of the constantsoracledb.POOL_GETMODE_WAIT, oracledb.POOL_GETMODE_NOWAIT,oracledb.POOL_GETMODE_FORCEGET, ororacledb.POOL_GETMODE_TIMEDWAIT. The default value isoracledb.POOL_GETMODE_WAIT.

The homogeneous parameter is a boolean that indicates whether the connections are homogeneous (same user) or heterogeneous (multiple users). The default value is True.

The timeout parameter is the length of time (in seconds) that a connection may remain idle in the pool before it is terminated. This applies only when the pool has more than min connections open, allowing it to shrink to the specified minimum size. The default value is _0_seconds. A value of 0 means there is no limit.

The wait_timeout parameter is the length of time (in milliseconds) that a caller should wait when acquiring a connection from the pool withgetmode set to oracledb.POOL_GETMODE_TIMEDWAIT. The default value is 0 milliseconds.

The max_lifetime_session parameter is the length of time (in seconds) that a pooled connection may exist since first being created. The default value is 0. A value of 0 means that there is no limit. Connections become candidates for termination when they are acquired or released back to the pool and have existed for longer than max_lifetime_sessionseconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 or later must be used and, prior to Oracle Client 21, cleanup only occurs when the pool is accessed.

The session_callback parameter is a callable that is invoked when a connection is returned from the pool for the first time, or when the connection tag differs from the one requested.

The max_sessions_per_shard parameter is the maximum number of connections that may be associated with a particular shard. This value is only used in the python-oracledb Thick mode and is ignored in the python-oracledb Thin mode. The default value is 0.

The soda_metadata_cache parameter is a boolean that indicates whether or not the SODA metadata cache should be enabled. This value is only used in the python-oracledb Thick mode and is ignored in the python-oracledb Thin mode. The default value is False.

The ping_interval parameter is the length of time (in seconds) after which an unused connection in the pool will be a candidate for pinging whenConnectionPool.acquire() is called. If the ping to the database indicates the connection is not alive a replacement connection will be returned by acquire(). If ping_interval is a negative value, then the ping functionality will be disabled. The default value is 60 seconds.

The ping_timeout parameter is the maximum length of time (in milliseconds) that ConnectionPool.acquire() waits for a connection to respond to any internal ping to the database. If the ping does not respond within the specified time, then the connection is destroyed andacquire() returns a different connection. This value is used in both the python-oracledb Thin and Thick modes. The default value is 5000 milliseconds.

The service_name parameter is expected to be a string which indicates the service name of the database. This value is used in both the python-oracledb Thin and Thick modes.

The instance_name parameter is expected to be a string which indicates the instance name of the database. This value is used in both the python-oracledb Thin and Thick modes.

The externalauth parameter is a boolean that determines whether to use external authentication. This value is only used in python-oracledb Thick mode and is ignored in Thin mode. The default value is False. For pooled connections in Thick mode, external authentication requires the use of a heterogeneous pool. For this reason, you must set the homogeneousparameter to False. See Connecting Using External Authentication.

The config_dir parameter is expected to be a string that indicates the directory in which the tnsnames.ora configuration file is located. The default is the value of defaults.config_dir.

The debug_jdwp parameter is expected to be a string with the formathost=;port= that specifies the host and port of the PL/SQL debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug PL/SQL code invoked by python-oracledb. This value is only used in the python-oracledb Thin mode. For python-oracledb Thick mode, set theORA_DEBUG_JDWP environment variable which has the same syntax. For more information, see Application Tracing.

The ssl_version parameter is expected to be one of the constants_ssl.TLSVersion.TLSv1_2_ or ssl.TLSVersion.TLSv1_3 which identifies the TLS protocol version used. These constants are defined in the Pythonssl module. This parameter can be specified when establishing connections with the protocol “tcps”. This value is used in both python-oracledb Thin and Thick modes. The value ssl.TLSVersion.TLSv1_3 requires Oracle Database 23ai. If you are using python-oracledb Thick mode, Oracle Client 23ai is additionally required.

The thick_mode_dsn_passthrough parameter is expected to be a boolean which indicates whether the connect string should be passed unchanged to the Oracle Client libraries for parsing when using python-oracledb Thick mode. If this parameter is set to False in Thick mode, connect strings are parsed by python-oracledb itself and a generated connect descriptor is sent to the Oracle Client libraries. This value is only used in the python-oracledb Thick mode. The default value isdefaults.thick_mode_dsn_passthrough. For more information, seeUsing Optional Oracle Configuration Files.

Changed in version 3.0.0: The pool_alias, instance_name, use_sni,thick_mode_dsn_passthrough, and extra_auth_params parameters were added.

Changed in version 2.5.0: The program, machine, terminal, osuser, anddriver_name parameters were added. Support for edition andappcontext was added to python-oracledb Thin mode.

Changed in version 2.3.0: The default value of the retry_delay parameter was changed from _0_seconds to 1 second. The default value of the tcp_connect_timeoutparameter was changed from 60.0 seconds to 20.0 seconds. Theping_timeout and ssl_version parameters were added.

Changed in version 2.1.0: The pool_boundary and use_tcp_fast_open parameters were added.

Changed in version 2.0.0: The ssl_context and sdu parameters were added.

Changed in version 1.4.0: The connection_id_prefix parameter was added.

oracledb.create_pool_async(dsn=None, pool_class=oracledb.AsyncConnectionPool, pool_alias=None, params=None, min=1, max=2, increment=1, connectiontype=oracledb.AsyncConnection, getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, wait_timeout=0, max_lifetime_session=0, session_callback=None, max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, ping_timeout=5000, user=None, proxy_user=None, password=None, newpassword=None, wallet_password=None, access_token=None, host=None, port=1521, protocol='tcp', https_proxy=None, https_proxy_port=0, service_name=None, instance_name=None, sid=None, server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, connection_id_prefix=None, ssl_context=None, sdu=8192, pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, program=oracledb.defaults.program, machine=oracledb.defaults.machine, terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, driver_name=oracledb.defaults.driver_name, use_sni=False, thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, extra_auth_params=None, handle=0)

Creates a connection pool with the supplied parameters and returns theAsyncConnectionPool object for the pool.create_pool_async() is a synchronous method. SeeConnection pooling for more information.

This method can only be used in python-oracledb Thin mode.

When connecting to Oracle Autonomous Database, use Python 3.11, or later.

Added in version 2.0.0.

The user, password, and dsn parameters are the same as fororacledb.connect().

The pool_class parameter is expected to be anAsyncConnectionPool Object or a subclass of AsyncConnectionPool.

The pool_alias parameter is expected to be a string representing the name used to store and reference the pool in the python-oracledb connection pool cache. If this parameter is not specified, then the pool will not be added to the cache. The value of this parameter can be used with theoracledb.get_pool() and oracledb.connect_async() methods to access the pool. See Using the Connection Pool Cache.

The params parameter is expected to be of type PoolParams and contains parameters that are used to create the pool. If this parameter is not specified, the additional keyword parameters will be used to create an instance of PoolParams. If both the params parameter and additional keyword parameters are specified, the values in the keyword parameters have precedence. Note that if a dsn is also supplied, then the values of the parameters specified (if any) within the dsn will override the values passed as additional keyword parameters, which themselves override the values set in the params parameter object.

If the connectiontype parameter is specified, all calls toAsyncConnectionPool.acquire() will create connection objects of that type, rather than the base type defined at the module level.

The getmode parameter determines the behavior ofAsyncConnectionPool.acquire(). One of the constantsoracledb.POOL_GETMODE_WAIT, oracledb.POOL_GETMODE_NOWAIT,oracledb.POOL_GETMODE_FORCEGET, ororacledb.POOL_GETMODE_TIMEDWAIT. The default value isoracledb.POOL_GETMODE_WAIT.

The homogeneous parameter is a boolean that indicates whether the connections are homogeneous (same user) or heterogeneous (multiple users). The default value is True.

The session_callback parameter is a callable that is invoked when a connection is returned from the pool for the first time, or when the connection tag differs from the one requested.

The max_sessions_per_shard parameter is ignored in the python-oracledb Thin mode.

The soda_metadata_cache parameter is ignored in the python-oracledb Thin mode.

The ping_interval parameter is the length of time (in seconds) after which an unused connection in the pool will be a candidate for pinging whenAsyncConnectionPool.acquire() is called. If the ping to the database indicates the connection is not alive a replacement connection will be returned by acquire(). Ifping_interval is a negative value, then the ping functionality will be disabled. The default value is 60 seconds.

The ping_timeout parameter is the maximum length of time (in milliseconds) that AsyncConnectionPool.acquire() waits for a connection to respond to any internal ping to the database. If the ping does not respond within the specified time, then the connection is destroyed and acquire() returns a different connection. This value is used in both the python-oracledb Thin and Thick modes. The default value is 5000 milliseconds.