4. API: ConnectParams Objects

4.1. ConnectParams Class

class oracledb.ConnectParams(*, user: str | None = None, proxy_user: str | None = None, password: str | None = None, newpassword: str | None = None, wallet_password: str | None = None, access_token: str | tuple | Callable | None = None, host: str | None = None, port: int | None = None, protocol: str | None = None, https_proxy: str | None = None, https_proxy_port: int | None = None, service_name: str | None = None, instance_name: str | None = None, sid: str | None = None, server_type: str | None = None, cclass: str | None = None, purity: Purity | None = None, expire_time: int | None = None, retry_count: int | None = None, retry_delay: int | None = None, tcp_connect_timeout: float | None = None, ssl_server_dn_match: bool | None = None, ssl_server_cert_dn: str | None = None, wallet_location: str | None = None, events: bool | None = None, externalauth: bool | None = None, mode: AuthMode | None = None, disable_oob: bool | None = None, stmtcachesize: int | None = None, edition: str | None = None, tag: str | None = None, matchanytag: bool | None = None, config_dir: str | None = None, appcontext: list | None = None, shardingkey: list | None = None, supershardingkey: list | None = None, debug_jdwp: str | None = None, connection_id_prefix: str | None = None, ssl_context: Any | None = None, sdu: int | None = None, pool_boundary: str | None = None, use_tcp_fast_open: bool | None = None, ssl_version: TLSVersion | None = None, program: str | None = None, machine: str | None = None, terminal: str | None = None, osuser: str | None = None, driver_name: str | None = None, use_sni: bool | None = None, thick_mode_dsn_passthrough: bool | None = None, extra_auth_params: dict | None = None, pool_name: str | None = None, handle: int | None = None)

