4. API: ConnectParams Objects
Note
This object is an extension to the DB API.
These objects are created by oracledb.ConnectParams()
. See
Using the ConnectParams Builder Class for more information.
4.1. ConnectParams Methods
- ConnectParams.copy()
Creates a copy of the ConnectParams instance and returns it.
- ConnectParams.get_connect_string()
Returns the connection string associated with the ConnectParams instance.
- ConnectParams.get_network_service_names()
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)
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 intnsnames.ora
. Parameters that are found in the connect string override any currently stored values.
- ConnectParams.parse_dsn_with_credentials(dsn)
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=None, proxy_user=None, password=None, newpassword=None, wallet_password=None, access_token=None, host=None, port=None, protocol=None, https_proxy=None, https_proxy_port=None, service_name=None, sid=None, server_type=None, cclass=None, purity=None, expire_time=None, retry_count=None, retry_delay=None, tcp_connect_timeout=None, ssl_server_dn_match=None, ssl_server_cert_dn=None, wallet_location=None, events=None, externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, edition=None, tag=None, matchanytag=None, config_dir=None, appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, connection_id_prefix=None, ssl_context=None, sdu=None, 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, handle=None)
Sets the values for one or more of the parameters of a ConnectParams object.
Changed in version 2.5.0: The
program
,machine
,terminal
,osuser
, anddriver_name
parameters were added. Support foredition
andappcontext
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
anduse_tcp_fast_open
parameters were added.Changed in version 2.0.0: The
ssl_context
andsdu
parameters were added.Changed in version 1.4.0: The
connection_id_prefix
parameter was added.
4.2. ConnectParams Attributes
- ConnectParams.appcontext
This read-only attribute is a list that specifies the application context used by the connection. It is a list of 3-tuples that includes the namespace, name, and value. Each entry in the tuple is a string.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.cclass
This read-only attribute is a string that specifies the connection class to use for Database Resident Connection Pooling (DRCP).
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.config_dir
This read-only attribute is a string that identifies the directory in which the configuration files such as tnsnames.ora are found. The default is the value of
defaults.config_dir
.This attribute is only supported in python-oracledb Thin mode.
For python-oracledb Thick mode, use the
config_dir
parameter oforacledb.init_oracle_client()
.
- ConnectParams.connection_id_prefix
This read-only attribute is a string that is added to the beginning of the generated
connection_id
that is sent to the database for tracing.This attribute is only supported in python-oracledb Thin mode.
Added in version 1.4.0.
- ConnectParams.debug_jdwp
This read-only attribute is a string with the format “host=<host>;port=<port>” that specifies the host and port of the PL/SQL debugger. This allows the Java Debug Wire Protocol (JDWP) to debug the PL/SQL code invoked by the python-oracledb driver. The default value is the value of the environment variable
ORA_DEBUG_JDWP
.This attribute is only supported in python-oracledb Thin mode.
For python-oracledb Thick mode, set the
ORA_DEBUG_JDWP
environment variable which has the same syntax. See Application Tracing for more information.
- ConnectParams.disable_oob
This read-only attribute is a boolean that indicates whether out-of-band breaks should be disabled. The default value is False. Note that this value has no effect on Windows, which does not support this functionality.
This attribute is only supported in python-oracledb Thin mode.
For python-oracledb Thick mode, set the equivalent option in a
sqlnet.ora
file.
- ConnectParams.driver_name
This read-only attribute is a string that specifies the driver used by the client to connect to Oracle Database. This is an arbitrary value set by the user in the
oracledb.ConnectParams()
method or thedefaults.driver_name
attribute which is the default value. This is the value shown in theCLIENT_DRIVER
column of theV$SESSION_CONNECT_INFO
view.This attribute is supported in both python-oracledb Thin and Thick modes.
Added in version 2.5.0.
- ConnectParams.edition
This read-only attribute is a string that specifies the edition to use for the connection. This attribute cannot be used simultaneously with the
ConnectParams.cclass
attribute.This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.events
This read-only attribute is a boolean that specifies whether the events mode should be enabled.
This attribute is needed for continuous query notification (CQN) and high availability event notifications. The default value is False.
This attribute is only supported in python-oracledb Thick mode.
- ConnectParams.expire_time
This read-only attribute is an integer that returns the number of minutes between the sending of keepalive probes.
The default value is 0. If this attribute is set to a value greater than zero, it enables keepalive.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.externalauth
This read-only attribute is a boolean that specifies whether external authentication should be used. 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 theexternalauth
attribute to True, which may aid code auditing.This attribute is only supported in python-oracledb Thick mode.
- ConnectParams.host
This read-only attribute is a string that returns the name or IP address of the machine hosting the database.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.https_proxy
This read-only attribute is a string that returns the name or IP address of a proxy host that is to be used for tunneling secure connections.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.https_proxy_port
This read-only attribute is an integer that returns the port to be used to communicate with the proxy host. The default value is 0.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.machine
This read-only attribute is a string that specifies the machine name of the client connecting to Oracle Database. This is an arbitrary value set by the user in the
oracledb.ConnectParams()
method or thedefaults.machine
attribute which is the default value. This is the value shown in theMACHINE
column of theV$SESSION
view.This attribute is only supported in python-oracledb Thin mode.
Added in version 2.5.0.
- ConnectParams.matchanytag
This read-only attribute is a boolean that specifies whether any tag can be used when acquiring a connection from the pool. The default value is False.
This attribute is only supported in python-oracledb Thick mode.
- ConnectParams.mode
This read-only attribute is an integer that specifies the authorization mode to use. The default value is
AUTH_MODE_DEFAULT
.This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.osuser
This read-only attribute is a string that represents the operating system user that initiates the database connection. This is an arbitrary value set by the user in the
oracledb.ConnectParams()
method or thedefaults.osuser
attribute which is the default value. This is the value shown in theOSUSER
column of theV$SESSION
view.This attribute is only supported in python-oracledb Thin mode.
Added in version 2.5.0.
- ConnectParams.pool_boundary
This read-only attribute is one of the strings “statement” or “transaction” which indicates when pooled DRCP or 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 attribute requires the use of DRCP or PRCP with Oracle Database 23ai (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.
- ConnectParams.port
This read-only attribute is an integer that returns the port number on which the database listener is listening. The default value is 1521.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.program
This read-only attribute is a string that specifies the name of the executable program or application connected to Oracle Database. This is an arbitrary value set by the user in the
oracledb.ConnectParams()
method or thedefaults.program
attribute which is the default value. This is the value shown in thePROGRAM
column of theV$SESSION
view.This attribute is supported in python-oracledb Thin mode.
Added in version 2.5.0.
- ConnectParams.protocol
This read-only attribute is a string that indicates whether unencrypted network traffic or encrypted network traffic (TLS) is used and it can have the value “tcp” or “tcps”. The default value is “tcp”.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.proxy_user
This read-only attribute is a string that specifies the name of the proxy user to connect to. If this value is not specified, then it will be parsed out of the user if the user attribute is in the form “user[proxy_user]”.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.purity
This read-only attribute is an integer that returns the purity used for Database Resident Connection Pooling (DRCP). When the value of this attribute is
oracledb.PURITY_DEFAULT
, then any standalone connection will useoracledb.PURITY_NEW
and any pooled connection will useoracledb.PURITY_SELF
. The default value isPURITY_DEFAULT
.This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.retry_count
This read-only attribute is an integer that returns the number of times that a connection attempt should be retried before the attempt is terminated. The default value is 0.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.retry_delay
This read-only attribute is an integer that returns the number of seconds to wait before making a new connection attempt. The default value is 1.
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.
- ConnectParams.sdu
This read-only attribute is 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 SQL*Net documentation for more details.
This attribute is supported in both python-oracledb Thin and Thick modes.
Added in version 2.0.0.
- ConnectParams.server_type
This read-only attribute is a string that returns the type of server connection that should be established. If specified, it should be one of dedicated, shared, or pooled.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.service_name
This read-only attribute is a string that returns the service name of the database.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.shardingkey
This read-only attribute is a list that specifies a sequence of strings, numbers, bytes, or dates that identify the database shard to connect to. See Connecting to Oracle Globally Distributed Database.
This attribute is only supported in python-oracledb Thick mode.
- ConnectParams.sid
This read-only attribute is a string that returns the SID of the database. It is recommended to use the
ConnectParams.service_name
instead.This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.ssl_context
This read-only attribute is 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 attribute is only supported in python-oracledb Thin mode.
Added in version 2.0.0.
- ConnectParams.ssl_server_cert_dn
This read-only attribute is a string that returns the distinguished name (DN), which should be matched with the server. If this value is specified, then it is used for any verification. Otherwise, the hostname will be used.
This value is ignored if the
ssl_server_dn_match
attribute is not set to the value True.This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.ssl_server_dn_match
This read-only attribute is a boolean that indicates whether the server certificate distinguished name (DN) should be matched in addition to the regular certificate verification that is performed. The default value is True.
Note that if the
ssl_server_cert_dn
attribute is not specified, then host name matching is performed instead.This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.ssl_version
This read-only attribute is 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 Python ssl module.
This attribute is supported in both python-oracledb Thin and Thick modes.
Added in version 2.3.0.
- ConnectParams.stmtcachesize
This read-only attribute is an integer that identifies the initial size of the statement cache. The default is the value of
defaults.stmtcachesize
.This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.supershardingkey
This read-only attribute is a list that specifies a sequence of strings, numbers, bytes, or dates that identify the database shard to connect to. See Connecting to Oracle Globally Distributed Database.
This attribute is only supported in python-oracledb Thick mode.
- ConnectParams.tag
This read-only attribute is a string that identifies the type of connection that should be returned from a pool.
This attribute is only supported in python-oracledb Thick mode.
- ConnectParams.tcp_connect_timeout
This read-only attribute is a float that indicates the maximum number of seconds to wait for a connection to be established to the database host. The default value is 20.0.
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.
- ConnectParams.terminal
This read-only attribute is a string that specifies the terminal identifier from which the connection originates. This is an arbitrary value set by the user in the
oracledb.ConnectParams()
method or thedefaults.terminal
attribute which is the default value. This is the value shown in theTERMINAL
column of theV$SESSION
view.This attribute is only supported in python-oracledb Thin mode.
Added in version 2.5.0.
- ConnectParams.use_tcp_fast_open
This read-only attribute is a boolean which indicates whether to use an 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. The default value is False.
This attribute is supported in both python-oracledb Thin and Thick modes.
Added in version 2.1.0.
- ConnectParams.user
This read-only attribute is a string that specifies the name of the user to connect to.
This attribute is supported in both python-oracledb Thin and Thick modes.
- ConnectParams.wallet_location
This read-only attribute is a string that specifies the directory where the wallet can be found.
In python-oracledb Thin mode, this attribute is the directory containing the PEM-encoded wallet file, ewallet.pem. In python-oracledb Thick mode, this attribute is the directory containing the file, cwallet.sso.
This attribute is supported in both python-oracledb Thin and Thick modes.