All parameters are optional. A brief description of each parameter follows:

  • user: the name of the database user to connect to (default: None)

  • proxy_user: 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]” (default: None)

  • password: the password for the database user (default: None)

  • newpassword: a new password for the database user. The new password will take effect immediately upon a successful connection to the database (default: None)

  • wallet_password: the password to use to decrypt the wallet, if it is encrypted. This is not the database password. For Oracle Autonomous Database this is the password created when downloading the wallet. This value is only used in python-oracledb Thin mode. (default: None)

  • access_token: a string, or a 2-tuple, or a callable. If it is a string, it specifies an Entra ID 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 (default: None)

  • host: the hostname or IP address of the machine hosting the database or the database listener (default: None)

  • port: the port number on which the database listener is listening (default: 1521)

  • protocol: one of the strings “tcp” or “tcps” indicating whether to use unencrypted network traffic or encrypted network traffic (TLS) (default: “tcp”)

  • https_proxy: the hostname or IP address of a proxy host to use for tunneling secure connections (default: None)

  • https_proxy_port: the port on which to communicate with the proxy host (default: 0)

  • service_name: the service name of the database (default: None)

  • instance_name: the instance name of the database (default: None)

  • sid: the system identifier (SID) of the database. Note using a service_name instead is recommended (default: None)

  • server_type: the type of server connection that should be established. If specified, it should be one of strings “dedicated”, “shared” or “pooled” (default: None)

  • cclass: the connection class to use for Database Resident Connection Pooling (DRCP) (default: None)

  • purity: the connection purity to use for Database Resident Connection Pooling (DRCP) (default: oracledb.PURITY_DEFAULT)

  • expire_time: the number of minutes between the sending of keepalive probes. If this parameter is set to a value greater than zero it enables keepalive (default: 0)

  • retry_count: the number of times that initial connection establishment should be retried before the connection attempt is terminated (default: 0)

  • retry_delay: the number of seconds to wait before retrying to establish a connection (default: 1)

  • tcp_connect_timeout: a float indicating the maximum number of seconds to wait when establishing a connection to the database host (default: 20.0)

  • ssl_server_dn_match: a boolean indicating 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 privided, host name matching is performed instead (default: True)

  • ssl_server_cert_dn: 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. If specified this value is used for any verfication. Otherwise the hostname will be used (default: None)

  • wallet_location: the directory where the wallet can be found. In python-oracledb Thin mode this must be the directory containing the PEM-encoded wallet file ewallet.pem. In python-oracledb Thick mode this must be the directory containing the file cwallet.sso (default: None)

  • events: a boolean specifying whether events mode should be enabled. This value is only used in python-oracledb Thick mode and is needed for continuous query notification and high availability event notifications (default: False)

  • externalauth: a boolean indicating whether to use external authentication (default: False)

  • mode: the authorization mode to use. One of the constants oracledb.AUTH_MODE_DEFAULT, oracledb.AUTH_MODE_PRELIM, oracledb.AUTH_MODE_SYSASM, oracledb.AUTH_MODE_SYSBKP, oracledb.AUTH_MODE_SYSDBA, oracledb.AUTH_MODE_SYSDGD, oracledb.AUTH_MODE_SYSKMT, oracledb.AUTH_MODE_SYSOPER, or oracledb.AUTH_MODE_SYSRAC (default: oracledb.AUTH_MODE_DEFAULT)

  • disable_oob: a boolean indicating whether out-of-band breaks should be disabled. This value is only used in python-oracledb Thin mode. It has no effect on Windows which does not support this functionality (default: False)

  • stmtcachesize: the size of the statement cache (default: oracledb.defaults.stmtcachesize)

  • edition: edition to use for the connection. This parameter cannot be used simultaneously with the cclass parameter (default: None)

  • tag: identifies the type of connection that should be returned from a pool. This value is only used in python-oracledb Thick mode (default: None)

  • matchanytag: a boolean specifying whether any tag can be used when acquiring a connection from the pool. This value is only used in python-oracledb Thick mode (default: False)

  • config_dir: a directory in which the optional tnsnames.ora configuration file is located. This value is only used in python- oracledb Thin mode. For python-oracledb Thick mode, it is used if oracledb.defaults.thick_mode_dsn_passthrough is False. Otherwise in Thick mode use the config_dir parameter of oracledb.init_oracle_client() (default: oracledb.defaults.config_dir)

  • appcontext: application context used by the connection. It should be a list of 3-tuples (namespace, name, value) and each entry in the tuple should be a string (default: None)

  • shardingkey: a list of strings, numbers, bytes or dates that identify the database shard to connect to. This value is only used in python-oracledb Thick mode (default: None)

  • supershardingkey: a list of strings, numbers, bytes or dates that identify the database shard to connect to. This value is only used in python-oracledb Thick mode (default: None)

  • debug_jdwp: a string with the format “host=<host>;port=<port>” that specifies the host and port of the PL/SQL debugger. This value is only used in python-oracledb Thin mode. For python-oracledb Thick mode set the ORA_DEBUG_JDWP environment variable (default: None)

  • connection_id_prefix: an application specific prefix that is added to the connection identifier used for tracing (default: None)

  • ssl_context: 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 (default: None)

  • sdu: 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 (default: 8192)

  • pool_boundary: one of the values “statement” or “transaction” indicating when pooled DRCP connections can be returned to the pool. This requires the use of DRCP with Oracle Database 23.4 or higher (default: None)

  • use_tcp_fast_open: a boolean indicating whether to use TCP fast open. This is an Oracle Autonomous Database Serverless (ADB-S) specific property for clients connecting from within OCI Cloud network. Please refer to the ADB-S documentation for more information (default: False)

  • ssl_version: one of the values ssl.TLSVersion.TLSv1_2 or ssl.TLSVersion.TLSv1_3 indicating which TLS version to use (default: None)

  • program: a string recorded by Oracle Database as the program from which the connection originates (default: oracledb.defaults.program)

  • machine: a string recorded by Oracle Database as the name of the machine from which the connection originates (default: oracledb.defaults.machine)

  • terminal: a string recorded by Oracle Database as the terminal identifier from which the connection originates (default: oracledb.defaults.terminal)

  • osuser: a string recorded by Oracle Database as the operating system user who originated the connection (default: oracledb.defaults.osuser)

  • driver_name: a string recorded by Oracle Database as the name of the driver which originated the connection (default: oracledb.defaults.driver_name)

  • use_sni: a boolean indicating whether to use the TLS SNI extension to bypass the second TLS neogiation that would otherwise be required (default: False)

  • thick_mode_dsn_passthrough: a boolean indicating whether to pass the connect string to the Oracle Client libraries unchanged without parsing by the driver. Setting this to False makes python-oracledb Thick and Thin mode applications behave similarly regarding connection string parameter handling and locating any optional tnsnames.ora configuration file (default: oracledb.defaults.thick_mode_dsn_passthrough)

  • extra_auth_params: a dictionary containing configuration parameters necessary for Oracle Database authentication using plugins, such as the Azure and OCI cloud-native authentication plugins (default: None)

  • pool_name: the name of the DRCP pool when using multi-pool DRCP with Oracle Database 23.4, or higher (default: None)

  • handle: an integer representing a pointer to a valid service context handle. This value is only used in python-oracledb Thick mode. It should be used with extreme caution (default: 0)

See Using the ConnectParams Builder Class for more information.

This object is an extension to the DB API definition.

Changed in version 3.2.0: The pool_name parameter was added.

Changed in version 3.0.0: The 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, and driver_name parameters were added. Support for edition and appcontext 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_timeout parameter was changed from 60.0 seconds to 20.0 seconds. The ssl_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.

4.2. ConnectParams Methods

ConnectParams.copy() → ConnectParams

Creates a copy of the ConnectParams instance and returns it.

ConnectParams.get_connect_string() → str

Returns the connection string associated with the instance.

ConnectParams.get_network_service_names() → list

Returns a list of the network service names found in the tnsnames.ora file which is inside the directory that can be identified by the attribute config_dir. If a tnsnames.ora file does not exist, then an exception is raised.

ConnectParams.parse_connect_string(connect_string: str) → None

Parses the connect string into its components and stores the parameters.

The connect string parameter can be an Easy Connect string, name-value pairs, or a simple alias which is looked up in tnsnames.ora. Parameters that are found in the connect string override any currently stored values.

ConnectParams.parse_dsn_with_credentials(dsn: str) → tuple

Parses a DSN in the form <user>/<password>@<connect_string> or in the form <user>/<password> and returns a 3-tuple containing the parsed user, password and connect string. Empty strings are returned as the value None.

Added in version 1.3.0.

ConnectParams.set(*, user: str | None = None, proxy_user: str | None = None, password: str | None = None, newpassword: str | None = None, wallet_password: str | None = None, access_token: str | tuple | Callable | None = None, host: str | None = None, port: int | None = None, protocol: str | None = None, https_proxy: str | None = None, https_proxy_port: int | None = None, service_name: str | None = None, instance_name: str | None = None, sid: str | None = None, server_type: str | None = None, cclass: str | None = None, purity: Purity | None = None, expire_time: int | None = None, retry_count: int | None = None, retry_delay: int | None = None, tcp_connect_timeout: float | None = None, ssl_server_dn_match: bool | None = None, ssl_server_cert_dn: str | None = None, wallet_location: str | None = None, events: bool | None = None, externalauth: bool | None = None, mode: AuthMode | None = None, disable_oob: bool | None = None, stmtcachesize: int | None = None, edition: str | None = None, tag: str | None = None, matchanytag: bool | None = None, config_dir: str | None = None, appcontext: list | None = None, shardingkey: list | None = None, supershardingkey: list | None = None, debug_jdwp: str | None = None, connection_id_prefix: str | None = None, ssl_context: Any | None = None, sdu: int | None = None, pool_boundary: str | None = None, use_tcp_fast_open: bool | None = None, ssl_version: TLSVersion | None = None, program: str | None = None, machine: str | None = None, terminal: str | None = None, osuser: str | None = None, driver_name: str | None = None, use_sni: bool | None = None, thick_mode_dsn_passthrough: bool | None = None, extra_auth_params: dict | None = None, pool_name: str | None = None, handle: int | None = None)

Sets the values for one or more of the parameters of a ConnectParams object. All parameters are optional. A brief description of each parameter follows:

  • user: the name of the database user to connect to

  • proxy_user: 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]”

  • password: the password for the database user

  • newpassword: a new password for the database user. The new password will take effect immediately upon a successful connection to the database

  • wallet_password: the password to use to decrypt the wallet, if it is encrypted. This is not the database password. For Oracle Autonomous Database this is the password created when downloading the wallet. This value is only used in python-oracledb Thin mode.

  • access_token: a string, or a 2-tuple, or a callable. If it is a string, it specifies an Entra ID 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

  • host: the hostname or IP address of the machine hosting the database or the database listener

  • port: the port number on which the database listener is listening

  • protocol: one of the strings “tcp” or “tcps” indicating whether to use unencrypted network traffic or encrypted network traffic (TLS)

  • https_proxy: the hostname or IP address of a proxy host to use for tunneling secure connections

  • https_proxy_port: the port on which to communicate with the proxy host

  • service_name: the service name of the database

  • instance_name: the instance name of the database

  • sid: the system identifier (SID) of the database. Note using a service_name instead is recommended

  • server_type: the type of server connection that should be established. If specified, it should be one of strings “dedicated”, “shared” or “pooled”

  • cclass: the connection class to use for Database Resident Connection Pooling (DRCP)

  • purity: the connection purity to use for Database Resident Connection Pooling (DRCP)

  • expire_time: the number of minutes between the sending of keepalive probes. If this parameter is set to a value greater than zero it enables keepalive

  • retry_count: the number of times that initial connection establishment should be retried before the connection attempt is terminated

  • retry_delay: the number of seconds to wait before retrying to establish a connection

  • tcp_connect_timeout: a float indicating the maximum number of seconds to wait when establishing a connection to the database host

  • ssl_server_dn_match: a boolean indicating 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 privided, host name matching is performed instead

  • ssl_server_cert_dn: 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. If specified this value is used for any verfication. Otherwise the hostname will be used

  • wallet_location: the directory where the wallet can be found. In python-oracledb Thin mode this must be the directory containing the PEM-encoded wallet file ewallet.pem. In python-oracledb Thick mode this must be the directory containing the file cwallet.sso

  • events: a boolean specifying whether events mode should be enabled. This value is only used in python-oracledb Thick mode and is needed for continuous query notification and high availability event notifications

  • externalauth: a boolean indicating whether to use external authentication

  • mode: the authorization mode to use. One of the constants oracledb.AUTH_MODE_DEFAULT, oracledb.AUTH_MODE_PRELIM, oracledb.AUTH_MODE_SYSASM, oracledb.AUTH_MODE_SYSBKP, oracledb.AUTH_MODE_SYSDBA, oracledb.AUTH_MODE_SYSDGD, oracledb.AUTH_MODE_SYSKMT, oracledb.AUTH_MODE_SYSOPER, or oracledb.AUTH_MODE_SYSRAC

  • disable_oob: a boolean indicating whether out-of-band breaks should be disabled. This value is only used in python-oracledb Thin mode. It has no effect on Windows which does not support this functionality

  • stmtcachesize: the size of the statement cache

  • edition: edition to use for the connection. This parameter cannot be used simultaneously with the cclass parameter

  • tag: identifies the type of connection that should be returned from a pool. This value is only used in python-oracledb Thick mode

  • matchanytag: a boolean specifying whether any tag can be used when acquiring a connection from the pool. This value is only used in python-oracledb Thick mode

  • config_dir: a directory in which the optional tnsnames.ora configuration file is located. This value is only used in python- oracledb Thin mode. For python-oracledb Thick mode, it is used if oracledb.defaults.thick_mode_dsn_passthrough is False. Otherwise in Thick mode use the config_dir parameter of oracledb.init_oracle_client()

  • appcontext: application context used by the connection. It should be a list of 3-tuples (namespace, name, value) and each entry in the tuple should be a string

  • shardingkey: a list of strings, numbers, bytes or dates that identify the database shard to connect to. This value is only used in python-oracledb Thick mode

  • supershardingkey: a list of strings, numbers, bytes or dates that identify the database shard to connect to. This value is only used in python-oracledb Thick mode

  • debug_jdwp: a string with the format “host=<host>;port=<port>” that specifies the host and port of the PL/SQL debugger. This value is only used in python-oracledb Thin mode. For python-oracledb Thick mode set the ORA_DEBUG_JDWP environment variable

  • connection_id_prefix: an application specific prefix that is added to the connection identifier used for tracing

  • ssl_context: 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

  • sdu: 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

  • pool_boundary: one of the values “statement” or “transaction” indicating when pooled DRCP connections can be returned to the pool. This requires the use of DRCP with Oracle Database 23.4 or higher

  • use_tcp_fast_open: a boolean indicating whether to use TCP fast open. This is an Oracle Autonomous Database Serverless (ADB-S) specific property for clients connecting from within OCI Cloud network. Please refer to the ADB-S documentation for more information

  • ssl_version: one of the values ssl.TLSVersion.TLSv1_2 or ssl.TLSVersion.TLSv1_3 indicating which TLS version to use

  • program: a string recorded by Oracle Database as the program from which the connection originates

  • machine: a string recorded by Oracle Database as the name of the machine from which the connection originates

  • terminal: a string recorded by Oracle Database as the terminal identifier from which the connection originates

  • osuser: a string recorded by Oracle Database as the operating system user who originated the connection

  • driver_name: a string recorded by Oracle Database as the name of the driver which originated the connection

  • use_sni: a boolean indicating whether to use the TLS SNI extension to bypass the second TLS neogiation that would otherwise be required

  • thick_mode_dsn_passthrough: a boolean indicating whether to pass the connect string to the Oracle Client libraries unchanged without parsing by the driver. Setting this to False makes python-oracledb Thick and Thin mode applications behave similarly regarding connection string parameter handling and locating any optional tnsnames.ora configuration file

  • extra_auth_params: a dictionary containing configuration parameters necessary for Oracle Database authentication using plugins, such as the Azure and OCI cloud-native authentication plugins

  • pool_name: the name of the DRCP pool when using multi-pool DRCP with Oracle Database 23.4, or higher

  • handle: an integer representing a pointer to a valid service context handle. This value is only used in python-oracledb Thick mode. It should be used with extreme caution

Changed in version 3.2.0: The pool_name parameter was added.

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

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

Changed in version 2.3.0: The ssl_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.

ConnectParams.set_from_config(config: dict) → None

Sets the property values based on the specified configuration. This method is intended for use with Centralized Configuration Providers.

The config parameter is a dictionary which consists of the following optional keys: “connect_descriptor”, “user”, “password”, and “pyo”.

If the key “connect_descriptor” is specified, it is expected to be a string, which will be parsed and the properties found within it are stored in the ConnectParams instance.

If the keys “user” or “password” are specified, and the parameters do not already have a user or password set, these values will be stored; otherwise, they will be ignored. The key “user” is expected to be a string. The “key” password may be a string or it may be a dictionary which will be examined by a registered password type handler to determine the actual password.

If the key “pyo” is specified, it is expected to be a dictionary containing keys corresponding to property names. Any property names accepted by the ConnectParams class will be stored in the ConnectParams instance; all other values will be ignored.

Added in version 3.0.0.

4.3. ConnectParams Attributes

All properties are read only.

property ConnectParams.appcontext: list

Application context used by the connection. It should be a list of 3-tuples (namespace, name, value) and each entry in the tuple should be a string.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.cclass: list | str

The connection class to use for Database Resident Connection Pooling (DRCP).

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.config_dir: str

A directory in which the optional tnsnames.ora configuration file is located. This value is only used in python-oracledb Thin mode. For python-oracledb Thick mode, it is used if oracledb.defaults.thick_mode_dsn_passthrough is False. Otherwise in Thick mode use the config_dir parameter of oracledb.init_oracle_client().

property ConnectParams.connection_id_prefix: list | str

An application specific prefix that is added to the connection identifier used for tracing.

This attribute is only supported in python-oracledb Thin mode.

Added in version 1.4.0.

property ConnectParams.debug_jdwp: str

A string with the format “host=<host>;port=<port>” that specifies the host and port of the PL/SQL debugger. This value is only used in python-oracledb Thin mode. For python-oracledb Thick mode set the ORA_DEBUG_JDWP environment variable.

See Application Tracing for more information.

property ConnectParams.disable_oob: bool

A boolean indicating whether out-of-band breaks should be disabled. This value is only used in python-oracledb Thin mode. It has no effect on Windows which does not support this functionality.

For python-oracledb Thick mode, set the equivalent option in a sqlnet.ora file.

property ConnectParams.driver_name: str

A string recorded by Oracle Database as the name of the driver which originated the connection.

This is an arbitrary value set by the user in the oracledb.ConnectParams() method or the oracledb.defaults.driver_name attribute which is the default value. This is the value shown in the CLIENT_DRIVER column of the V$SESSION_CONNECT_INFO view.

This attribute is supported in both python-oracledb Thin and Thick modes.

Added in version 2.5.0.

property ConnectParams.edition: str

Edition to use for the connection. This parameter cannot be used simultaneously with the cclass parameter.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.events: bool

A boolean specifying whether events mode should be enabled. This value is only used in python-oracledb Thick mode and is needed for continuous query notification and high availability event notifications.

property ConnectParams.expire_time: list | int

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 attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.externalauth: bool

A boolean indicating whether to use external authentication.

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 externalauth attribute to True, which may aid code auditing.

This attribute is only supported in python-oracledb Thick mode.

property ConnectParams.extra_auth_params: dict

A dictionary containing configuration parameters necessary for Oracle Database authentication using plugins, such as the Azure and OCI cloud- native authentication plugins.

This attribute is supported in both python-oracledb Thin and Thick modes.

Added in version 3.0.0.

property ConnectParams.host: list | str

The hostname or IP address of the machine hosting the database or the database listener.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.https_proxy: list | str

The hostname or IP address of a proxy host to use for tunneling secure connections.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.https_proxy_port: list | int

The port on which to communicate with the proxy host.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.instance_name: list | str

The instance name of the database.

This attribute is supported in both python-oracledb Thin and Thick modes.

Added in version 3.0.0.

property ConnectParams.machine: str

A string recorded by Oracle Database as the name of the machine from which the connection originates.

This is an arbitrary value set by the user in the oracledb.ConnectParams() method or the oracledb.defaults.machine attribute which is the default value. This is the value shown in the MACHINE column of the V$SESSION view.

This attribute is only supported in python-oracledb Thin mode.

Added in version 2.5.0.

property ConnectParams.matchanytag: bool

A boolean specifying whether any tag can be used when acquiring a connection from the pool. This value is only used in python-oracledb Thick mode.

property ConnectParams.mode: AuthMode

The authorization mode to use. One of the constants oracledb.AUTH_MODE_DEFAULT, oracledb.AUTH_MODE_PRELIM, oracledb.AUTH_MODE_SYSASM, oracledb.AUTH_MODE_SYSBKP, oracledb.AUTH_MODE_SYSDBA, oracledb.AUTH_MODE_SYSDGD, oracledb.AUTH_MODE_SYSKMT, oracledb.AUTH_MODE_SYSOPER, or oracledb.AUTH_MODE_SYSRAC.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.osuser: str

A string recorded by Oracle Database as the operating system user who originated the connection.

This is an arbitrary value set by the user in the oracledb.ConnectParams() method or the oracledb.defaults.osuser attribute which is the default value. This is the value shown in the OSUSER column of the V$SESSION view.

This attribute is only supported in python-oracledb Thin mode.

Added in version 2.5.0.

property ConnectParams.pool_boundary: list | str

One of the values “statement” or “transaction” indicating when pooled DRCP connections can be returned to the pool. This requires the use of DRCP with Oracle Database 23.4 or higher.

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() or Connection.rollback() are called. This attribute requires the use of DRCP or PRCP with Oracle Database version 23, or later. See Implicit Connection Pooling for more information.

This attribute is supported in both python-oracledb Thin and Thick modes.

Added in version 2.1.0.

property ConnectParams.pool_name: list | str

The name of the DRCP pool when using multi-pool DRCP with Oracle Database 23.4, or higher.

See DRCP Pool Names.

This attribute is supported in both python-oracledb Thin and Thick modes.

Added in version 3.2.0.

property ConnectParams.port: list | int

The port number on which the database listener is listening.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.program: str

A string recorded by Oracle Database as the program from which the connection originates.

This is an arbitrary value set by the user in the oracledb.ConnectParams() method or the oracledb.defaults.program attribute which is the default value. This is the value shown in the PROGRAM column of the V$SESSION view.

This attribute is supported in python-oracledb Thin mode.

Added in version 2.5.0.

property ConnectParams.protocol: list | str

One of the strings “tcp” or “tcps” indicating whether to use unencrypted network traffic or encrypted network traffic (TLS).

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.proxy_user: str

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 attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.purity: list | Purity

The connection purity to use for Database Resident Connection Pooling (DRCP).

When the value of this attribute is oracledb.PURITY_DEFAULT, then any standalone connection will use oracledb.PURITY_NEW and any pooled connection will use oracledb.PURITY_SELF. The default value is PURITY_DEFAULT.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.retry_count: list | int

The number of times that initial connection establishment should be retried before the connection attempt is terminated.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.retry_delay: list | int

The number of seconds to wait before retrying to establish a connection.

This attribute is supported in both python-oracledb Thin and Thick modes.

Changed in version 2.3.0: The default value of this attribute was changed from 0 seconds to 1 second.

property ConnectParams.sdu: list | int

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 attribute is supported in both python-oracledb Thin and Thick modes.

Added in version 2.0.0.

property ConnectParams.server_type: list | str

The type of server connection that should be established. If specified, it should be one of strings “dedicated”, “shared” or “pooled”.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.service_name: list | str

The service name of the database.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.shardingkey: list

A list of strings, numbers, bytes or dates that identify the database shard to connect to. This value is only used in python-oracledb Thick mode.

property ConnectParams.sid: list | str

The system identifier (SID) of the database. Note using a service_name instead is recommended.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.ssl_context: Any

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.

This attribute is only supported in python-oracledb Thin mode.

Added in version 2.0.0.

property ConnectParams.ssl_server_cert_dn: list | str

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. If specified this value is used for any verfication. Otherwise the hostname will be used.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.ssl_server_dn_match: list | bool

A boolean indicating 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 privided, host name matching is performed instead.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.ssl_version: list | TLSVersion

One of the values ssl.TLSVersion.TLSv1_2 or ssl.TLSVersion.TLSv1_3 indicating which TLS version to use.

This attribute is supported in both python-oracledb Thin and Thick modes.

Added in version 2.3.0.

property ConnectParams.stmtcachesize: int

The size of the statement cache.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.supershardingkey: list

A list of strings, numbers, bytes or dates that identify the database shard to connect to. This value is only used in python-oracledb Thick mode.

property ConnectParams.tag: str

Identifies the type of connection that should be returned from a pool. This value is only used in python-oracledb Thick mode.

This attribute is only supported in python-oracledb Thick mode.

property ConnectParams.tcp_connect_timeout: list | float

A float indicating the maximum number of seconds to wait when establishing a connection to the database host.

This attribute is supported in both python-oracledb Thin and Thick modes.

Changed in version 2.3.0: The default value of this attribute was changed from 60.0 seconds to 20.0 seconds.

property ConnectParams.terminal: str

A string recorded by Oracle Database as the terminal identifier from which the connection originates.

This is an arbitrary value set by the user in the oracledb.ConnectParams() method or the oracledb.defaults.terminal attribute which is the default value. This is the value shown in the TERMINAL column of the V$SESSION view.

This attribute is only supported in python-oracledb Thin mode.

Added in version 2.5.0.

property ConnectParams.use_sni: list | bool

A boolean indicating whether to use the TLS SNI extension to bypass the second TLS neogiation that would otherwise be required.

This attribute is supported in both python-oracledb Thin and Thick modes.

Added in version 3.0.0.

property ConnectParams.thick_mode_dsn_passthrough: bool

A boolean indicating whether to pass the connect string to the Oracle Client libraries unchanged without parsing by the driver. Setting this to False makes python-oracledb Thick and Thin mode applications behave similarly regarding connection string parameter handling and locating any optional tnsnames.ora configuration file.

This attribute is only supported in python-oracledb Thick mode.

Added in version 3.0.0.

property ConnectParams.use_tcp_fast_open: list | bool

A boolean indicating whether to use TCP fast open. This is an Oracle Autonomous Database Serverless (ADB-S) specific property for clients connecting from within OCI Cloud network. Please refer to the ADB-S documentation for more information.

This attribute is supported in both python-oracledb Thin and Thick modes.

Added in version 2.1.0.

property ConnectParams.user: str

The name of the database user to connect to.

This attribute is supported in both python-oracledb Thin and Thick modes.

property ConnectParams.wallet_location: list | str

The directory where the wallet can be found. In python-oracledb Thin mode this must be the directory containing the PEM-encoded wallet file ewallet.pem. In python-oracledb Thick mode this must be the directory containing the file cwallet.sso.

This attribute is supported in both python-oracledb Thin and Thick modes.