1.API: python-oracledb Module
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 fivevalues 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 Thickmode. 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,pool_name=None,handle=0)
Constructor for creating a connection to the database. Returns aConnection Object. All parameters are optional and can bespecified as keyword parameters. SeeStandalone Connectionsinformation about connections.
Not all parameters apply to both python-oracledb Thin andThick modes.
Some values, such as the database host name, can be specified asparameters, as part of the connect string, and in the params object. If a
dsn(data source name) parameter is passed, the python-oracledb Thickmode will use the string to connect, otherwise a connection string isinternally constructed from the individual parameters and params objectvalues, with the individual parameters having precedence. Inpython-oracledb’s default Thin mode, a connection string is internally usedthat contains all relevant values specified. The precedence in Thin modeis that values in anydsnparameter override values passed asindividual parameters, which themselves override values set in theparamsparameter object. Similar precedence rules also apply to othervalues.The
dsn(data source name) parameter is anOracle Net ServicesConnection String. It can also be a string in the formatuser/password@connect_string.The
poolparameter is expected to be a pool object. This parameterwas deprecated in python-oracledb 3.0.0. UseConnectionPool.acquire()instead since the use of this parameteris the equivalent of calling this method.The
pool_aliasparameter is expected to be a string which indicates thename of the previously created pool in theconnection pool cache from which to acquire the connection. This is identical tocallingConnectionPool.acquire(). Whenpool_aliasis used,connect()supports the same parameters asacquire()and has the same behavior.The
conn_classparameter is expected to be Connection or a subclass ofConnection.The
paramsparameter is expected to be of typeConnectParams and contains connection parameters that will be used whenestablishing the connection. If this parameter is not specified, theadditional keyword parameters will be used to internally create an instanceof ConnectParams. If both the params parameter and additional keywordparameters are specified, the values in the keyword parameters haveprecedence. Note that if adsnis also supplied in python-oracledb Thinmode, then the values of the parameters specified (if any) within thedsnwill override the values passed as additional keyword parameters,which themselves override the values set in theparamsparameterobject.The
userparameter is expected to be a string which indicates the nameof the user to connect to. This value is used in both the python-oracledbThin and Thick modes.The
proxy_userparameter is expected to be a string which indicates thename of the proxy user to connect to. If this value is not specified, itwill be parsed out of user if user is in the form “user[proxy_user]”. Thisvalue is used in both the python-oracledb Thin and Thick modes.The
passwordparameter expected to be a string which indicates thepassword for the user. This value is used in both the python-oracledb Thinand Thick modes.The
newpasswordparameter is expected to be a string which indicatesthe new password for the user. The new password will take effectimmediately upon a successful connection to the database. This value isused in both the python-oracledb Thin and Thick modes.The
wallet_passwordparameter is expected to be a string whichindicates the password to use to decrypt the PEM-encoded wallet, if it isencrypted. This value is only used in python-oracledb Thin mode. Thewallet_passwordparameter is not needed for cwallet.sso files that areused in the python-oracledb Thick mode.The
access_tokenparameter is expected to be a string or a 2-tuple ora callable. If it is a string, it specifies an Azure AD OAuth2 token usedfor Open Authorization (OAuth 2.0) token based authentication. If it is a2-tuple, it specifies the token and private key strings used for OracleCloud Infrastructure (OCI) Identity and Access Management (IAM) token basedauthentication. If it is a callable, it returns either a string or a2-tuple used for OAuth 2.0 or OCI IAM token based authentication and isuseful when the pool needs to expand and create new connections but thecurrent authentication token has expired. This value is used in both thepython-oracledb Thin and Thick modes.The
hostparameter is expected to be a string which specifies the nameor IP address of the machine hosting the listener, which handles theinitial connection to the database. This value is used in both thepython-oracledb Thin and Thick modes.The
portparameter is expected to be an integer which indicates theport number on which the listener is listening. The default value is1521. This value is used in both the python-oracledb Thin and Thickmodes.The
protocolparameter is expected to be one of the stringstcp ortcps which indicates whether to use unencrypted network traffic orencrypted network traffic (TLS). The default value istcp. This value isused in both the python-oracledb Thin and Thick modes.The
https_proxyparameter is expected to be a string which indicatesthe name or IP address of a proxy host to use for tunneling secureconnections. This value is used in both the python-oracledb Thin and Thickmodes.The
https_proxy_portparameter is expected to be an integer whichindicates the port that is to be used to communicate with the proxy host.The default value is0. This value is used in both the python-oracledbThin and Thick modes.The
service_nameparameter is expected to be a string which indicatesthe service name of the database. This value is used in both thepython-oracledb Thin and Thick modes.The
instance_nameparameter is expected to be a string which indicatesthe instance name of the database. This value is used in both thepython-oracledb Thin and Thick modes.The
sidparameter is expected to be a string which indicates the SID ofthe database. It is recommended to useservice_nameinstead. This valueis used in both the python-oracledb Thin and Thick modes.The
server_typeparameter is expected to be a string that indicates thetype of server connection that should be established. If specified, itshould be one ofdedicated,shared, orpooled. This value is used inboth the python-oracledb Thin and Thick modes.The
cclassparameter is expected to be a string that identifies theconnection class to use forDatabase Resident Connection Pooling (DRCP). This value is used in both thepython-oracledb Thin and Thick modes.The
purityparameter is expected to be one of theoracledb.PURITY_* constants that identifies thepurity to use for DRCP. This value is used in both the python-oracledb Thinand Thick modes. The purity will internally default toPURITY_SELFfor pooled connections. For standaloneconnections, the purity will internally default toPURITY_NEW.The
expire_timeparameter is expected to be an integer which indicatesthe number of minutes between the sending of keepalive probes. If thisparameter is set to a value greater than zero it enables keepalive. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is0.The
retry_countparameter is expected to be an integer that identifiesthe number of times that a connection attempt should be retried before theattempt is terminated. This value is used in both the python-oracledb Thinand Thick modes. The default value is0.The
retry_delayparameter is expected to be an integer that identifiesthe number of seconds to wait before making a new connection attempt. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is1.The
tcp_connect_timeoutparameter is expected to be a float thatindicates the maximum number of seconds to wait for establishing aconnection to the database host. This value is used in both thepython-oracledb Thin and Thick modes. The default value is20.0.The
ssl_server_dn_matchparameter is expected to be a boolean thatindicates whether the server certificate distinguished name (DN) should bematched in addition to the regular certificate verification that isperformed. Note that if thessl_server_cert_dnparameter is notprovided, host name matching is performed instead. This value is used inboth the python-oracledb Thin and Thick modes. The default value isTrue.The
ssl_server_cert_dnparameter is expected to be a string thatindicates the distinguished name (DN) which should be matched with theserver. This value is ignored if thessl_server_dn_matchparameter isnot set to the valueTrue. This value is used in both the python-oracledbThin and Thick modes.The
wallet_locationparameter is expected to be a string thatidentifies the directory where the wallet can be found. In python-oracledbThin mode, this must be the directory of the PEM-encoded wallet file,ewallet.pem. In python-oracledb Thick mode, this must be the directory ofthe file, cwallet.sso. This value is used in both the python-oracledb Thinand Thick modes.The
eventsparameter is expected to be a boolean that specifies whetherthe events mode should be enabled. This value is only used in thepython-oracledb Thick mode and is ignored in the Thin mode. This parameteris needed for continuous query notification and high availability eventnotifications. The default value isFalse.The
externalauthparameter is a boolean that specifies whether externalauthentication should be used. This value is only used in thepython-oracledb Thick mode and is ignored in the Thin mode. The defaultvalue isFalse. For standalone connections, external authenticationoccurs when theuserandpasswordattributes are not used. If theseattributes are not used, you can optionally set theexternalauthattribute toTrue, which may aid code auditing.If the
modeparameter is specified, it must be one of theconnection authorization modeswhich are defined at the module level. This value is used in both thepython-oracledb Thin and Thick modes. The default value isoracledb.AUTH_MODE_DEFAULT.The
disable_oobparameter is expected to be a boolean that indicateswhether out-of-band breaks should be disabled. This value is only usedin the python-oracledb Thin mode and has no effect on Windows whichdoes not support this functionality. The default value isFalse.The
stmtcachesizeparameter is expected to be an integer whichspecifies the initial size of the statement cache. This value is used inboth the python-oracledb Thin and Thick modes. The default is the value ofdefaults.stmtcachesize.The
editionparameter is expected to be a string that indicates theedition to use for the connection. It requires Oracle Database 11.2, orlater. This parameter cannot be used simultaneously with thecclassparameter.The
tagparameter is expected to be a string that identifies the typeof connection that should be returned from a pool. This value is only usedin the python-oracledb Thick mode and is ignored in the Thin mode.The
matchanytagparameter is expected to be a boolean specifyingwhether any tag can be used when acquiring a connection from the pool. Thisvalue is only used in the python-oracledb Thick mode when acquiring aconnection from a pool. This value is ignored in the python-oracledb Thinmode. The default value isFalse.The
config_dirparameter is expected to be a string that indicates thedirectory in whichoptional configuration files arefound. The default is the value ofdefaults.config_dir.The
appcontextparameter is expected to be a list of 3-tuples thatidentifies the application context used by the connection. This parametershould contain namespace, name, and value and each entry in the tupleshould be a string.The
shardingkeyparameter andsupershardingkeyparameters, ifspecified, are expected to be a sequence of values which identifies thedatabase shard to connect to. The key values can be a list of strings,numbers, bytes, or dates. These values are only used in thepython-oracledb Thick mode and are ignored in the Thin mode. SeeConnecting to Oracle Globally Distributed Database.The
debug_jdwpparameter is expected to be a string with the formathost=<host>;port=<port> that specifies the host and port of the PL/SQLdebugger. This allows using the Java Debug Wire Protocol (JDWP) to debugPL/SQL code called by python-oracledb. This value is only used in thepython-oracledb Thin mode. For python-oracledb Thick mode, set theORA_DEBUG_JDWPenvironment variable which has the same syntax. For moreinformation, seeApplication Tracing.The
connection_id_prefixparameter is expected to be a string and isadded to the beginning of the generatedconnection_idthat is sent tothe database fortracing. This valueis only used in the python-oracledb Thin mode.The
ssl_contextparameter is expected to be anSSLContext object which is usedfor connecting to the database using TLS. This SSL context will bemodified to include the private key or any certificates found in aseparately supplied wallet. This parameter should only be specified ifthe default SSLContext object cannot be used. This value is only used inthe python-oracledb Thin mode.The
sduparameter is expected to be an integer that returns therequested size of the Session Data Unit (SDU), in bytes. The value tunesinternal buffers used for communication to the database. Bigger values canincrease throughput for large queries or bulk data loads, but at the costof higher memory use. The SDU size that will actually be used is negotiateddown to the lower of this value and the database network SDU configurationvalue. See theDatabase Net Services documentation for more details. This value is used in both thepython-oracledb Thin and Thick modes. The default value is8192 bytes.The
pool_boundaryparameter is expected to be one of the stringsstatement ortransaction which indicates when pooledDRCPor PRCP connections can be returned to the pool. If the value isstatement, then pooled DRCP or PRCP connections are implicitly releasedback to the DRCP or PRCP pool when the connection is stateless (that is,there are no active cursors, active transactions, temporary tables, ortemporary LOBs). If the value istransaction, then pooled DRCP or PRCPconnections are implicitly released back to the DRCP or PRCP pool wheneither one of the methodsConnection.commit()orConnection.rollback()are called. This parameter requires the useof DRCP or PRCP with Oracle Database 23ai (or later). SeeImplicit Connection Pooling for more information. This value is used in boththe python-oracledb Thin and Thick modes.The
use_tcp_fast_openparameter is expected to be a boolean whichindicates whether to use TCP Fast Open which is anOracle AutonomousDatabase Serverless (ADB-S) specific feature that canreduce the latency in round-trips to the database after a connection hasbeen established. This feature is only available with certain versions ofADB-S. This value is used in both python-oracledb Thin and Thick modes.The default value isFalse.The
ssl_versionparameter is expected to be one of the constantsssl.TLSVersion.TLSv1_2 orssl.TLSVersion.TLSv1_3 which identifies theTLS protocol version used. These constants are defined in the Pythonssl module. Thisparameter can be specified when establishing connections with the protocoltcps. This value is used in both python-oracledb Thin and Thick modes.The valuessl.TLSVersion.TLSv1_3 requires Oracle Database 23ai. If youare using python-oracledb Thick mode, Oracle Client 23ai is additionallyrequired.The
use_sniparameter is expected to be a boolean which indicateswhether to use the TLS Server Name Indication (SNI) extension to bypass thesecond TLS negotiation that would otherwise be required. This parameter isused in both python-oracledb Thin and Thick modes. This parameter requiresOracle Database 23.7. The default value isFalse. See theDatabase NetServices documentation for more details.The
programparameter is expected to be a string which specifies thename of the executable program or application connected to OracleDatabase. This value is only used in the python-oracledb Thin mode. Thedefault is the value ofdefaults.program.The
machineparameter is expected to be a string which specifies themachine name of the client connecting to Oracle Database. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.machine.The
terminalparameter is expected to be a string which specifies theterminal identifier from which the connection originates. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.terminal.The
osuserparameter is expected to be a string which specifies theoperating system user that initiates the database connection. This valueis only used in the python-oracledb Thin mode. The default value is thevalue ofdefaults.osuser.The
driver_nameparameter is expected to be a string which specifiesthe driver used by the client to connect to Oracle Database. This valueis used in both the python-oracledb Thin and Thick modes. The default isthe value ofdefaults.driver_name.The
thick_mode_dsn_passthroughparameter is expected to be a booleanwhich indicates whether the connect string should be passed unchanged tothe Oracle Client libraries for parsing when using python-oracledb Thickmode. If this parameter is set toFalse in Thick mode, connect stringsare parsed by python-oracledb itself and a generated connect descriptor issent to the Oracle Client libraries. This value is only used in thepython-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_paramsparameter is expected to be a dictionarycontaining the configuration parameters necessary for Oracle Databaseauthentication usingOCI orAzure cloud native authentication plugins. This value isused in both the python-oracledb Thin and Thick modes. SeeToken-Based Authentication.The
pool_nameparameter is expected to be a string which specifies thename of the pool when using multiple DRCP pools with Oracle Database 23.4or later. This value is used in both python-oracledb Thin and Thick modes.SeeDRCP Pool Names.If the
handleparameter is specified, it must be of type OCISvcCtx*and is only of use when embedding Python in an application (likePowerBuilder) which has already made the connection. The connection thuscreated shouldnever be used after the source handle has been closed ordestroyed. This value is only used in the python-oracledb Thick mode andis ignored in the Thin mode. It should be used with extreme caution. Thedefault value is0.Changed in version 3.2.0:The
pool_nameparameter was added.Changed in version 3.0.0:The
pool_alias,instance_name,use_sni,thick_mode_dsn_passthrough, andextra_auth_paramsparameterswere added. Thepoolparameter was deprecated: useConnectionPool.acquire()instead.Changed in version 2.5.0:The
program,machine,terminal,osuser, anddriver_nameparameters were added. Support foreditionandappcontextwas added to python-oracledb Thin mode.Changed in version 2.3.0:The default value of the
retry_delayparameter was changed from 0seconds to 1 second. The default value of thetcp_connect_timeoutparameter was changed from 60.0 seconds to 20.0 seconds. Thessl_versionparameter was added.Changed in version 2.1.0:The
pool_boundaryanduse_tcp_fast_openparameters were added.Changed in version 2.0.0:The
ssl_contextandsduparameters were added.Changed in version 1.4.0:The
connection_id_prefixparameter 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,pool_name=None,handle=0)
Constructor for creating a connection to the database. Returns anAsyncConnection Object. All parameters are optionaland 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 asparameters, as part of the connect string, and in the params object.The precedence is that values in the
dsnparameter override valuespassed as individual parameters, which themselves override values set intheparamsparameter object. Similar precedence rules also apply toother values.The
dsn(data source name) parameter is anOracle Net ServicesConnection String. It can also be a string in the formatuser/password@connect_string.The
poolparameter is expected to be an AsyncConnectionPool object.This parameter was deprecated in python-oracledb 3.0.0. UseAsyncConnectionPool.acquire()instead since theuse of this parameter is the equivalent of calling this method.The
pool_aliasparameter is expected to be a string which indicates thename of the previously created pool in theconnection pool cache from which to acquire the connection. This is identical tocallingAsyncConnectionPool.acquire(). Whenpool_aliasis used,connect_async()supports the same parameters asacquire()and has the same behavior.The
conn_classparameter is expected to be AsyncConnection or asubclass of AsyncConnection.The
paramsparameter is expected to be of typeConnectParams and contains connection parameters that will be used whenestablishing the connection. If this parameter is not specified, theadditional keyword parameters will be used to create an instance ofConnectParams. If both the params parameter and additional keywordparameters are specified, the values in the keyword parameters haveprecedence. Note that if adsnis also supplied, then the values of theparameters specified (if any) within thedsnwill override the valuespassed as additional keyword parameters, which themselves override thevalues set in theparamsparameter object.The
userparameter is expected to be a string which indicates the nameof the user to connect to.The
proxy_userparameter is expected to be a string which indicates thename of the proxy user to connect to. If this value is not specified, itwill be parsed out of user if user is in the form “user[proxy_user]”.The
passwordparameter expected to be a string which indicates thepassword for the user.The
newpasswordparameter is expected to be a string which indicatesthe new password for the user. The new password will take effectimmediately upon a successful connection to the database.The
wallet_passwordparameter is expected to be a string whichindicates the password to use to decrypt the PEM-encoded wallet, if it isencrypted.The
access_tokenparameter is expected to be a string or a 2-tuple ora callable. If it is a string, it specifies an Azure AD OAuth2 token usedfor Open Authorization (OAuth 2.0) token based authentication. If it is a2-tuple, it specifies the token and private key strings used for OracleCloud Infrastructure (OCI) Identity and Access Management (IAM) token basedauthentication. If it is a callable, it returns either a string or a2-tuple used for OAuth 2.0 or OCI IAM token based authentication and isuseful when the pool needs to expand and create new connections but thecurrent authentication token has expired.The
hostparameter is expected to be a string which specifies the nameor IP address of the machine hosting the listener, which handles theinitial connection to the database.The
portparameter is expected to be an integer which indicates theport number on which the listener is listening. The default value is1521.The
protocolparameter is expected to be one of the stringstcp ortcps which indicates whether to use unencrypted network traffic orencrypted network traffic (TLS). The default value istcp.The
https_proxyparameter is expected to be a string which indicatesthe name or IP address of a proxy host to use for tunneling secureconnections.The
https_proxy_portparameter is expected to be an integer whichindicates the port that is to be used to communicate with the proxy host.The default value is0.The
service_nameparameter is expected to be a string which indicatesthe service name of the database.The
instance_nameparameter is expected to be a string which indicatesthe instance name of the database.The
sidparameter is expected to be a string which indicates the SID ofthe database. It is recommended to useservice_nameinstead.The
server_typeparameter is expected to be a string that indicates thetype of server connection that should be established. If specified, itshould be one ofdedicated,shared, orpooled.The
cclassparameter is expected to be a string that identifies theconnection class to use forDatabase Resident Connection Pooling (DRCP).The
purityparameter is expected to be one of theoracledb.PURITY_* constants that identifies thepurity to use for DRCP. The purity will internally default toPURITY_SELFfor pooled connections. For standaloneconnections, the purity will internally default toPURITY_NEW.The
expire_timeparameter is expected to be an integer which indicatesthe number of minutes between the sending of keepalive probes. If thisparameter is set to a value greater than zero it enables keepalive. Thedefault value is0.The
retry_countparameter is expected to be an integer that identifiesthe number of times that a connection attempt should be retried before theattempt is terminated. The default value is0.The
retry_delayparameter is expected to be an integer that identifiesthe number of seconds to wait before making a new connection attempt. Thedefault value is1.The
tcp_connect_timeoutparameter is expected to be a float thatindicates the maximum number of seconds to wait for establishing aconnection to the database host. The default value is20.0.The
ssl_server_dn_matchparameter is expected to be a boolean thatindicates whether the server certificate distinguished name (DN) should bematched in addition to the regular certificate verification that isperformed. Note that if thessl_server_cert_dnparameter is notprovided, host name matching is performed instead. The default value isTrue.The
ssl_server_cert_dnparameter is expected to be a string thatindicates the distinguished name (DN) which should be matched with theserver. This value is ignored if thessl_server_dn_matchparameter isnot set to the valueTrue.The
wallet_locationparameter is expected to be a string thatidentifies the directory where the wallet can be found. In python-oracledbThin mode, this must be the directory of the PEM-encoded wallet file,ewallet.pem.The
eventsparameter is ignored in the python-oracledb Thin mode.The
externalauthparameter is ignored in the python-oracledb Thin mode.If the
modeparameter 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_oobparameter is expected to be a boolean that indicateswhether out-of-band breaks should be disabled. This value has no effect onWindows which does not support this functionality. The default value isFalse.The
stmtcachesizeparameter is expected to be an integer whichspecifies the initial size of the statement cache. The default is thevalue ofdefaults.stmtcachesize.The
tagparameter is ignored in the python-oracledb Thin mode.The
matchanytagparameter is ignored in the python-oracledb Thin mode.The
config_dirparameter is expected to be a string that indicates thedirectory in whichoptional configuration files arefound. The default is the value ofdefaults.config_dir.The
appcontextparameter is expected to be a list of 3-tuples thatidentifies the application context used by the connection. This parametershould contain namespace, name, and value and each entry in the tupleshould be a string.The
shardingkeyparameter andsupershardingkeyparameters areignored in the python-oracledb Thin mode.The
debug_jdwpparameter is expected to be a string with the formathost=<host>;port=<port> that specifies the host and port of the PL/SQLdebugger. This allows using the Java Debug Wire Protocol (JDWP) to debugPL/SQL code called by python-oracledb.The
connection_id_prefixparameter is expected to be a string and isadded to the beginning of the generatedconnection_idthat is sent tothe database fortracing.The
ssl_contextparameter is expected to be an SSLContext object usedfor connecting to the database using TLS. This SSL context will bemodified to include the private key or any certificates found in aseparately supplied wallet. This parameter should only be specified ifthe default SSLContext object cannot be used.The
sduparameter is expected to be an integer that returns therequested size of the Session Data Unit (SDU), in bytes. The value tunesinternal buffers used for communication to the database. Bigger values canincrease throughput for large queries or bulk data loads, but at the costof higher memory use. The SDU size that will actually be used is negotiateddown to the lower of this value and the database network SDU configurationvalue. See theDatabase Net Services documentation for more details. The default value is8192 bytes.The
pool_boundaryparameter is expected to be one of the stringsstatement ortransaction which indicates when pooledDRCPor PRCP connections can be returned to the pool. If the value isstatement, then pooled DRCP or PRCP connections are implicitly releasedback to the DRCP or PRCP pool when the connection is stateless (that is,there are no active cursors, active transactions, temporary tables, ortemporary LOBs). If the value istransaction, then pooled DRCP or PRCPconnections are implicitly released back to the DRCP or PRCP pool wheneither one of the methodsAsyncConnection.commit()orAsyncConnection.rollback()are called. This parameter requires theuse of DRCP or PRCP with Oracle Database 23ai (or later). SeeImplicit Connection Pooling for more information. This value is used in boththe python-oracledb Thin and Thick modes.The
use_tcp_fast_openparameter is expected to be a boolean whichindicates whether to use TCP Fast Open which is anOracle AutonomousDatabase Serverless (ADB-S) specific feature that canreduce the latency in round-trips to the database after a connection hasbeen established. This feature is only available with certain versions ofADB-S. This value is used in both python-oracledb Thin and Thick modes.The default value isFalse.The
ssl_versionparameter is expected to be one of the constantsssl.TLSVersion.TLSv1_2 orssl.TLSVersion.TLSv1_3 which identifies theTLS protocol version used. These constants are defined in the Pythonssl module. Thisparameter can be specified when establishing connections with the protocoltcps. This value is used in both python-oracledb Thin and Thick modes.The valuessl.TLSVersion.TLSv1_3 requires Oracle Database 23ai. If youare using python-oracledb Thick mode, Oracle Client 23ai is additionallyrequired.The
use_sniparameter is expected to be a boolean which indicateswhether to use the TLS Server Name Indication (SNI) extension to bypass thesecond TLS negotiation that would otherwise be required. This parameter isused in both python-oracledb Thin and Thick modes. This parameter requiresOracle Database 23.7. The default value isFalse. See theDatabase NetServices documentation for more details.The
programparameter is expected to be a string which specifies thename of the executable program or application connected to OracleDatabase. This value is only used in the python-oracledb Thin mode. Thedefault is the value ofdefaults.program.The
machineparameter is expected to be a string which specifies themachine name of the client connecting to Oracle Database. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.machine.The
terminalparameter is expected to be a string which specifies theterminal identifier from which the connection originates. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.terminal.The
osuserparameter is expected to be a string which specifies theoperating system user that initiates the database connection. This valueis only used in the python-oracledb Thin mode. The default value is thevalue ofdefaults.osuser.The
driver_nameparameter is expected to be a string which specifiesthe driver used by the client to connect to Oracle Database. This valueis used in both the python-oracledb Thin and Thick modes. The default isthe value ofdefaults.driver_name.The
extra_auth_paramsparameter is expected to be a dictionarycontaining the configuration parameters necessary for Oracle Databaseauthentication usingOCI orAzure cloud native authentication plugins.This value is used in both the python-oracledb Thin and Thick modes. SeeToken-Based Authentication.The
pool_nameparameter is expected to be a string which specifies thename of the pool when using multiple DRCP pools with Oracle Database 23.4or later. This value is used in both python-oracledb Thin and Thick modes.SeeDRCP Pool Names.The
thick_mode_dsn_passthroughandhandleparameters are ignored inpython-oracledb Thin mode.Changed in version 3.2.0:The
pool_nameparameter was added.Changed in version 3.0.0:The
pool_alias,instance_name,use_sni,thick_mode_dsn_passthrough, andextra_auth_paramsparameterswere added. Thepoolparameter was deprecated: useAsyncConnectionPool.acquire()instead.Changed in version 2.5.0:The
program,machine,terminal,osuser, anddriver_nameparameters were added. Support foreditionandappcontextwas added.Changed in version 2.3.0:The default value of the
retry_delayparameter was changed from 0seconds to 1 second. The default value of thetcp_connect_timeoutparameter was changed from 60.0 seconds to 20.0 seconds. Thessl_versionparameter was added.Changed in version 2.1.0:The
pool_boundaryanduse_tcp_fast_openparameters were added.Changed in version 2.0.0:The
ssl_contextandsduparameters were added.Changed in version 1.4.0:The
connection_id_prefixparameter 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,pool_name=None,handle=0)
Contains all the parameters that can be used to establish a connection tothe database.
Creates and returns aConnectParams Object. The objectcan be passed to
oracledb.connect().All the parameters are optional.
The
userparameter is expected to be a string which indicates the nameof the user to connect to. This value is used in both the python-oracledbThin andThick modes.The
proxy_userparameter is expected to be a string which indicates thename of the proxy user to connect to. If this value is not specified, itwill be parsed out of user if user is in the form “user[proxy_user]”. Thisvalue is used in both the python-oracledb Thin and Thick modes.The
passwordparameter expected to be a string which indicates thepassword for the user. This value is used in both the python-oracledb Thinand Thick modes.The
newpasswordparameter is expected to be a string which indicatesthe new password for the user. The new password will take effectimmediately upon a successful connection to the database. This value isused in both the python-oracledb Thin and Thick modes.The
wallet_passwordparameter is expected to be a string whichindicates the password to use to decrypt the PEM-encoded wallet, if it isencrypted. This value is only used in python-oracledb Thin mode. Thewallet_passwordparameter is not needed for cwallet.sso files that areused in the python-oracledb Thick mode.The
access_tokenparameter is expected to be a string or a 2-tuple ora callable. If it is a string, it specifies an Azure AD OAuth2 token usedfor Open Authorization (OAuth 2.0) token based authentication. If it is a2-tuple, it specifies the token and private key strings used for OracleCloud Infrastructure (OCI) Identity and Access Management (IAM) token basedauthentication. If it is a callable, it returns either a string or a2-tuple used for OAuth 2.0 or OCI IAM token based authentication and isuseful when the pool needs to expand and create new connections but thecurrent authentication token has expired. This value is used in both thepython-oracledb Thin and Thick modes.The
hostparameter is expected to be a string which specifies the nameor IP address of the machine hosting the listener, which handles theinitial connection to the database. This value is used in both thepython-oracledb Thin and Thick modes.The
portparameter is expected to be an integer which indicates theport number on which the listener is listening. The default value is1521. This value is used in both the python-oracledb Thin and Thickmodes.The
protocolparameter is expected to be one of the stringstcp ortcps which indicates whether to use unencrypted network traffic orencrypted network traffic (TLS). The default value istcp. This value isused in both the python-oracledb Thin and Thick modes.The
https_proxyparameter is expected to be a string which indicatesthe name or IP address of a proxy host to use for tunneling secureconnections. This value is used in both the python-oracledb Thin and Thickmodes.The
https_proxy_portparameter is expected to be an integer whichindicates the port that is to be used to communicate with the proxy host.The default value is0. This value is used in both the python-oracledb Thinand Thick modes.The
service_nameparameter is expected to be a string which indicatesthe service name of the database. This value is used in both thepython-oracledb Thin and Thick modes.The
instance_nameparameter is expected to be a string which indicatesthe instance name of the database. This value is used in both thepython-oracledb Thin and Thick modes.The
sidparameter is expected to be a string which indicates the SID ofthe database. It is recommended to useservice_nameinstead. This valueis used in both the python-oracledb Thin and Thick modes.The
server_typeparameter is expected to be a string that indicates thetype of server connection that should be established. If specified, itshould be one ofdedicated,shared, orpooled. This value is used inboth the python-oracledb Thin and Thick modes.The
cclassparameter is expected to be a string that identifies theconnection class to use forDatabase Resident Connection Pooling (DRCP). This value is used in both thepython-oracledb Thin and Thick modes.The
purityparameter is expected to be one of theoracledb.PURITY_* constants that identifies thepurity to use for DRCP. This value is used in both the python-oracledb Thinand Thick modes. The purity will internally default toPURITY_SELFfor pooled connections . For standaloneconnections, the purity will internally default toPURITY_NEW.The
expire_timeparameter is expected to be an integer which indicatesthe number of minutes between the sending of keepalive probes. If thisparameter is set to a value greater than zero it enables keepalive. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is0.The
retry_countparameter is expected to be an integer that identifiesthe number of times that a connection attempt should be retried before theattempt is terminated. This value is used in both the python-oracledb Thinand Thick modes. The default value is0.The
retry_delayparameter is expected to be an integer that identifiesthe number of seconds to wait before making a new connection attempt. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is1.The
tcp_connect_timeoutparameter is expected to be a float thatindicates the maximum number of seconds to wait for establishing aconnection to the database host. This value is used in both thepython-oracledb Thin and Thick modes. The default value is20.0.The
ssl_server_dn_matchparameter is expected to be a boolean thatindicates whether the server certificate distinguished name (DN) should bematched in addition to the regular certificate verification that isperformed. Note that if thessl_server_cert_dnparameter is notprovided, host name matching is performed instead. This value is used inboth the python-oracledb Thin and Thick modes. The default value isTrue.The
ssl_server_cert_dnparameter is expected to be a string thatindicates the distinguished name (DN) which should be matched with theserver. This value is ignored if thessl_server_dn_matchparameter isnot set to the valueTrue. This value is used in both the python-oracledbThin and Thick modes.The
wallet_locationparameter is expected to be a string thatidentifies the directory where the wallet can be found. In python-oracledbThin mode, this must be the directory of the PEM-encoded wallet file,ewallet.pem. In python-oracledb Thick mode, this must be the directory ofthe file, cwallet.sso. This value is used in both the python-oracledb Thinand Thick modes.The
eventsparameter is expected to be a boolean that specifies whetherthe events mode should be enabled. This value is only used in thepython-oracledb Thick mode. This parameter is needed for continuousquery notification and high availability event notifications. The defaultvalue isFalse.The
externalauthparameter is a boolean that specifies whether externalauthentication should be used. This value is only used in thepython-oracledb Thick mode. The default value isFalse. For standaloneconnections, external authentication occurs when theuserandpasswordattributes are not used. If these attributes are not used, youcan optionally set theexternalauthattribute toTrue, which may aidcode auditing.The
modeparameter is expected to be an integer that identifies theauthorization mode to use. This value is used in both the python-oracledbThin and Thick modes.The default value isoracledb.AUTH_MODE_DEFAULT.The
disable_oobparameter is expected to be a boolean that indicateswhether out-of-band breaks should be disabled. This value is only usedin the python-oracledb Thin mode and has no effect on Windows whichdoes not support this functionality. The default value isFalse.The
stmtcachesizeparameter is expected to be an integer thatidentifies the initial size of the statement cache. This value is used inboth the python-oracledb Thin and Thick modes. The default is the value ofdefaults.stmtcachesize.The
editionparameter is expected to be a string that indicates theedition to use for the connection. It requires Oracle Database 11.2, orlater. This parameter cannot be used simultaneously with thecclassparameter.The
tagparameter is expected to be a string that identifies the type ofconnection that should be returned from a pool. This value is only usedin the python-oracledb Thick mode.The
matchanytagparameter is expected to be a boolean specifyingwhether any tag can be used when acquiring a connection from the pool. Thisvalue is only used in the python-oracledb Thick mode when acquiring aconnection from a pool. The default value isFalse.The
config_dirparameter is expected to be a string that indicates thedirectory in which thetnsnames.ora configuration fileis located.The
appcontextparameter is expected to be a list of 3-tuples thatidentifies the application context used by the connection. This parametershould contain namespace, name, and value and each entry in the tupleshould be a string.The
shardingkeyparameter andsupershardingkeyparameters, ifspecified, are expected to be a sequence of values which identifies thedatabase shard to connect to. The key values can be a list of strings,numbers, bytes, or dates. These values are only used in thepython-oracledb Thick mode and are ignored in the Thin mode. SeeConnecting to Oracle Globally Distributed Database.The
debug_jdwpparameter is expected to be a string with the formathost=<host>;port=<port> that specifies the host and port of the PL/SQLdebugger. This allows using the Java Debug Wire Protocol (JDWP) to debugPL/SQL code invoked by python-oracledb. This value is only used in thepython-oracledb Thin mode. For python-oracledb Thick mode, set theORA_DEBUG_JDWPenvironment variable which has the same syntax. For moreinformation, seeApplication Tracing.The
connection_id_prefixparameter is expected to be a string and isadded to the beginning of the generatedconnection_idthat is sent tothe database fortracing. This valueis only used in the python-oracledb Thin mode.The
ssl_contextparameter is expected to be anSSLContext object which is usedfor connecting to the database using TLS. This SSL context will bemodified to include the private key or any certificates found in aseparately supplied wallet. This parameter should only be specified ifthe default SSLContext object cannot be used. This value is only used inthe python-oracledb Thin mode.The
sduparameter is expected to be an integer that returns therequested size of the Session Data Unit (SDU), in bytes. The value tunesinternal buffers used for communication to the database. Bigger values canincrease throughput for large queries or bulk data loads, but at the costof higher memory use. The SDU size that will actually be used is negotiateddown to the lower of this value and the database network SDU configurationvalue. See theDatabase Net Services documentation for more details. This value is used in both thepython-oracledb Thin and Thick modes. The default value is8192 bytes.The
pool_boundaryparameter is expected to be one of the stringsstatement ortransaction which indicates when pooledDRCPor PRCP connections can be returned to the pool. If the value isstatement, then pooled DRCP or PRCP connections are implicitly releasedback to the DRCP or PRCP pool when the connection is stateless (that is,there are no active cursors, active transactions, temporary tables, ortemporary LOBs). If the value istransaction, then pooled DRCP or PRCPconnections are implicitly released back to the DRCP or PRCP pool wheneither one of the methodsConnection.commit()orConnection.rollback()are called. This parameter requires the useof DRCP or PRCP with Oracle Database 23ai (or later). SeeImplicit Connection Pooling for more information. This value is used in boththe python-oracledb Thin and Thick modes.The
use_tcp_fast_openparameter is expected to be a boolean whichindicates whether to use TCP Fast Open which is anOracle AutonomousDatabase Serverless (ADB-S) specific feature that canreduce the latency in round-trips to the database after a connection hasbeen established. This feature is only available with certain versions ofADB-S. This value is used in both python-oracledb Thin and Thick modes.The default value isFalse.The
ssl_versionparameter is expected to be one of the constantsssl.TLSVersion.TLSv1_2 orssl.TLSVersion.TLSv1_3 which identifies theTLS protocol version used. These constants are defined in the Pythonssl module. Thisparameter can be specified when establishing connections with the protocol“tcps”. This value is used in both python-oracledb Thin and Thick modes.The valuessl.TLSVersion.TLSv1_3 requires Oracle Database 23ai. If youare using python-oracledb Thick mode, Oracle Client 23ai is additionallyrequired.The
use_sniparameter is expected to be a boolean which indicateswhether to use the TLS Server Name Indication (SNI) extension to bypass thesecond TLS negotiation that would otherwise be required. This parameter isused in both python-oracledb Thin and Thick modes. This parameter requiresOracle Database 23.7. The default value isFalse. See theDatabase NetServices documentation for more details.The
programparameter is expected to be a string which specifies thename of the executable program or application connected to OracleDatabase. This value is only used in the python-oracledb Thin mode. Thedefault is the value ofdefaults.program.The
machineparameter is expected to be a string which specifies themachine name of the client connecting to Oracle Database. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.machine.The
terminalparameter is expected to be a string which specifies theterminal identifier from which the connection originates. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.terminal.The
osuserparameter is expected to be a string which specifies theoperating system user that initiates the database connection. This valueis only used in the python-oracledb Thin mode. The default value is thevalue ofdefaults.osuser.The
driver_nameparameter is expected to be a string which specifiesthe driver used by the client to connect to Oracle Database. This valueis used in both the python-oracledb Thin and Thick modes. The default isthe value ofdefaults.driver_name.The
thick_mode_dsn_passthroughparameter is expected to be a booleanwhich indicates whether the connect string should be passed unchanged tothe Oracle Client libraries for parsing when using python-oracledb Thickmode. If this parameter is set toFalse in Thick mode, connect stringsare parsed by python-oracledb itself and a generated connect descriptor issent to the Oracle Client libraries. This value is only used in thepython-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_paramsparameter is expected to be a dictionarycontaining the configuration parameters necessary for Oracle Databaseauthentication usingOCI orAzure cloud native authentication plugins. This value isused in both the python-oracledb Thin and Thick modes. SeeToken-Based Authentication.The
pool_nameparameter is expected to be a string which specifies thename of the pool when using multiple DRCP pools with Oracle Database 23.4or later. This value is used in both python-oracledb Thin and Thick modes.SeeDRCP Pool Names.The
handleparameter is expected to be an integer which represents apointer to a valid service context handle. This value is only used in thepython-oracledb Thick mode. It should be used with extreme caution. Thedefault value is0.Changed in version 3.2.0:The
pool_nameparameter was added.Changed in version 3.0.0:The
instance_name,use_sni,thick_mode_dsn_passthroughandextra_auth_paramsparameters were added.Changed in version 2.5.0:The
program,machine,terminal,osuser, anddriver_nameparameters were added. Support foreditionandappcontextwas added to python-oracledb Thin mode.Changed in version 2.3.0:The default value of the
retry_delayparameter was changed from 0seconds to 1 second. The default value of thetcp_connect_timeoutparameter was changed from 60.0 seconds to 20.0 seconds. Thessl_versionparameter was added.Changed in version 2.1.0:The
pool_boundaryanduse_tcp_fast_openparameters were added.Changed in version 2.0.0:The
ssl_contextandsduparameters were added.Changed in version 1.4.0:The
connection_id_prefixparameter was added.
- oracledb.create_pipeline()
Creates apipeline object which can be used toprocess 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,pool_name=None,handle=0)
Creates a connection pool with the supplied parameters and returns theConnectionPool object for the pool. SeeConnectionpooling for more information.
This function is the equivalent of the
cx_Oracle.SessionPool()function. The use ofSessionPool()has been deprecated inpython-oracledb.Not all parameters apply to both python-oracledb Thin andThick modes.
Some values, such as the database host name, can be specified asparameters, as part of the connect string, and in the params object. If a
dsn(data source name) parameter is passed, the python-oracledb Thickmode will use the string to connect, otherwise a connection string isinternally constructed from the individual parameters and params objectvalues, with the individual parameters having precedence. Inpython-oracledb’s default Thin mode, a connection string is internally usedthat contains all relevant values specified. The precedence in Thin modeis that values in anydsnparameter override values passed asindividual parameters, which themselves override values set in theparamsparameter object. Similar precedence rules also apply to othervalues.Python-oracledb connection pools must be created, used and closed withinthe same process. Sharing pools or connections across processes hasunpredictable behavior. Using connection pools in multi-threadedarchitectures is supported. Multi-process architectures that cannot beconverted to threading may get some benefit fromDatabase 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, anddsnparameters are the same as fororacledb.connect().The
pool_classparameter is expected to be aConnectionPool Object or a subclass of ConnectionPool.The
pool_aliasparameter is expected to be a string representing thename used to store and reference the pool in the python-oracledb connectionpool cache. If this parameter is not specified, then the pool will not beadded to the cache. The value of this parameter can be used with theoracledb.get_pool()andoracledb.connect()methods toaccess the pool. SeeUsing the Connection Pool Cache.The
paramsparameter is expected to be of typePoolParams and contains parameters that are used to create the pool.If this parameter is not specified, the additional keyword parameters willbe used to create an instance of PoolParams. If both the params parameterand additional keyword parameters are specified, the values in the keywordparameters have precedence. Note that if adsnis also supplied, thenin the python-oracledb Thin mode, the values of the parameters specified(if any) within thedsnwill override the values passed as additionalkeyword parameters, which themselves override the values set in theparamsparameter object.The
min,maxandincrementparameters control pool growthbehavior. A fixed pool size whereminequalsmaxisrecommended to help prevent connection storms and tohelp overall system stability. Theminparameter is the number ofconnections opened when the pool is created. The default value of theminparameter is1. Theincrementparameter is the number ofconnections that are opened whenever a connection request exceeds thenumber of currently open connections. The default value of theincrementparameter is1. Themaxparameter is the maximum numberof connections that can be open in the connection pool. The default valueof themaxparameter is2.If the
connectiontypeparameter is specified, all calls toConnectionPool.acquire()will create connection objects of thattype, rather than the base type defined at the module level.The
getmodeparameter 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
homogeneousparameter is a boolean that indicates whether theconnections are homogeneous (same user) or heterogeneous (multipleusers). The default value isTrue.The
timeoutparameter is the length of time (in seconds) that aconnection may remain idle in the pool before it is terminated. Thisapplies only when the pool has more thanminconnections open, allowingit to shrink to the specified minimum size. The default value is0seconds. A value of0 means there is no limit.The
wait_timeoutparameter is the length of time (in milliseconds) thata caller should wait when acquiring a connection from the pool withgetmodeset tooracledb.POOL_GETMODE_TIMEDWAIT. The defaultvalue is0 milliseconds.The
max_lifetime_sessionparameter is the length of time (in seconds)that a pooled connection may exist since first being created. The defaultvalue is0. A value of0 means that there is no limit. Connectionsbecome candidates for termination when they are acquired or released backto the pool and have existed for longer thanmax_lifetime_sessionseconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 orlater must be used and, prior to Oracle Client 21, cleanup only occurs whenthe pool is accessed.The
session_callbackparameter is a callable that is invoked when aconnection is returned from the pool for the first time, or when theconnection tag differs from the one requested.The
max_sessions_per_shardparameter is the maximum number ofconnections that may be associated with a particular shard. This value isonly used in the python-oracledb Thick mode and is ignored in thepython-oracledb Thin mode. The default value is0.The
soda_metadata_cacheparameter is a boolean that indicates whetheror not the SODA metadata cache should be enabled. This value is only usedin the python-oracledb Thick mode and is ignored in the python-oracledbThin mode. The default value isFalse.The
ping_intervalparameter is the length of time (in seconds) afterwhich an unused connection in the pool will be a candidate for pinging whenConnectionPool.acquire()is called. If the ping to the databaseindicates the connection is not alive a replacement connection will bereturned byacquire(). Ifping_intervalis anegative value, then the ping functionality will be disabled. The defaultvalue is60 seconds.The
ping_timeoutparameter is the maximum length of time (inmilliseconds) thatConnectionPool.acquire()waits for a connectionto respond to any internal ping to the database. If the ping does notrespond within the specified time, then the connection is destroyed andacquire()returns a different connection. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is5000 milliseconds.The
proxy_userparameter is expected to be a string which indicates thename of the proxy user to connect to. If this value is not specified, itwill be parsed out of user if user is in the form “user[proxy_user]”. Thisvalue is used in both the python-oracledb Thin and Thick modes.The
newpasswordparameter is expected to be a string which indicatesthe new password for the user. The new password will take effectimmediately upon a successful connection to the database. This value isused in both the python-oracledb Thin and Thick modes.The
wallet_passwordparameter is expected to be a string whichindicates the password to use to decrypt the PEM-encoded wallet, if it isencrypted. This value is only used in python-oracledb Thin mode. Thewallet_passwordparameter is not needed for cwallet.sso files that areused in the python-oracledb Thick mode.The
access_tokenparameter is expected to be a string or a 2-tuple ora callable. If it is a string, it specifies an Azure AD OAuth2 token usedfor Open Authorization (OAuth 2.0) token based authentication. If it is a2-tuple, it specifies the token and private key strings used for OracleCloud Infrastructure (OCI) Identity and Access Management (IAM) token basedauthentication. If it is a callable, it returns either a string or a2-tuple used for OAuth 2.0 or OCI IAM token based authentication and isuseful when the pool needs to expand and create new connections but thecurrent authentication token has expired. This value is used in both thepython-oracledb Thin and Thick modes.The
hostparameter is expected to be a string which specifies the nameor IP address of the machine hosting the listener, which handles theinitial connection to the database. This value is used in both thepython-oracledb Thin and Thick modes.The
portparameter is expected to be an integer which indicates theport number on which the listener is listening. The default value is1521. This value is used in both the python-oracledb Thin and Thickmodes.The
protocolparameter is expected to be one of the stringstcp ortcps which indicates whether to use unencrypted network traffic orencrypted network traffic (TLS). The default value istcp. This value isused in both the python-oracledb Thin and Thick modes.The
https_proxyparameter is expected to be a string which indicatesthe name or IP address of a proxy host to use for tunneling secureconnections. This value is used in both the python-oracledb Thin and Thickmodes.The
https_proxy_portparameter is expected to be an integer whichindicates the port that is to be used to communicate with the proxy host.The default value is0. This value is used in both the python-oracledbThin and Thick modes.The
service_nameparameter is expected to be a string which indicatesthe service name of the database. This value is used in both thepython-oracledb Thin and Thick modes.The
instance_nameparameter is expected to be a string which indicatesthe instance name of the database. This value is used in both thepython-oracledb Thin and Thick modes.The
sidparameter is expected to be a string which indicates the SID ofthe database. It is recommended to useservice_nameinstead. This valueis used in both the python-oracledb Thin and Thick modes.The
server_typeparameter is expected to be a string that indicates thetype of server connection that should be established. If specified, itshould be one ofdedicated,shared, orpooled. This value is used inboth the python-oracledb Thin and Thick modes.The
cclassparameter is expected to be a string that identifies theconnection class to use forDatabase Resident Connection Pooling (DRCP). This value is used in both thepython-oracledb Thin and Thick modes.The
purityparameter is expected to be one of theoracledb.PURITY_* constants that identifies thepurity to use for DRCP. This value is used in both the python-oracledb Thinand Thick modes. The purity will internally default toPURITY_SELFfor pooled connections.The
expire_timeparameter is expected to be an integer which indicatesthe number of minutes between the sending of keepalive probes. If thisparameter is set to a value greater than zero it enables keepalive. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is0 minutes.The
retry_countparameter is expected to be an integer that identifiesthe number of times that a connection attempt should be retried before theattempt is terminated. This value is used in both the python-oracledb Thinand Thick modes. The default value is0.The
retry_delayparameter is expected to be an integer that identifiesthe number of seconds to wait before making a new connection attempt. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is1 seconds.The
tcp_connect_timeoutparameter is expected to be a float thatindicates the maximum number of seconds to wait for establishing aconnection to the database host. This value is used in both thepython-oracledb Thin and Thick modes. The default value is20.0 seconds.The
ssl_server_dn_matchparameter is expected to be a boolean thatindicates whether the server certificate distinguished name (DN) should bematched in addition to the regular certificate verification that isperformed. Note that if thessl_server_cert_dnparameter is notprovided, host name matching is performed instead. This value is used inboth the python-oracledb Thin and Thick modes. The default value isTrue.The
ssl_server_cert_dnparameter is expected to be a string thatindicates the distinguished name (DN) which should be matched with theserver. This value is ignored if thessl_server_dn_matchparameter isnot set to the valueTrue. This value is used in both the python-oracledbThin and Thick modes.The
wallet_locationparameter is expected to be a string thatidentifies the directory where the wallet can be found. In python-oracledbThin mode, this must be the directory of the PEM-encoded wallet file,ewallet.pem. In python-oracledb Thick mode, this must be the directory ofthe file, cwallet.sso. This value is used in both the python-oracledb Thinand Thick modes.The
eventsparameter is expected to be a boolean that specifies whetherthe events mode should be enabled. This value is only used in thepython-oracledb Thick mode and is ignored in the Thin mode. This parameteris needed for continuous query notification and high availability eventnotifications. The default value isFalse.The
externalauthparameter is a boolean that determines whether to useexternal authentication. This value is only used in python-oracledb Thickmode and is ignored in Thin mode. The default value isFalse. For pooledconnections in Thick mode, external authentication requires the use of aheterogeneous pool. For this reason, you must set thehomogeneousparameter toFalse. SeeConnecting Using External Authentication.If the
modeparameter is specified, it must be one of theconnection authorization modeswhich are defined at the module level. This value is used in both thepython-oracledb Thin and Thick modes.The default value isoracledb.AUTH_MODE_DEFAULT.The
disable_oobparameter is expected to be a boolean that indicateswhether out-of-band breaks should be disabled. This value is only usedin the python-oracledb Thin mode and has no effect on Windows whichdoes not support this functionality. The default value isFalse.The
stmtcachesizeparameter is expected to be an integer whichspecifies the initial size of the statement cache. This value is used inboth the python-oracledb Thin and Thick modes. The default is the value ofdefaults.stmtcachesize.The
editionparameter is expected to be a string that indicates theedition to use for the connection. It requires Oracle Database 11.2, orlater. This parameter cannot be used simultaneously with thecclassparameter.The
tagparameter is expected to be a string that identifies the typeof connection that should be returned from a pool. This value is only usedin the python-oracledb Thick mode and is ignored in the Thin mode.The
matchanytagparameter is expected to be a boolean specifyingwhether any tag can be used when acquiring a connection from the pool. Thisvalue is only used in the python-oracledb Thick mode when acquiring aconnection from a pool. This value is ignored in the python-oracledb Thinmode. The default value isFalse.The
config_dirparameter is expected to be a string that indicates thedirectory in which thetnsnames.ora configuration fileis located. The default is the value ofdefaults.config_dir.The
appcontextparameter is expected to be a list of 3-tuples thatidentifies the application context used by the connection. This parametershould contain namespace, name, and value and each entry in the tupleshould be a string.The
shardingkeyparameter andsupershardingkeyparameters, ifspecified, are expected to be a sequence of values which identifies thedatabase shard to connect to. The key values can be a list of strings,numbers, bytes, or dates. These values are only used in thepython-oracledb Thick mode and are ignored in the Thin mode. SeeConnecting to Oracle Globally Distributed Database.The
debug_jdwpparameter is expected to be a string with the formathost=<host>;port=<port> that specifies the host and port of the PL/SQLdebugger. This allows using the Java Debug Wire Protocol (JDWP) to debugPL/SQL code invoked by python-oracledb. This value is only used in thepython-oracledb Thin mode. For python-oracledb Thick mode, set theORA_DEBUG_JDWPenvironment variable which has the same syntax. For moreinformation, seeApplication Tracing.The
connection_id_prefixparameter is expected to be a string and isadded to the beginning of the generatedconnection_idthat is sent tothe database fortracing. This valueis only used in the python-oracledb Thin mode.The
ssl_contextparameter is expected to be anSSLContext object which is usedfor connecting to the database using TLS. This SSL context will bemodified to include the private key or any certificates found in aseparately supplied wallet. This parameter should only be specified ifthe default SSLContext object cannot be used. This value is only used inthe python-oracledb Thin mode.The
sduparameter is expected to be an integer that returns therequested size of the Session Data Unit (SDU), in bytes. The value tunesinternal buffers used for communication to the database. Bigger values canincrease throughput for large queries or bulk data loads, but at the costof higher memory use. The SDU size that will actually be used is negotiateddown to the lower of this value and the database network SDU configurationvalue. See theDatabase Net Services documentation for more details. This value is used in both thepython-oracledb Thin and Thick modes. The default value is8192 bytes.The
pool_boundaryparameter is expected to be one of the stringsstatement ortransaction which indicates when pooledDRCPor PRCP connections can be returned to the pool. If the value isstatement, then pooled DRCP or PRCP connections are implicitly releasedback to the DRCP or PRCP pool when the connection is stateless (that is,there are no active cursors, active transactions, temporary tables, ortemporary LOBs). If the value istransaction, then pooled DRCP or PRCPconnections are implicitly released back to the DRCP or PRCP pool wheneither one of the methodsConnection.commit()orConnection.rollback()are called. This parameter requires the useof DRCP or PRCP with Oracle Database 23ai (or later). SeeImplicit Connection Pooling for more information. This value is used in boththe python-oracledb Thin and Thick modes.The
use_tcp_fast_openparameter is expected to be a boolean whichindicates whether to use TCP Fast Open which is anOracle AutonomousDatabase Serverless (ADB-S) specific feature that canreduce the latency in round-trips to the database after a connection hasbeen established. This feature is only available with certain versions ofADB-S. This value is used in both python-oracledb Thin and Thick modes.The default value isFalse.The
ssl_versionparameter is expected to be one of the constantsssl.TLSVersion.TLSv1_2 orssl.TLSVersion.TLSv1_3 which identifies theTLS protocol version used. These constants are defined in the Pythonssl module. Thisparameter can be specified when establishing connections with the protocol“tcps”. This value is used in both python-oracledb Thin and Thick modes.The valuessl.TLSVersion.TLSv1_3 requires Oracle Database 23ai. If youare using python-oracledb Thick mode, Oracle Client 23ai is additionallyrequired.The
use_sniparameter is expected to be a boolean which indicateswhether to use the TLS Server Name Indication (SNI) extension to bypass thesecond TLS negotiation that would otherwise be required. This parameter isused in both python-oracledb Thin and Thick modes. This parameter requiresOracle Database 23.7. The default value isFalse. See theDatabase NetServices documentation for more details.The
programparameter is expected to be a string which specifies thename of the executable program or application connected to OracleDatabase. This value is only used in the python-oracledb Thin mode. Thedefault is the value ofdefaults.program.The
machineparameter is expected to be a string which specifies themachine name of the client connecting to Oracle Database. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.machine.The
terminalparameter is expected to be a string which specifies theterminal identifier from which the connection originates. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.terminal.The
osuserparameter is expected to be a string which specifies theoperating system user that initiates the database connection. This valueis only used in the python-oracledb Thin mode. The default value is thevalue ofdefaults.osuser.The
driver_nameparameter is expected to be a string which specifiesthe driver used by the client to connect to Oracle Database. This valueis used in both the python-oracledb Thin and Thick modes. The default isthe value ofdefaults.driver_name.The
thick_mode_dsn_passthroughparameter is expected to be a booleanwhich indicates whether the connect string should be passed unchanged tothe Oracle Client libraries for parsing when using python-oracledb Thickmode. If this parameter is set toFalse in Thick mode, connect stringsare parsed by python-oracledb itself and a generated connect descriptor issent to the Oracle Client libraries. This value is only used in thepython-oracledb Thick mode. The default value isdefaults.thick_mode_dsn_passthrough. For more information, seeUsing Optional Oracle Configuration Files.The
extra_auth_paramsparameter is expected to be a dictionarycontaining the configuration parameters necessary for Oracle Databaseauthentication usingOCI orAzure cloud native authentication plugins. This value isused in both the python-oracledb Thin and Thick modes. SeeToken-Based Authentication.The
pool_nameparameter is expected to be a string which specifies thename of the pool when using multiple DRCP pools with Oracle Database 23.4or later. This value is used in both python-oracledb Thin and Thick modes.SeeDRCP Pool Names.If the
handleparameter is specified, it must be of type OCISvcCtx*and is only of use when embedding Python in an application (likePowerBuilder) which has already made the connection. The connection thuscreated shouldnever be used after the source handle has been closed ordestroyed. This value is only used in the python-oracledb Thick mode andis ignored in the Thin mode. It should be used with extreme caution. Thedefault value is0.Changed in version 3.2.0:The
pool_nameparameter was added.Changed in version 3.0.0:The
pool_alias,instance_name,use_sni,thick_mode_dsn_passthrough, andextra_auth_paramsparameterswere added.Changed in version 2.5.0:The
program,machine,terminal,osuser, anddriver_nameparameters were added. Support foreditionandappcontextwas added to python-oracledb Thin mode.Changed in version 2.3.0:The default value of the
retry_delayparameter was changed from0seconds to1 second. The default value of thetcp_connect_timeoutparameter was changed from60.0 seconds to20.0 seconds. Theping_timeoutandssl_versionparameters were added.Changed in version 2.1.0:The
pool_boundaryanduse_tcp_fast_openparameters were added.Changed in version 2.0.0:The
ssl_contextandsduparameters were added.Changed in version 1.4.0:The
connection_id_prefixparameter 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,pool_name=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.
Some values, such as the database host name, can be specified asparameters, as part of the connect string, and in the params object.The precedence is that values in the
dsnparameter override valuespassed as individual parameters, which themselves override values set intheparamsparameter object. Similar precedence rules also apply toother values.The
user,password, anddsnparameters are the same as fororacledb.connect().The
pool_classparameter is expected to be anAsyncConnectionPool Object or a subclass ofAsyncConnectionPool.The
pool_aliasparameter is expected to be a string representing thename used to store and reference the pool in the python-oracledb connectionpool cache. If this parameter is not specified, then the pool will not beadded to the cache. The value of this parameter can be used with theoracledb.get_pool()andoracledb.connect_async()methods toaccess the pool. SeeUsing the Connection Pool Cache.The
paramsparameter is expected to be of typePoolParams and contains parameters that are used to create the pool.If this parameter is not specified, the additional keyword parameters willbe used to create an instance of PoolParams. If both the params parameterand additional keyword parameters are specified, the values in the keywordparameters have precedence. Note that if adsnis also supplied, thenthe values of the parameters specified (if any) within thedsnwilloverride the values passed as additional keyword parameters, whichthemselves override the values set in theparamsparameter object.The
min,maxandincrementparameters control pool growthbehavior. A fixed pool size whereminequalsmaxisrecommended to help prevent connection storms and tohelp overall system stability. Theminparameter is the number ofconnections opened when the pool is created. The default value of theminparameter is1. Theincrementparameter is the number ofconnections that are opened whenever a connection request exceeds thenumber of currently open connections. The default value of theincrementparameter is1. Themaxparameter is the maximum numberof connections that can be open in the connection pool. The default valueof themaxparameter is2.If the
connectiontypeparameter is specified, all calls toAsyncConnectionPool.acquire()will create connection objects ofthat type, rather than the base type defined at the module level.The
getmodeparameter 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
homogeneousparameter is a boolean that indicates whether theconnections are homogeneous (same user) or heterogeneous (multipleusers). The default value isTrue.The
timeoutparameter is the length of time (in seconds) that aconnection may remain idle in the pool before it is terminated. Thisapplies only when the pool has more thanminconnections open, allowingit to shrink to the specified minimum size. The default value is0seconds. A value of0 means there is no limit.The
wait_timeoutparameter is the length of time (in milliseconds) thata caller should wait when acquiring a connection from the pool withgetmodeset tooracledb.POOL_GETMODE_TIMEDWAIT. The defaultvalue is0 milliseconds.The
max_lifetime_sessionparameter is the length of time (in seconds)that a pooled connection may exist since first being created. The defaultvalue is0. A value of0 means that there is no limit. Connectionsbecome candidates for termination when they are acquired or released backto the pool and have existed for longer thanmax_lifetime_sessionseconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 orlater must be used and, prior to Oracle Client 21, cleanup only occurs whenthe pool is accessed.The
session_callbackparameter is a callable that is invoked when aconnection is returned from the pool for the first time, or when theconnection tag differs from the one requested.The
max_sessions_per_shardparameter is ignored in the python-oracledbThin mode.The
soda_metadata_cacheparameter is ignored in the python-oracledbThin mode.The
ping_intervalparameter is the length of time (in seconds) afterwhich an unused connection in the pool will be a candidate for pinging whenAsyncConnectionPool.acquire()is called. If the ping to thedatabase indicates the connection is not alive a replacement connectionwill be returned byacquire(). Ifping_intervalis a negative value, then the ping functionality will bedisabled. The default value is60 seconds.The
ping_timeoutparameter is the maximum length of time (inmilliseconds) thatAsyncConnectionPool.acquire()waits for aconnection to respond to any internal ping to the database. If the pingdoes not respond within the specified time, then the connection isdestroyed andacquire()returns a differentconnection. This value is used in both the python-oracledb Thin and Thickmodes. The default value is5000 milliseconds.The
proxy_userparameter is expected to be a string which indicates thename of the proxy user to connect to. If this value is not specified, itwill be parsed out of user if user is in the form “user[proxy_user]”.The
newpasswordparameter is expected to be a string which indicatesthe new password for the user. The new password will take effectimmediately upon a successful connection to the database.The
wallet_passwordparameter is expected to be a string whichindicates the password to use to decrypt the PEM-encoded wallet, if it isencrypted.The
access_tokenparameter is expected to be a string or a 2-tuple ora callable. If it is a string, it specifies an Azure AD OAuth2 token usedfor Open Authorization (OAuth 2.0) token based authentication. If it is a2-tuple, it specifies the token and private key strings used for OracleCloud Infrastructure (OCI) Identity and Access Management (IAM) token basedauthentication. If it is a callable, it returns either a string or a2-tuple used for OAuth 2.0 or OCI IAM token based authentication and isuseful when the pool needs to expand and create new connections but thecurrent authentication token has expired.The
hostparameter is expected to be a string which specifies the nameor IP address of the machine hosting the listener, which handles theinitial connection to the database.The
portparameter is expected to be an integer which indicates theport number on which the listener is listening. The default value is1521.The
protocolparameter is expected to be one of the stringstcp ortcps which indicates whether to use unencrypted network traffic orencrypted network traffic (TLS). The default value istcp.The
https_proxyparameter is expected to be a string which indicatesthe name or IP address of a proxy host to use for tunneling secureconnections.The
https_proxy_portparameter is expected to be an integer whichindicates the port that is to be used to communicate with the proxy host.The default value is0.The
service_nameparameter is expected to be a string which indicatesthe service name of the database.The
instance_nameparameter is expected to be a string which indicatesthe instance name of the database.The
sidparameter is expected to be a string which indicates the SID ofthe database. It is recommended to useservice_nameinstead.The
server_typeparameter is expected to be a string that indicates thetype of server connection that should be established. If specified, itshould be one ofdedicated,shared, orpooled.The
cclassparameter is expected to be a string that identifies theconnection class to use forDatabase Resident Connection Pooling (DRCP).The
purityparameter is expected to be one of theoracledb.PURITY_* constants that identifies thepurity to use for DRCP. The purity will internally default toPURITY_SELFfor pooled connections.The
expire_timeparameter is expected to be an integer which indicatesthe number of minutes between the sending of keepalive probes. If thisparameter is set to a value greater than zero it enables keepalive. Thedefault value is0 minutes.The
retry_countparameter is expected to be an integer that identifiesthe number of times that a connection attempt should be retried before theattempt is terminated. The default value is0.The
retry_delayparameter is expected to be an integer that identifiesthe number of seconds to wait before making a new connection attempt. Thedefault value is1 seconds.The
tcp_connect_timeoutparameter is expected to be a float thatindicates the maximum number of seconds to wait for establishing aconnection to the database host. The default value is20.0 seconds.The
ssl_server_dn_matchparameter is expected to be a boolean thatindicates whether the server certificate distinguished name (DN) should bematched in addition to the regular certificate verification that isperformed. Note that if thessl_server_cert_dnparameter is notprovided, host name matching is performed instead. The default value isTrue.The
ssl_server_cert_dnparameter is expected to be a string thatindicates the distinguished name (DN) which should be matched with theserver. This value is ignored if thessl_server_dn_matchparameter isnot set to the valueTrue.The
wallet_locationparameter is expected to be a string thatidentifies the directory where the wallet can be found. In python-oracledbThin mode, this must be the directory of the PEM-encoded wallet file,ewallet.pem.The
eventsparameter is ignored in the python-oracledb Thin mode.The
externalauthparameter is ignored in the python-oracledb Thin mode.If the
modeparameter 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_oobparameter is expected to be a boolean that indicateswhether out-of-band breaks should be disabled. This value has no effecton Windows which does not support this functionality. The default valueisFalse.The
stmtcachesizeparameter is expected to be an integer whichspecifies the initial size of the statement cache. The default is thevalue ofdefaults.stmtcachesize.The
tagparameter is ignored in the python-oracledb Thin mode.The
matchanytagparameter is ignored in the python-oracledb Thin mode.The
config_dirparameter is expected to be a string that indicates thedirectory in which thetnsnames.ora configuration fileis located.The
appcontextparameter is expected to be a list of 3-tuples thatidentifies the application context used by the connection. This parametershould contain namespace, name, and value and each entry in the tupleshould be a string.The
shardingkeyparameter andsupershardingkeyparameters areignored in the python-oracledb Thin mode.The
debug_jdwpparameter is expected to be a string with the formathost=<host>;port=<port> that specifies the host and port of the PL/SQLdebugger. This allows using the Java Debug Wire Protocol (JDWP) to debugPL/SQL code invoked by python-oracledb.The
connection_id_prefixparameter is expected to be a string and isadded to the beginning of the generatedconnection_idthat is sent tothe database fortracing.The
ssl_contextparameter is expected to be an SSLContext object usedfor connecting to the database using TLS. This SSL context will bemodified to include the private key or any certificates found in aseparately supplied wallet. This parameter should only be specified ifthe default SSLContext object cannot be used.The
sduparameter is expected to be an integer that returns therequested size of the Session Data Unit (SDU), in bytes. The value tunesinternal buffers used for communication to the database. Bigger values canincrease throughput for large queries or bulk data loads, but at the costof higher memory use. The SDU size that will actually be used is negotiateddown to the lower of this value and the database network SDU configurationvalue. See theDatabase Net Services documentation for more details. The default value is8192 bytes.The
pool_boundaryparameter is expected to be one of the stringsstatement ortransaction which indicates when pooledDRCPor PRCP connections can be returned to the pool. If the value isstatement, then pooled DRCP or PRCP connections are implicitly releasedback to the DRCP or PRCP pool when the connection is stateless (that is,there are no active cursors, active transactions, temporary tables, ortemporary LOBs). If the value istransaction, then pooled DRCP or PRCPconnections are implicitly released back to the DRCP or PRCP pool wheneither one of the methodsAsyncConnection.commit()orAsyncConnection.rollback()are called. This parameter requires theuse of DRCP or PRCP with Oracle Database 23ai (or later). SeeImplicit Connection Pooling for more information. This value is used in boththe python-oracledb Thin and Thick modes.The
use_tcp_fast_openparameter is expected to be a boolean whichindicates whether to use TCP Fast Open which is anOracle AutonomousDatabase Serverless (ADB-S) specific feature that canreduce the latency in round-trips to the database after a connection hasbeen established. This feature is only available with certain versions ofADB-S. This value is used in both python-oracledb Thin and Thick modes.The default value isFalse.The
ssl_versionparameter is expected to be one of the constantsssl.TLSVersion.TLSv1_2 orssl.TLSVersion.TLSv1_3 which identifies theTLS protocol version used. These constants are defined in the Pythonssl module. Thisparameter can be specified when establishing connections with the protocoltcps. This value is used in both python-oracledb Thin and Thick modes.The valuessl.TLSVersion.TLSv1_3 requires Oracle Database 23ai. If youare using python-oracledb Thick mode, Oracle Client 23ai is additionallyrequired.The
use_sniparameter is expected to be a boolean which indicateswhether to use the TLS Server Name Indication (SNI) extension to bypass thesecond TLS negotiation that would otherwise be required. This parameter isused in both python-oracledb Thin and Thick modes. This parameter requiresOracle Database 23.7. The default value isFalse. See theDatabase NetServices documentation for more details.The
programparameter is expected to be a string which specifies thename of the executable program or application connected to OracleDatabase. This value is only used in the python-oracledb Thin mode. Thedefault is the value ofdefaults.program.The
machineparameter is expected to be a string which specifies themachine name of the client connecting to Oracle Database. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.machine.The
terminalparameter is expected to be a string which specifies theterminal identifier from which the connection originates. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.terminal.The
osuserparameter is expected to be a string which specifies theoperating system user that initiates the database connection. This valueis only used in the python-oracledb Thin mode. The default value is thevalue ofdefaults.osuser.The
driver_nameparameter is expected to be a string which specifiesthe driver used by the client to connect to Oracle Database. This valueis used in both the python-oracledb Thin and Thick modes. The default isthe value ofdefaults.driver_name.The
extra_auth_paramsparameter is expected to be a dictionarycontaining the configuration parameters necessary for Oracle Databaseauthentication usingOCI orAzure cloud native authentication plugins. This value isused in both the python-oracledb Thin and Thick modes. SeeToken-Based Authentication.The
pool_nameparameter is expected to be a string which specifies thename of the pool when using multiple DRCP pools with Oracle Database 23.4or later. This value is used in both python-oracledb Thin and Thick modes.SeeDRCP Pool Names.The
handleandthick_mode_dsn_passthroughparameters are ignored inpython-oracledb Thin mode.Changed in version 3.2.0:The
pool_nameparameter was added.Changed in version 3.0.0:The
pool_alias,instance_name,use_sni,thick_mode_dsn_passthrough, andextra_auth_paramsparameterswere added.Changed in version 2.5.0:The
program,machine,terminal,osuser, anddriver_nameparameters were added. Support foreditionandappcontextwas added.Changed in version 2.3.0:The default value of the
retry_delayparameter was changed from 0seconds to 1 second. The default value of thetcp_connect_timeoutparameter was changed from 60.0 seconds to 20.0 seconds. Theping_timeoutandssl_versionparameters were added.Changed in version 2.1.0:The
pool_boundaryanduse_tcp_fast_openparameters were added.Changed in version 2.0.0:The
ssl_contextandsduparameters were added.Changed in version 1.4.0:The
connection_id_prefixparameter was added.
- oracledb.Cursor(connection)
Constructor for creating a cursor. Returns a newcursor object using the connection.
This method is an extension to the DB API definition.
- oracledb.Date(year,month,day)
Constructs an object holding a date value.
- oracledb.DateFromTicks(ticks)
Constructs an object holding a date value from the given ticks value(number of seconds since the epoch; see the documentation of the standardPython time module for details).
- oracledb.enable_thin_mode()
Makes python-oracledb be in Thin mode. After this method is called, Thickmode cannot be enabled. If python-oracledb is already in Thick mode, thencalling
enable_thin_mode()will fail. If Thin mode connections havealready been opened, or a connection pool created in Thin mode, thencallingenable_thin_mode()is a no-op.Since python-oracledb defaults to Thin mode, almost all applications do notneed to call this method. However, because it bypasses python-oracledb’sinternal mode-determination heuristic, it may be useful for applicationswith multiple threads that concurrently createstandalone connections when the application starts.
SeeExplicitly Enabling python-oracledb Thin Mode for more information.
Added in version 2.5.0.
- oracledb.get_pool(pool_alias)
Returns aConnectionPool object from the python-oracledbpool cache. The pool must have been previously created by passing the same
pool_aliasvalue tooracledb.create_pool()ororacledb.create_pool_async().If a pool with the given name does not exist,None is returned.
SeeUsing the Connection Pool Cache for more information.
Added in version 3.0.0.
- oracledb.init_oracle_client(lib_dir=None,config_dir=None,error_url=None,driver_name=None)
Enables python-oracledb Thick mode by initializing the Oracle Clientlibrary, seeEnabling python-oracledb Thick mode. If a standalone connection or pool hasalready been created in Thin mode,
init_oracle_client()will raise anexception and python-oracledb will remain in Thin mode.If a standalone connection or pool hasnot already been created in Thinmode, but
init_oracle_client()raises an exception, python-oracledbwill remain in Thin mode but further calls toinit_oracle_client()canbe made, if desired.The
init_oracle_client()method can be called multiple times in eachPython process as long as the arguments are the same each time.The
lib_dirparameter is a string or a bytes object that specifies thedirectory containing Oracle Client libraries. If thelib_dirparameteris set, then the specified directory is the only one searched for theOracle Client libraries; otherwise, the operating system library searchpath is used to locate the Oracle Client library. If you are using Python3.11 and later, then the value specified in this parameter is encodedusinglocale.getencoding(). For all other Python versions, the encoding“utf-8” is used. If a bytes object is specified in this parameter, thenthis value will be used as is without any encoding.The
config_dirparameter is a string or a bytes object that specifiesthe directory in which theOptional Oracle Net Configuration andOptional Oracle Client Configuration files reside.If theconfig_dirparameter is set, then the specified directory isused to find Oracle Client library configuration files. This isequivalent to setting the environment variableTNS_ADMINand overridesany value already set inTNS_ADMIN. If this parameter is not set, theOracle standard way of locating Oracle Clientlibrary configuration files is used. If you are using Python 3.11 andlater, then the value specified in this parameter is encoded usinglocale.getencoding(). For all other Python versions, the encoding“utf-8” is used. If a bytes object is specified in this parameter, thenthis value will be used as is without any encoding.The
error_urlparameter is a string that specifies the URL which isincluded in the python-oracledb exception message if the Oracle Clientlibraries cannot be loaded. If theerror_urlparameter is set, thenthe specified value is included in the message of the exception raisedwhen the Oracle Client library cannot be loaded; otherwise, theInstalling python-oracledb URL is included. This parameter lets your applicationdisplay custom installation instructions.The
driver_nameparameter is a string that specifies the driver namevalue. If thedriver_nameparameter is set, then the specified valuecan be found in database views that give information about connections.For example, it is in the CLIENT_DRIVER column of theV$SESSION_CONNECT_INFO view. From Oracle Database 12.2, the name displayedcan be 30 characters. The standard is to set this value to"<name>:version>", where <name> is the name of the driver and <version> is itsversion. There should be a single space character before and after thecolon. If this parameter is not set, then the value specified inoracledb.defaults.driver_nameis used. Ifthe value of this attribute isNone, then the default value inpython-oracledb Thick mode is like “python-oracledb thk : <version>”. SeeOther python-oracledb Thick Mode Initialization.At successful completion of a call to
oracledb.init_oracle_client(),the attributedefaults.config_dirwill be set as determined below(first one wins):the value of the
oracledb.init_oracle_client()parameterconfig_dir, if one was passed.the value of
defaults.config_dirif it has one. I.e.defaults.config_dirremains unchanged afteroracledb.init_oracle_client()completes.the value of the environment variable
$TNS_ADMIN, if it is set.the value of
$ORACLE_HOME/network/adminif the environment variable$ORACLE_HOMEis set.the directory of the loaded Oracle Client library, appended with
network/admin. Note this directory is not determinable on AIX.otherwise the valueNone is used. (Leaving
defaults.config_dirunchanged).
Changed in version 3.0.0:At completion of the method, the value of
defaults.config_dirmay get changed by python-oracledb.Changed in version 2.5.0:The values supplied to the
lib_dirandconfig_dirparametersare encoded using the encoding returned bylocale.getencoding()for Python 3.11 and higher; for all other versions, the encoding“utf-8” is used. These values may also be supplied as abytesobject, in which case they will be used as is.
- oracledb.is_thin_mode()
Returns a boolean indicating if Thin mode is in use.
Immediately after python-oracledb is imported, this function will returnTrue indicating that python-oracledb defaults to Thin mode. If
oracledb.init_oracle_client()is called, then a subsequent call tois_thin_mode()will return False indicating that Thick mode isenabled. Once the first standalone connection or connection pool iscreated, or a call tooracledb.init_oracle_client()is made, thenpython-oracledb’s mode is fixed and the value returned byis_thin_mode()will never change for the lifetime of the process.The attribute
This method is an extension to the DB API definition.Connection.thincan be used to check a connection’smode. The attributeConnectionPool.thincan be used to check apool’s mode.Added in version 1.1.0.
- oracledb.makedsn(host,port,sid=None,service_name=None,region=None,sharding_key=None,super_sharding_key=None)
Returns a string suitable for use as the
dsnparameter forconnect(). This string is identical to the strings thatare defined by the Oracle names server or defined in thetnsnames.orafile.Deprecated since python-oracledb 1.0.
Use the
This method is an extension to the DB API definition.oracledb.ConnectParams()method instead.
- oracledb.PoolParams(min=1,max=2,increment=1,connectiontype=None,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=Nonde,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,pool_name=None,handle=0)
Creates and returns aPoolParams Object. The objectcan be passed to
oracledb.create_pool().All the parameters are optional.
The
minparameter is the minimum number of connections that the poolshould contain. The default value is1.The
maxparameter is the maximum number of connections that the poolshould contain. The default value is2.The
incrementparameter is the number of connections that should beadded to the pool whenever a new connection needs to be created. Thedefault value is1.The
connectiontypeparameter is the class of the connection that shouldbe returned during calls toConnectionPool.acquire(). It must be aConnection or a subclass of Connection.The
getmodeparameter 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
homogeneousparameter is a boolean that indicates whether theconnections are homogeneous (same user) or heterogeneous (multiple users).The default value isTrue.The
timeoutparameter is the length of time (in seconds) that aconnection may remain idle in the pool before it is terminated. Thisapplies only when the pool has more thanminconnections open, allowingit to shrink to the specified minimum size. The default value is0seconds. A value of0 means there is no limit.The
wait_timeoutparameter is the length of time (in milliseconds) thata caller should wait when acquiring a connection from the pool withgetmodeset tooracledb.POOL_GETMODE_TIMEDWAIT. The defaultvalue is0 milliseconds.The
max_lifetime_sessionparameter is the length of time (in seconds)that a pooled connection may exist since first being created. The defaultvalue is0. A value of0 means that there is no limit. Connectionsbecome candidates for termination when they are acquired or released backto the pool and have existed for longer thanmax_lifetime_sessionseconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 orlater must be used and, prior to Oracle Client 21, cleanup only occurs whenthe pool is accessed.The
session_callbackparameter is a callable that is invoked when aconnection is returned from the pool for the first time, or when theconnection tag differs from the one requested.The
max_sessions_per_shardparameter is the maximum number ofconnections that may be associated with a particular shard. The defaultvalue is0.The
soda_metadata_cacheparameter is a boolean that indicates whetheror not the SODA metadata cache should be enabled. The default value isFalse.The
ping_intervalparameter is the length of time (in seconds) afterwhich an unused connection in the pool will be a candidate for pinging whenConnectionPool.acquire()is called. If the ping to the databaseindicates the connection is not alive a replacement connection will bereturned byConnectionPool.acquire(). If ping_interval is anegative value, then the ping functionality will be disabled. The defaultvalue is60 seconds.The
ping_timeoutparameter is the maximum length of time (inmilliseconds) thatConnectionPool.acquire()waits for a connectionto respond to any internal ping to the database. If the ping does notrespond within the specified time, then the connection is destroyed andacquire()returns a different connection. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is5000 milliseconds.The
userparameter is expected to be a string which indicates the nameof the user to connect to. This value is used in both the python-oracledbThin and Thick modes.The
proxy_userparameter is expected to be a string which indicates thename of the proxy user to connect to. If this value is not specified, itwill be parsed out of user if user is in the form “user[proxy_user]”. Thisvalue is used in both the python-oracledb Thin and Thick modes.The
passwordparameter expected to be a string which indicates thepassword for the user. This value is used in both the python-oracledb Thinand Thick modes.The
newpasswordparameter is expected to be a string which indicatesthe new password for the user. The new password will take effectimmediately upon a successful connection to the database. This value isused in both the python-oracledb Thin and Thick modes.The
wallet_passwordparameter is expected to be a string whichindicates the password to use to decrypt the PEM-encoded wallet, if it isencrypted. This value is only used in python-oracledb Thin mode. Thewallet_passwordparameter is not needed for cwallet.sso files that areused in the python-oracledb Thick mode.The
access_tokenparameter is expected to be a string or a 2-tuple ora callable. If it is a string, it specifies an Azure AD OAuth2 token usedfor Open Authorization (OAuth 2.0) token based authentication. If it is a2-tuple, it specifies the token and private key strings used for OracleCloud Infrastructure (OCI) Identity and Access Management (IAM) token basedauthentication. If it is a callable, it returns either a string or a2-tuple used for OAuth 2.0 or OCI IAM token based authentication and isuseful when the pool needs to expand and create new connections but thecurrent authentication token has expired. This value is used in both thepython-oracledb Thin and Thick modes.The
hostparameter is expected to be a string which specifies the nameor IP address of the machine hosting the listener, which handles theinitial connection to the database. This value is used in both thepython-oracledb Thin and Thick modes.The
portparameter is expected to be an integer which indicates theport number on which the listener is listening. The default value is1521. This value is used in both the python-oracledb Thin and Thickmodes.The
protocolparameter is expected to be one of the stringstcp ortcps which indicates whether to use unencrypted network traffic orencrypted network traffic (TLS). The default value istcp. This value isused in both the python-oracledb Thin and Thick modes.The
https_proxyparameter is expected to be a string which indicatesthe name or IP address of a proxy host to use for tunneling secureconnections. This value is used in both the python-oracledb Thin and Thickmodes.The
https_proxy_portparameter is expected to be an integer whichindicates the port that is to be used to communicate with the proxy host.The default value is0. This value is used in both the python-oracledb Thinand Thick modes.The
service_nameparameter is expected to be a string which indicatesthe service name of the database. This value is used in both thepython-oracledb Thin and Thick modes.The
instance_nameparameter is expected to be a string which indicatesthe instance name of the database. This value is used in both thepython-oracledb Thin and Thick modes.The
sidparameter is expected to be a string which indicates the SID ofthe database. It is recommended to useservice_nameinstead. This valueis used in both the python-oracledb Thin and Thick modes.The
server_typeparameter is expected to be a string that indicates thetype of server connection that should be established. If specified, itshould be one ofdedicated,shared, orpooled. This value is used inboth the python-oracledb Thin and Thick modes.The
cclassparameter is expected to be a string that identifies theconnection class to use forDatabase Resident Connection Pooling (DRCP). This value is used in both thepython-oracledb Thin and Thick modes.The
purityparameter is expected to be one of theoracledb.PURITY_* constants that identifies thepurity to use for DRCP. This value is used in both the python-oracledb Thinand Thick modes. Internally pooled connections will default to a purity ofPURITY_SELF.The
expire_timeparameter is expected to be an integer which indicatesthe number of minutes between the sending of keepalive probes. If thisparameter is set to a value greater than zero it enables keepalive. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is0 minutes.The
retry_countparameter is expected to be an integer that identifiesthe number of times that a connection attempt should be retried before theattempt is terminated. This value is used in both the python-oracledb Thinand Thick modes. The default value is0.The
retry_delayparameter is expected to be an integer that identifiesthe number of seconds to wait before making a new connection attempt. Thisvalue is used in both the python-oracledb Thin and Thick modes. The defaultvalue is1 seconds.The
tcp_connect_timeoutparameter is expected to be a float thatindicates the maximum number of seconds to wait for establishing aconnection to the database host. This value is used in both thepython-oracledb Thin and Thick modes. The default value is20.0 seconds.The
ssl_server_dn_matchparameter is expected to be a boolean thatindicates whether the server certificate distinguished name (DN) should bematched in addition to the regular certificate verification that isperformed. Note that if the ssl_server_cert_dn parameter is not provided,host name matching is performed instead. This value is used in both thepython-oracledb Thin and Thick modes. The default value isTrue.The
ssl_server_cert_dnparameter is expected to be a string thatindicates the distinguished name (DN) which should be matched with theserver. This value is ignored if the ssl_server_dn_match parameter is notset to the valueTrue. This value is used in both the python-oracledb Thinand Thick modes.The
wallet_locationparameter is expected to be a string thatidentifies the directory where the wallet can be found. In python-oracledbThin mode, this must be the directory of the PEM-encoded wallet file,ewallet.pem. In python-oracledb Thick mode, this must be the directory ofthe file, cwallet.sso. This value is used in both the python-oracledb Thinand Thick modes.The
externalauthparameter is a boolean that determines whether to useexternal authentication. This value is only used in the python-oracledbThick mode. The default value isFalse.The
eventsparameter is expected to be a boolean that specifies whetherthe events mode should be enabled. This value is only used in thepython-oracledb Thick mode. This parameter is needed for continuousquery notification and high availability event notifications. The defaultvalue isFalse.The
modeparameter is expected to be an integer that identifies theauthorization mode to use. This value is used in both the python-oracledbThin and Thick modes.The default value isoracledb.AUTH_MODE_DEFAULT.The
disable_oobparameter is expected to be a boolean that indicateswhether out-of-band breaks should be disabled. This value is only usedin the python-oracledb Thin mode and has no effect on Windows whichdoes not support this functionality. The default value isFalse.The
stmtcachesizeparameter is expected to be an integer thatidentifies the initial size of the statement cache. This value is used inboth the python-oracledb Thin and Thick modes. The default is the value ofdefaults.stmtcachesize.The
editionparameter is expected to be a string that indicates theedition to use for the connection. It requires Oracle Database 11.2, orlater. This parameter cannot be used simultaneously with thecclassparameter.The
tagparameter is expected to be a string that identifies the typeof connection that should be returned from a pool. This value is only usedin the python-oracledb Thick mode.The
matchanytagparameter is expected to be a boolean specifyingwhether any tag can be used when acquiring a connection from the pool. Thisvalue is only used in the python-oracledb Thick mode when acquiring aconnection from a pool. The default value isFalse.The
config_dirparameter is expected to be a string that indicates thedirectory in which thetnsnames.ora configuration fileis located.The
appcontextparameter is expected to be a list of 3-tuples thatidentifies the application context used by the connection. This parametershould contain namespace, name, and value and each entry in the tupleshould be a string.The
shardingkeyparameter andsupershardingkeyparameters, ifspecified, are expected to be a sequence of values which identifies thedatabase shard to connect to. The key values can be a list of strings,numbers, bytes, or dates. These values are only used in thepython-oracledb Thick mode and are ignored in the Thin mode. SeeConnecting to Oracle Globally Distributed Database.The
debug_jdwpparameter is expected to be a string with the formathost=<host>;port=<port> that specifies the host and port of the PL/SQLdebugger. This allows using the Java Debug Wire Protocol (JDWP) to debugPL/SQL code invoked by python-oracledb. This value is only used in thepython-oracledb Thin mode. For python-oracledb Thick mode, set theORA_DEBUG_JDWPenvironment variable which has the same syntax. For moreinformation, seeDebugging PL/SQL with the Java Debug Wire Protocol.The
connection_id_prefixparameter is expected to be a string and isadded to the beginning of the generatedconnection_idthat is sent tothe database fortracing. This valueis only used in the python-oracledb Thin mode.The
ssl_contextparameter is expected to be anSSLContext object which is usedfor connecting to the database using TLS. This SSL context will bemodified to include the private key or any certificates found in aseparately supplied wallet. This parameter should only be specified ifthe default SSLContext object cannot be used. This value is only used inthe python-oracledb Thin mode.The
sduparameter is expected to be an integer that returns therequested size of the Session Data Unit (SDU), in bytes. The value tunesinternal buffers used for communication to the database. Bigger values canincrease throughput for large queries or bulk data loads, but at the costof higher memory use. The SDU size that will actually be used is negotiateddown to the lower of this value and the database network SDU configurationvalue. See theDatabase Net Services documentation for more details. This value is used in both thepython-oracledb Thin and Thick modes. The default value is8192 bytes.The
pool_boundaryparameter is expected to be one of the stringsstatement ortransaction which indicates when pooledDRCPor PRCP connections can be returned to the pool. If the value isstatement, then pooled DRCP or PRCP connections are implicitly releasedback to the DRCP or PRCP pool when the connection is stateless (that is,there are no active cursors, active transactions, temporary tables, ortemporary LOBs). If the value istransaction, then pooled DRCP or PRCPconnections are implicitly released back to the DRCP or PRCP pool wheneither one of the methodsConnection.commit()orConnection.rollback()are called. This parameter requires the useof DRCP or PRCP with Oracle Database 23ai (or later). SeeImplicit Connection Pooling for more information. This value is used in boththe python-oracledb Thin and Thick modes.The
use_tcp_fast_openparameter is expected to be a boolean whichindicates whether to use TCP Fast Open which is anOracle AutonomousDatabase Serverless (ADB-S) specific feature that canreduce the latency in round-trips to the database after a connection hasbeen established. This feature is only available with certain versions ofADB-S. This value is used in both python-oracledb Thin and Thick modes.The default value isFalse.The
ssl_versionparameter is expected to be one of the constantsssl.TLSVersion.TLSv1_2 orssl.TLSVersion.TLSv1_3 which identifies theTLS protocol version used. These constants are defined in the Pythonssl module. Thisparameter can be specified when establishing connections with the protocol“tcps”. This value is used in both python-oracledb Thin and Thick modes.The valuessl.TLSVersion.TLSv1_3 requires Oracle Database 23ai. If youare using python-oracledb Thick mode, Oracle Client 23ai is additionallyrequired.The
use_sniparameter is expected to be a boolean which indicateswhether to use the TLS Server Name Indication (SNI) extension to bypass thesecond TLS negotiation that would otherwise be required. This parameter isused in both python-oracledb Thin and Thick modes. This parameter requiresOracle Database 23.7. The default value isFalse. See theDatabase NetServices documentation for more details.The
programparameter is expected to be a string which specifies thename of the executable program or application connected to OracleDatabase. This value is only used in the python-oracledb Thin mode. Thedefault is the value ofdefaults.program.The
machineparameter is expected to be a string which specifies themachine name of the client connecting to Oracle Database. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.machine.The
terminalparameter is expected to be a string which specifies theterminal identifier from which the connection originates. This value isonly used in the python-oracledb Thin mode. The default is the value ofdefaults.terminal.The
osuserparameter is expected to be a string which specifies theoperating system user that initiates the database connection. This valueis only used in the python-oracledb Thin mode. The default value is thevalue ofdefaults.osuser.The
driver_nameparameter is expected to be a string which specifiesthe driver used by the client to connect to Oracle Database. This valueis used in both the python-oracledb Thin and Thick modes. The default isthe value ofdefaults.driver_name.The
thick_mode_dsn_passthroughparameter is expected to be a booleanwhich indicates whether the connect string should be passed unchanged tothe Oracle Client libraries for parsing when using python-oracledb Thickmode. If this parameter is set toFalse in Thick mode, connect stringsare parsed by python-oracledb itself and a generated connect descriptor issent to the Oracle Client libraries. This value is only used in thepython-oracledb Thick mode. The default value isdefaults.thick_mode_dsn_passthrough. For more information, seeUsing Optional Oracle Configuration Files.The
extra_auth_paramsparameter is expected to be a dictionarycontaining the configuration parameters necessary for Oracle Databaseauthentication usingOCI orAzure cloud native authentication plugins. This value isused in both the python-oracledb Thin and Thick modes. SeeToken-Based Authentication.The
pool_nameparameter is expected to be a string which specifies thename of the pool when using multiple DRCP pools with Oracle Database 23.4or later. This value is used in both python-oracledb Thin and Thick modes.SeeDRCP Pool Names.The
handleparameter is expected to be an integer which represents apointer to a valid service context handle. This value is only used in thepython-oracledb Thick mode. It should be used with extreme caution. Thedefault value is0.Changed in version 3.2.0:The
pool_nameparameter was added.Changed in version 3.0.0:The
use_sni,instance_name,thick_mode_dsn_passthrough,extra_auth_params, andinstance_nameparameters were added.Changed in version 2.5.0:The
program,machine,terminal,osuser, anddriver_nameparameters were added. Support foreditionandappcontextwas added to python-oracledb Thin mode.Changed in version 2.3.0:The default value of the
retry_delayparameter was changed from0seconds to1 second. The default value of thetcp_connect_timeoutparameter was changed from60.0 seconds to20.0 seconds. Theping_timeoutandssl_versionparameters were added.Changed in version 2.1.0:The
pool_boundaryanduse_tcp_fast_openparameters were added.Changed in version 2.0.0:The
ssl_contextandsduparameters were added.Changed in version 1.4.0:The
connection_id_prefixparameter was added.
- oracledb.SparseVector(num_dimensions,indices,values)
Creates and returns aSparseVector object.
The
num_dimensionsparameter is the number of dimensions contained inthe vector.The
indicesparameter is the indices (zero-based) of non-zero valuesin the vector.The
valuesparameter is the non-zero values stored in the vector.Added in version 3.0.0.
- oracledb.register_params_hook(hook_function)
Registers a user parameter hook function that will be called internally bypython-oracledb prior to connection or pool creation. The hook functionaccepts a copy of the parameters that will be used to create the pool orstandalone connection and may modify them. For example, the cloud nativeauthentication plugins modify the “access_token” parameter with a functionthat will acquire the token using information found in the“extra_auth_parms” parameter.
Multiple hooks may be registered. They will be invoked in order ofregistration.
To unregister a user function, use
oracledb.unregister_params_hook().SeeUsing Parameter Hook Functions.
This method is an extension to the DB API definition.Added in version 3.0.0.
- oracledb.register_password_type(password_type,hook_function)
Registers a user password hook function that will be called internally bypython-oracledb when a password is supplied as a dictionary containing thegiven
password_typeas the key “type”. The hook function is called forpasswords specified as thepassword,newpasswordandwallet_parameterparameters in calls tooracledb.connect(),oracledb.create_pool(),oracledb.connect_async(), andoracledb.create_pool_async().Your hook function is expected to accept the dictionary supplied by theapplication and return the valid password.
Calling
register_password_type()with thehook_functionparameter set toNone will result in a previouslyregistered user function being removed and the default behavior restored.SeeUsing Password Hook Functions.
This method is an extension to the DB API definition.Added in version 3.0.0.
- oracledb.register_protocol(protocol,hook_function)
Registers a user protocol hook function that will be called internally bypython-oracledb Thin mode prior to connection or pool creation. The hookfunction will be invoked when
oracledb.connect(),oracledb.create_pool(),oracledb.connect_async(), ororacledb.create_pool_async()are called with adsnparametervalue prefixed with the specified protocol. The user function will also beinvoked whenConnectParams.parse_connect_string()is called in Thinor Thick modes with a similarconnect_stringparameter value.Your hook function is expected to construct valid connection details. Forexample, if a hook function is registered for the “ldaps” protocol, thencalling
oracledb.connect()with a connection string prefixed with“ldaps://” will invoke the function. The function can then perform LDAPlookup to retrieve and set the actual database information that will beused internally by python-oracledb to complete the connection creation.The
protocolparameter is a string that will be matched against theprefix appearing before “://” in connection strings.The
hook_functionparameter should be a function with the signature:hook_function(protocol,protocol_arg,params)
The hook function will be called with the following arguments:
The
protocolparameter is the value that was registered.The
protocol_argparameter is the section after “://” in theconnection string used in the connection or pool creation call, or passedtoparse_connect_string().The
paramsparameter is an instance ofConnectParams.When your hook function is invoked internally prior to connection or poolcreation,
paramswill be the ConnectParams instance originally passedto theoracledb.connect(),oracledb.create_pool(),oracledb.connect_async(), ororacledb.create_pool_async()call, if such an instance was passed. Otherwise it will be a newConnectParams instance. The hook function should parseprotocolandprotocol_argand take any desired action to updateparamsattributes with appropriate connectionparameters. Attributes can be set usingConnectParams.set()orConnectParams.parse_connect_string(). The ConnectParams instancewill then be used to complete the connection or pool creation.When your hook function is invoked by
ConnectParams.parse_connect_string(), thenparamswill be theinvoking ConnectParams instance that you can update usingConnectParams.set()orConnectParams.parse_connect_string().
Internal hook functions for the “tcp” and “tcps” protocols arepre-registered but can be overridden if needed. If any other protocol hasnot been registered, then connecting will result in the error
DPY-4021:invalidprotocol.Calling
register_protocol()with thehook_functionparameter set toNone will result in a previously registered user functionbeing removed and the default behavior restored.SeeUsing Protocol Hook Functions for more information.
This method is an extension to the DB API definition.Added in version 2.5.0.
- oracledb.Time(hour,minute,second)
Constructs an object holding a time value.
Note
A time-only data type is not supported by Oracle Database. Calling thisfunction raises a NotSupportedError exception.
- oracledb.TimeFromTicks(ticks)
Constructs an object holding a time value from the given ticks value(number of seconds since the epoch; see the documentation of the standardPython time module for details).
Note
A time-only data type is not supported by Oracle Database. Calling thisfunction raises a NotSupportedError exception.
- oracledb.Timestamp(year,month,day,hour,minute,second)
Constructs an object holding a time stamp value.
- oracledb.TimestampFromTicks(ticks)
Constructs an object holding a time stamp value from the given ticks value(number of seconds since the epoch; see the documentation of the standardPython time module for details).
- oracledb.unregister_params_hook(hook_function)
Unregisters a user parameter function that was earlier registered with acall to
This method is an extension to the DB API definition.oracledb.register_params_hook().Added in version 3.0.0.
1.2.Oracledb IntervalYM Class
Objects of this class are returned for columns of type INTERVAL YEAR TO MONTHand can be passed to variables of typeoracledb.DB_TYPE_INTERVAL_YMThe class is acollections.namedtuple()class with two integer attributes,years andmonths.
Added in version 2.2.0.
1.3.Oracledb JsonId Class
Objects of this class are returned bySODA in the_idattribute of documents stored in native collections when using Oracle Database23.4 (and later). It is a subclass of thebytes class.
Added in version 2.1.0.
1.4.Oracledb __future__ Object
Special object that contains attributes which control the behavior ofpython-oracledb, allowing for opting in for new features.
This method is an extension to the DB API definition.1.5.Oracledb Constants
1.5.1.General
- oracledb.apilevel
String constant stating the supported DB API level. Currently ‘2.0’.
- oracledb.paramstyle
String constant stating the type of parameter marker formatting expected bythe interface. Currently ‘named’ as in ‘where name = :name’.
- oracledb.threadsafety
Integer constant stating the level of thread safety that the interfacesupports. Currently 2, which means that threads may share the module andconnections, but not cursors. Sharing means that a thread may use aresource without wrapping it using a mutex semaphore to implement resourcelocking.
- oracledb.version
- oracledb.__version__
String constant stating the version of the module. Currently ‘3.3.0b1’.
This attribute is an extension to the DB API definition.
1.5.2.Advanced Queuing: Delivery Modes
The AQ Delivery mode constants are possible values for thedeliverymode attribute of thedequeue options object passed as theoptions parameterto theQueue.deqone(),Queue.deqmany(),AsyncQueue.deqone(), andAsyncQueue.deqmany() methods as wellas thedeliverymode attribute of theenqueue options object passed as theoptions parameterto theQueue.enqone(),Queue.enqmany(),AsyncQueue.enqone(), andAsyncQueue.enqmany() methods. They arealso possible values for thedeliverymode attributeof themessage properties object passed as themsgproperties parameter to theQueue.deqone(),Queue.deqmany(),AsyncQueue.deqone(), orAsyncQueue.deqmany(), andQueue.enqone(),Queue.enqmany(),AsyncQueue.enqone(), orAsyncQueue.enqmany() methods.
- oracledb.MSG_BUFFERED
This constant is used to specify that enqueue or dequeue operations shouldenqueue or dequeue buffered messages, respectively. For multi-consumerqueues, asubscriber with buffered deliverymode needs to be created prior to enqueuing buffered messages.
This mode is not supported for bulk array operations in python-oracledbThick mode.
- oracledb.MSG_PERSISTENT
This constant is used to specify that enqueue/dequeue operations shouldenqueue or dequeue persistent messages. This is the default value.
- oracledb.MSG_PERSISTENT_OR_BUFFERED
This constant is used to specify that dequeue operations should dequeueeither persistent or buffered messages.
1.5.3.Advanced Queuing: Dequeue Modes
The AQ Dequeue mode constants are possible values for themode attribute of thedequeue options object. This object is theoptionsparameter for theQueue.deqone(),Queue.deqmany(),AsyncQueue.deqone(), orAsyncQueue.deqmany() methods.
- oracledb.DEQ_BROWSE
This constant is used to specify that dequeue should read the messagewithout acquiring any lock on the message (equivalent to a selectstatement).
- oracledb.DEQ_LOCKED
This constant is used to specify that dequeue should read and obtain awrite lock on the message for the duration of the transaction (equivalentto a select for update statement).
- oracledb.DEQ_REMOVE
This constant is used to specify that dequeue should read the message andupdate or delete it. This is the default value.
- oracledb.DEQ_REMOVE_NODATA
This constant is used to specify that dequeue should confirm receipt of themessage but not deliver the actual message content.
1.5.4.Advanced Queuing: Dequeue Navigation Modes
The AQ Dequeue Navigation mode constants are possible values for thenavigation attribute of thedequeue options object. This object is theoptionsparameter for theQueue.deqone(),Queue.deqmany(),AsyncQueue.deqone(), orAsyncQueue.deqmany() methods.
- oracledb.DEQ_FIRST_MSG
This constant is used to specify that dequeue should retrieve the firstavailable message that matches the search criteria. This resets theposition to the beginning of the queue.
- oracledb.DEQ_NEXT_MSG
This constant is used to specify that dequeue should retrieve the nextavailable message that matches the search criteria. If the previous messagebelongs to a message group, AQ retrieves the next available message thatmatches the search criteria and belongs to the message group. This is thedefault.
- oracledb.DEQ_NEXT_TRANSACTION
This constant is used to specify that dequeue should skip the remainder ofthe transaction group and retrieve the first message of the nexttransaction group. This option can only be used if message grouping isenabled for the current queue.
1.5.5.Advanced Queuing: Dequeue Visibility Modes
The AQ Dequeue Visibility mode constants are possible values for thevisibility attribute of thedequeue options object. This object is theoptionsparameter for theQueue.deqone(),Queue.deqmany(),AsyncQueue.deqone(), orAsyncQueue.deqmany() methods.
- oracledb.DEQ_IMMEDIATE
This constant is used to specify that dequeue should perform its work aspart of an independent transaction.
- oracledb.DEQ_ON_COMMIT
This constant is used to specify that dequeue should be part of the currenttransaction. This is the default value.
1.5.6.Advanced Queuing: Dequeue Wait Modes
The AQ Dequeue Wait mode constants are possible values for thewait attribute of thedequeue options object. This object is theoptionsparameter for theQueue.deqone(),Queue.deqmany(),AsyncQueue.deqone(), orAsyncQueue.deqmany() methods.
- oracledb.DEQ_NO_WAIT
This constant is used to specify that dequeue not wait for messages to beavailable for dequeuing.
- oracledb.DEQ_WAIT_FOREVER
This constant is used to specify that dequeue should wait forever formessages to be available for dequeuing. This is the default value.
1.5.7.Advanced Queuing: Enqueue Visibility Modes
The AQ Enqueue Visibility mode constants are possible values for thevisibility attribute of theenqueue options object. This object is theoptionsparameter for theQueue.enqone(),Queue.enqmany(),AsyncQueue.enqone(), orAsyncQueue.enqmany() methods.
- oracledb.ENQ_IMMEDIATE
This constant is used to specify that enqueue should perform its work aspart of an independent transaction.
The use of this constant withbulk enqueuing is onlysupported in python-oracledbThick mode.
- oracledb.ENQ_ON_COMMIT
This constant is used to specify that enqueue should be part of the currenttransaction. This is the default value.
1.5.8.Advanced Queuing: Message States
The AQ Message state constants are possible values for thestate attribute of themessage properties object. This object is themsgproperties parameter for theQueue.deqone(),Queue.deqmany(),AsyncQueue.deqone() orAsyncQueue.deqmany() andQueue.enqone(),Queue.enqmany(),AsyncQueue.enqone(), orAsyncQueue.enqmany() methods.
- oracledb.MSG_EXPIRED
This constant is used to specify that the message has been moved to theexception queue.
- oracledb.MSG_PROCESSED
This constant is used to specify that the message has been processed andhas been retained.
- oracledb.MSG_READY
This constant is used to specify that the message is ready to be processed.
- oracledb.MSG_WAITING
This constant is used to specify that the message delay has not yet beenreached.
1.5.9.Advanced Queuing: Other Constants
This section contains other constants that are used for Advanced Queueing.
These constants are extensions to the DB API definition.- oracledb.MSG_NO_DELAY
This constant is a possible value for the
delayattribute of themessage properties object passedas themsgpropertiesparameter to theQueue.deqone()orQueue.deqmany()andQueue.enqone()orQueue.enqmany()methods. It specifies that no delay should beimposed and the message should be immediately available for dequeuing. Thisis also the default value.
- oracledb.MSG_NO_EXPIRATION
This constant is a possible value for the
expirationattribute of themessage properties object passed as themsgpropertiesparameter to theQueue.deqone()orQueue.deqmany()andQueue.enqone()orQueue.enqmany()methods. It specifies that the message neverexpires. This is also the default value.
1.5.10.Connection Authorization Modes
The Connection Authorization mode constants belong to the enumeration calledAuthMode. They are possible values for themode parameters oforacledb.connect(),oracledb.create_pool(),oracledb.connect_async(), andoracledb.create_pool_async().These constants have deprecated the authorization modes used in the obsoletecx_Oracle driver.
Changed in version 2.3.0:The integer constants for the connection authorization modes were replacedwith the enumerationAuthMode.
- oracledb.AUTH_MODE_DEFAULT
This constant is used to specify that default authentication is to takeplace. This is the default value if no mode is passed at all.
It can be used for standalone and pooled connections in python-oracledbThin mode, and for standalone connections in Thick mode.
Its enumerated value can also be identified by
oracledb.AuthMode.DEFAULT.This constant deprecates the
DEFAULT_AUTHconstant that was used in theobsolete cx_Oracle driver, and was the defaultmodevalue.
- oracledb.AUTH_MODE_PRELIM
This constant is used to specify that preliminary authentication is to beused. This is needed for performing database startup and shutdown.
It can only be used in python-oracledb Thick mode for standaloneconnections.
Its enumerated value can also be identified by
oracledb.AuthMode.PRELIM.This constant deprecates the
PRELIM_AUTHconstant that was used in theobsolete cx_Oracle driver.
- oracledb.AUTH_MODE_SYSASM
This constant is used to specify that SYSASM access is to be acquired.
It can be used for standalone and pooled connections in python-oracledbThin mode, and for standalone connections in Thick mode.
Its enumerated value can also be identified by
oracledb.AuthMode.SYSASM.This constant deprecates the
SYSASMconstant that was used in theobsolete cx_Oracle driver.
- oracledb.AUTH_MODE_SYSBKP
This constant is used to specify that SYSBACKUP access is to be acquired.
It can be used for standalone and pooled connections in python-oracledbThin mode, and for standalone connections in Thick mode.
Its enumerated value can also be identified by
oracledb.AuthMode.SYSBKP.This constant deprecates the
SYSBKPconstant that was used in theobsolete cx_Oracle driver.
- oracledb.AUTH_MODE_SYSDBA
This constant is used to specify that SYSDBA access is to be acquired.
It can be used for standalone and pooled connections in python-oracledbThin mode, and for standalone connections in Thick mode.
Its enumerated value can also be identified by
oracledb.AuthMode.SYSDBA.This constant deprecates the
SYSDBAconstant that was used in theobsolete cx_Oracle driver.
- oracledb.AUTH_MODE_SYSDGD
This constant is used to specify that SYSDG access is to be acquired.
It can be used for standalone and pooled connections in python-oracledbThin mode, and for standalone connections in Thick mode.
Its enumerated value can also be identified by
oracledb.AuthMode.SYSDGD.This constant deprecates the
SYSDGDconstant that was used in theobsolete cx_Oracle driver.
- oracledb.AUTH_MODE_SYSKMT
This constant is used to specify that SYSKM access is to be acquired.
It can be used for standalone and pooled connections in python-oracledbThin mode, and for standalone connections in Thick mode.
Its enumerated value can also be identified by
oracledb.AuthMode.SYSKMT.This constant deprecates the
SYSKMTconstant that was used in theobsolete cx_Oracle driver.
- oracledb.AUTH_MODE_SYSOPER
This constant is used to specify that SYSOPER access is to be acquired.
It can be used for standalone and pooled connections in python-oracledbThin mode, and for standalone connections in Thick mode.
Its enumerated value can also be identified by
oracledb.AuthMode.SYSOPER.This constant deprecates the
SYSOPERconstant that was used in theobsolete cx_Oracle driver.
- oracledb.AUTH_MODE_SYSRAC
This constant is used to specify that SYSRAC access is to be acquired.
It can be used for standalone and pooled connections in python-oracledbThin mode, and for standalone connections in Thick mode.
Its enumerated value can also be identified by
oracledb.AuthMode.SYSRAC.This constant deprecates the
SYSRACconstant that was used in theobsolete cx_Oracle driver.
1.5.11.Pipeline Operation Types
The Pipeline Operation type constants belong to the enumeration calledPipelineOpType. The pipelining constants listed below are used to identifythe type of operation added. They are possible values for thePipelineOp.op_type attribute.
Added in version 2.4.0.
- oracledb.PIPELINE_OP_TYPE_CALL_FUNC
This constant identifies the type of operation as the calling of a storedfunction.
This enumerated value can also be identified by
oracledb.PipelineOpType.CALL_FUNC.
- oracledb.PIPELINE_OP_TYPE_CALL_PROC
This constant identifies the type of operation as the calling of a storedprocedure.
This enumerated value can also be identified by
oracledb.PipelineOpType.CALL_PROC.
- oracledb.PIPELINE_OP_TYPE_COMMIT
This constant identifies the type of operation as the performing of acommit.
This enumerated value can also be identified by
oracledb.PipelineOpType.COMMIT.
- oracledb.PIPELINE_OP_TYPE_EXECUTE
This constant identifies the type of operation as the executing of astatement.
This enumerated value can also be identified by
oracledb.PipelineOpType.EXECUTE.
- oracledb.PIPELINE_OP_TYPE_EXECUTE_MANY
This constant identifies the type of operations as the executing of astatement multiple times.
This enumerated value can also be identified by
oracledb.PipelineOpType.EXECUTE_MANY.
- oracledb.PIPELINE_OP_TYPE_FETCH_ALL
This constant identifies the type of operation as the executing of aquery and returning all of the rows from the result set.
This enumerated value can also be identified by
oracledb.PipelineOpType.FETCH_ALL.
- oracledb.PIPELINE_OP_TYPE_FETCH_MANY
This constant identifies the type of operation as the executing of aquery and returning up to the specified number of rows from the resultset.
This enumerated value can also be identified by
oracledb.PipelineOpType.FETCH_MANY.
- oracledb.PIPELINE_OP_TYPE_FETCH_ONE
This constant identifies the type of operation as the executing of a queryand returning the first row of the result set.
This enumerated value can also be identified by
oracledb.PipelineOpType.FETCH_ONE.
1.5.12.Database Shutdown Modes
The Database Shutdown mode constants are possible values for themodeparameter of theConnection.shutdown() method.
- oracledb.DBSHUTDOWN_ABORT
This constant is used to specify that the caller should not wait forcurrent processing to complete or for users to disconnect from thedatabase. This should only be used in unusual circumstances since databaserecovery may be necessary upon next startup.
- oracledb.DBSHUTDOWN_FINAL
This constant is used to specify that the instance can be truly halted.This should only be done after the database has been shutdown with one ofthe other modes (except abort) and the database has been closed anddismounted using the appropriate SQL commands.
- oracledb.DBSHUTDOWN_IMMEDIATE
This constant is used to specify that all uncommitted transactions shouldbe rolled back and any connected users should be disconnected.
- oracledb.DBSHUTDOWN_TRANSACTIONAL
This constant is used to specify that further connections to the databaseshould be prohibited and no new transactions should be allowed. It thenwaits for all active transactions to complete.
- oracledb.DBSHUTDOWN_TRANSACTIONAL_LOCAL
This constant is used to specify that further connections to the databaseshould be prohibited and no new transactions should be allowed. It thenwaits for only local active transactions to complete.
1.5.13.Event Types
The Event type constants are possible values for theMessage.typeattribute of the messages that are sent for subscriptions created by theConnection.subscribe() method.
- oracledb.EVENT_AQ
This constant is used to specify that one or more messages are availablefor dequeuing on the queue specified when the subscription was created.
- oracledb.EVENT_DEREG
This constant is used to specify that the subscription has beenderegistered and no further notifications will be sent.
- oracledb.EVENT_NONE
This constant is used to specify no information is available about theevent.
- oracledb.EVENT_OBJCHANGE
This constant is used to specify that a database change has taken place ona table registered with the
Subscription.registerquery()method.
- oracledb.EVENT_QUERYCHANGE
This constant is used to specify that the result set of a query registeredwith the
Subscription.registerquery()method has been changed.
- oracledb.EVENT_SHUTDOWN
This constant is used to specify that the instance is in the process ofbeing shut down.
- oracledb.EVENT_SHUTDOWN_ANY
This constant is used to specify that any instance (when running RAC) is inthe process of being shut down.
- oracledb.EVENT_STARTUP
This constant is used to specify that the instance is in the process ofbeing started up.
1.5.14.Operation Codes
The Operation code constants are possible values for theoperationsparameter for theConnection.subscribe() method. One or more of thesevalues can be OR’ed together. These values are also used by theMessageTable.operation orMessageQuery.operation attributes ofthe messages that are sent.
- oracledb.OPCODE_ALLOPS
This constant is used to specify that messages should be sent for alloperations.
- oracledb.OPCODE_ALLROWS
This constant is used to specify that the table or query has beencompletely invalidated.
- oracledb.OPCODE_ALTER
This constant is used to specify that messages should be sent when aregistered table has been altered in some fashion by DDL, or that themessage identifies a table that has been altered.
- oracledb.OPCODE_DELETE
This constant is used to specify that messages should be sent when data isdeleted, or that the message identifies a row that has been deleted.
- oracledb.OPCODE_DROP
This constant is used to specify that messages should be sent when aregistered table has been dropped, or that the message identifies a tablethat has been dropped.
- oracledb.OPCODE_INSERT
This constant is used to specify that messages should be sent when data isinserted, or that the message identifies a row that has been inserted.
- oracledb.OPCODE_UPDATE
This constant is used to specify that messages should be sent when data isupdated, or that the message identifies a row that has been updated.
1.5.15.Connection Pool Get Modes
The Connection Pool Get mode constants belong to the enumeration calledPoolGetMode. They are possible values for thegetmode parameters oforacledb.create_pool(),oracledb.create_pool_async(),PoolParams.set(), and for related attributes. These constants havedeprecated the Session Pool mode constants that were used in the obsoletecx_Oracle driver.
Changed in version 2.3.0:The integer constants for the connection pool creation, reconfiguration,and acquisitiongetmode parameters were replaced with the enumerationPoolGetMode.
- oracledb.POOL_GETMODE_FORCEGET
This constant is used to specify that a new connection should be createdand returned by
ConnectionPool.acquire()if there are no freeconnections available in the pool and the pool is already at its maximumsize.When a connection acquired in this mode is eventually released back to thepool, it will be dropped and not added to the pool if the pool is still atits maximum size.
This enumerated value can also be identified by
oracledb.PoolGetMode.FORCEGET.This constant deprecates the
SPOOL_ATTRVAL_FORCEGETconstant that wasused in the obsolete cx_Oracle driver.
- oracledb.POOL_GETMODE_NOWAIT
This constant is used to specify that an exception should be raised by
ConnectionPool.acquire()when all currently created connections arealready in use and soacquire()cannot immediatelyreturn a connection. Note the exception may occur even if the pool issmaller than its maximum size.This enumerated value can also be identified by
oracledb.PoolGetMode.NOWAIT.This constant deprecates the
SPOOL_ATTRVAL_NOWAITconstant that wasused in the obsolete cx_Oracle driver, and was the defaultgetmodevalue.
- oracledb.POOL_GETMODE_WAIT
This constant is used to specify that
ConnectionPool.acquire()should wait until a connection is available if there are currently no freeconnections available in the pool. This is the default value.This enumerated value can also be identified by
oracledb.PoolGetMode.WAIT.This constant deprecates the
SPOOL_ATTRVAL_WAITconstant that was usedin the obsolete cx_Oracle driver.
- oracledb.POOL_GETMODE_TIMEDWAIT
This constant is used to specify that
ConnectionPool.acquire()should wait for a period of time (defined by thewait_timeoutparameter) for a connection to become available before returning with anerror.This enumerated value can also be identified by
oracledb.PoolGetMode.TIMEDWAIT.This constant deprecates the
SPOOL_ATTRVAL_TIMEDWAITconstant that wasused in the obsolete cx_Oracle driver.
1.5.16.Connection Pool Purity Constants
The Connection Pool Purity constants belong to the enumeration calledPurity. They are possible values for theDatabase Resident Connection Pooling (DRCP)purity parameteroforacledb.create_pool(),ConnectionPool.acquire(),oracledb.connect(),oracledb.create_pool_async(), andoracledb.connect_async(). These constants have deprecated the SessionPool purity constants that were used in the obsolete cx_Oracle driver.
Changed in version 2.3.0:The integer constants for the connection pool get modes were replacedwith the enumerationPurity.
- oracledb.PURITY_DEFAULT
This constant is used to specify that the purity of the session is thedefault value identified by Oracle (see Oracle’s documentation for moreinformation). This is the default value.
This enumerated value can also be identified by
oracledb.Purity.DEFAULT.This constant deprecates the
ATTR_PURITY_DEFAULTconstant that was usedin the obsolete cx_Oracle driver, and was the defaultpurityvalue.
- oracledb.PURITY_NEW
This constant is used to specify that the session acquired from the poolshould be new and not have any prior session state.
This enumerated value can also be identified by
oracledb.Purity.NEW.This constant deprecates the
ATTR_PURITY_NEWconstant that was used inthe obsolete cx_Oracle driver.
- oracledb.PURITY_SELF
This constant is used to specify that the session acquired from the poolneed not be new and may have prior session state.
This enumerated value can also be identified by
oracledb.Purity.SELF.This constant deprecates the
ATTR_PURITY_SELFconstant that was used inthe obsolete cx_Oracle driver.
1.5.17.Subscription Grouping Classes
The Subscription Grouping Class constants are possible values for thegroupingClass parameter of theConnection.subscribe() method.
- oracledb.SUBSCR_GROUPING_CLASS_TIME
This constant is used to specify that events are to be grouped by theperiod of time in which they are received.
1.5.18.Subscription Grouping Types
The Subscription Grouping Type constants are possible values for thegroupingType parameter of theConnection.subscribe() method.
- oracledb.SUBSCR_GROUPING_TYPE_SUMMARY
This constant is used to specify that when events are grouped a summary ofthe events should be sent instead of the individual events. This is thedefault value.
- oracledb.SUBSCR_GROUPING_TYPE_LAST
This constant is used to specify that when events are grouped the lastevent that makes up the group should be sent instead of the individualevents.
1.5.19.Subscription Namespaces
The Subscription Namespace constants are possible values for thenamespaceparameter of theConnection.subscribe() method.
- oracledb.SUBSCR_NAMESPACE_AQ
This constant is used to specify that notifications should be sent when aqueue has messages available to dequeue.
- oracledb.SUBSCR_NAMESPACE_DBCHANGE
This constant is used to specify that database change notification or querychange notification messages are to be sent. This is the default value.
1.5.20.Subscription Protocols
The Subscription Protocol constants are possible values for theprotocolparameter of theConnection.subscribe() method.
- oracledb.SUBSCR_PROTO_CALLBACK
This constant is used to specify that notifications will be sent to thecallback routine identified when the subscription was created. It is thedefault value and the only value currently supported.
- oracledb.SUBSCR_PROTO_HTTP
This constant is used to specify that notifications will be sent to anHTTP URL when a message is generated. This value is currently notsupported.
- oracledb.SUBSCR_PROTO_MAIL
This constant is used to specify that notifications will be sent to ane-mail address when a message is generated. This value is currently notsupported.
- oracledb.SUBSCR_PROTO_OCI
This constant is used to specify that notifications will be sent to thecallback routine identified when the subscription was created. It is thedefault value and the only value currently supported.
Deprecated since python-oracledb 1.0.
- oracledb.SUBSCR_PROTO_SERVER
This constant is used to specify that notifications will be sent to aPL/SQL procedure when a message is generated. This value is currently notsupported.
1.5.21.Subscription Quality of Service
The Subscription Quality of Service constants are possible values for theqos parameter of theConnection.subscribe() method. One or more ofthese values can be OR’ed together.
- oracledb.SUBSCR_QOS_BEST_EFFORT
This constant is used to specify that best effort filtering for queryresult set changes is acceptable. False positive notifications may bereceived. This behaviour may be suitable for caching applications.
- oracledb.SUBSCR_QOS_DEREG_NFY
This constant is used to specify that the subscription should beautomatically unregistered after the first notification is received.
- oracledb.SUBSCR_QOS_QUERY
This constant is used to specify that notifications should be sent if theresult set of the registered query changes. By default, no false positivenotifications will be generated.
- oracledb.SUBSCR_QOS_RELIABLE
This constant is used to specify that notifications should not be lost inthe event of database failure.
- oracledb.SUBSCR_QOS_ROWIDS
This constant is used to specify that the rowids of the inserted, updatedor deleted rows should be included in the message objects that are sent.
1.5.22.DB API Types
- oracledb.BINARY
This type object is used to describe columns in a database that containbinary data. The database types
DB_TYPE_RAWandDB_TYPE_LONG_RAWwill compare equal to this value. If a variable iscreated with this type, the database typeDB_TYPE_RAWwill be used.
- oracledb.DATETIME
This type object is used to describe columns in a database that are dates.The database types
DB_TYPE_DATE,DB_TYPE_TIMESTAMP,DB_TYPE_TIMESTAMP_LTZandDB_TYPE_TIMESTAMP_TZwill allcompare equal to this value. If a variable is created with thistype, the database typeDB_TYPE_DATEwill be used.
- oracledb.NUMBER
This type object is used to describe columns in a database that arenumbers. The database types
DB_TYPE_BINARY_DOUBLE,DB_TYPE_BINARY_FLOAT,DB_TYPE_BINARY_INTEGERandDB_TYPE_NUMBERwill all compare equal to this value. If a variableis created with this type, the database typeDB_TYPE_NUMBERwill beused.
- oracledb.ROWID
This type object is used to describe the pseudo column “rowid”. Thedatabase types
DB_TYPE_ROWIDandDB_TYPE_UROWIDwillcompare equal to this value. If a variable is created with this type, thedatabase typeDB_TYPE_VARCHARwill be used.
- oracledb.STRING
This type object is used to describe columns in a database that arestrings. The database types
DB_TYPE_CHAR,DB_TYPE_LONG,DB_TYPE_NCHAR,DB_TYPE_NVARCHARandDB_TYPE_VARCHARwill all compare equal to this value. If a variable is created with thistype, the database typeDB_TYPE_VARCHARwill be used.
1.5.23.Database Types
All of these types are extensions to the DB API definition. They are found inquery and object metadata. They can also be used to specify the database typewhen binding data.
Also see the tableSupported Oracle Database Data Types.
- oracledb.DB_TYPE_BFILE
Describes columns, attributes or array elements in a database that are oftype BFILE. It will compare equal to the DB API type
BINARY.
- oracledb.DB_TYPE_BINARY_DOUBLE
Describes columns, attributes or array elements in a database that are oftype BINARY_DOUBLE. It will compare equal to the DB API type
NUMBER.
- oracledb.DB_TYPE_BINARY_FLOAT
Describes columns, attributes or array elements in a database that areof type BINARY_FLOAT. It will compare equal to the DB API type
NUMBER.
- oracledb.DB_TYPE_BINARY_INTEGER
Describes attributes or array elements in a database that are of typeBINARY_INTEGER. It will compare equal to the DB API type
NUMBER.
- oracledb.DB_TYPE_BLOB
Describes columns, attributes or array elements in a database that are oftype BLOB. It will compare equal to the DB API type
BINARY.
- oracledb.DB_TYPE_BOOLEAN
Describes attributes or array elements in a database that are of typeBOOLEAN. It is only available in Oracle 12.1 and higher and only withinPL/SQL.
- oracledb.DB_TYPE_CHAR
Describes columns, attributes or array elements in a database that are oftype CHAR. It will compare equal to the DB API type
STRING.Note that these are fixed length string values and behave differently fromVARCHAR2.
- oracledb.DB_TYPE_CLOB
Describes columns, attributes or array elements in a database that are oftype CLOB. It will compare equal to the DB API type
STRING.
- oracledb.DB_TYPE_CURSOR
Describes columns in a database that are of type CURSOR. In PL/SQL, theseare known as REF CURSOR.
- oracledb.DB_TYPE_DATE
Describes columns, attributes or array elements in a database that are oftype DATE. It will compare equal to the DB API type
DATETIME.
- oracledb.DB_TYPE_INTERVAL_DS
Describes columns, attributes or array elements in a database that are oftype INTERVAL DAY TO SECOND.
- oracledb.DB_TYPE_INTERVAL_YM
Describes columns, attributes or array elements in a database that are oftype INTERVAL YEAR TO MONTH.
- oracledb.DB_TYPE_JSON
Describes columns in a database that are of type JSON (with Oracle Database21 or later).
- oracledb.DB_TYPE_LONG
Describes columns, attributes or array elements in a database that are oftype LONG. It will compare equal to the DB API type
STRING.
- oracledb.DB_TYPE_LONG_RAW
Describes columns, attributes or array elements in a database that are oftype LONG RAW. It will compare equal to the DB API type
BINARY.
- oracledb.DB_TYPE_LONG_NVARCHAR
This constant can be used in output type handlers when fetching NCLOBcolumns as a string. (Note a type handler is not needed iforacledb.defaults.fetch_lobs is set to False). For INbinds, this constant can be used to create a bind variable in
Cursor.var()or viaCursor.setinputsizes(). TheDB_TYPE_LONG_NVARCHARvalue won’t be shown in query metadata since itis not a database type.It will compare equal to the DB API type
STRING.
- oracledb.DB_TYPE_NCHAR
Describes columns, attributes or array elements in a database that are oftype NCHAR. It will compare equal to the DB API type
STRING.Note that these are fixed length string values and behave differently fromNVARCHAR2.
- oracledb.DB_TYPE_NCLOB
Describes columns, attributes or array elements in a database that are oftype NCLOB. It will compare equal to the DB API type
STRING.
- oracledb.DB_TYPE_NUMBER
Describes columns, attributes or array elements in a database that are oftype NUMBER. It will compare equal to the DB API type
NUMBER.
- oracledb.DB_TYPE_NVARCHAR
Describes columns, attributes or array elements in a database that are oftype NVARCHAR2. It will compare equal to the DB API type
STRING.
- oracledb.DB_TYPE_OBJECT
Describes columns, attributes or array elements in a database that are aninstance of a named SQL or PL/SQL type.
- oracledb.DB_TYPE_RAW
Describes columns, attributes or array elements in a database that are oftype RAW. It will compare equal to the DB API type
BINARY.
- oracledb.DB_TYPE_ROWID
Describes columns, attributes or array elements in a database that are oftype ROWID or UROWID. It will compare equal to the DB API type
ROWID.
- oracledb.DB_TYPE_TIMESTAMP
Describes columns, attributes or array elements in a database that are oftype TIMESTAMP. It will compare equal to the DB API type
DATETIME.
- oracledb.DB_TYPE_TIMESTAMP_LTZ
Describes columns, attributes or array elements in a database that are oftype TIMESTAMP WITH LOCAL TIME ZONE. It will compare equal to the DB APItype
DATETIME.
- oracledb.DB_TYPE_TIMESTAMP_TZ
Describes columns, attributes or array elements in a database that are oftype TIMESTAMP WITH TIME ZONE. It will compare equal to the DB API type
DATETIME.
- oracledb.DB_TYPE_UNKNOWN
Describes columns, attributes or array elements in a database that areof an unknown type.
- oracledb.DB_TYPE_UROWID
Describes columns, attributes or array elements in a database that are oftype UROWID. It will compare equal to the DB API type
ROWID.Note
This type is not supported in python-oracledb Thick mode.SeeQuery Metadata in Thin and Thick Modes.
- oracledb.DB_TYPE_VARCHAR
Describes columns, attributes or array elements in a database that are oftype VARCHAR2. It will compare equal to the DB API type
STRING.
- oracledb.DB_TYPE_VECTOR
Describes columns, attributes or array elements in a database that are oftype VECTOR.
Added in version 2.2.0.
- oracledb.DB_TYPE_XMLTYPE
Describes columns, attributes or array elements in a database that are oftype SYS.XMLTYPE.
Added in version 2.0.0.
1.5.24.Database Type Synonyms
All of the following constants are deprecated and will be removed in a futureversion of python-oracledb.
- oracledb.BFILE
A synonym for
DB_TYPE_BFILE.Deprecated since cx_Oracle 8.0.
- oracledb.BLOB
A synonym for
DB_TYPE_BLOB.Deprecated since cx_Oracle 8.0.
- oracledb.BOOLEAN
A synonym for
DB_TYPE_BOOLEAN.Deprecated since cx_Oracle 8.0.
- oracledb.CLOB
A synonym for
DB_TYPE_CLOB.Deprecated since cx_Oracle 8.0.
- oracledb.CURSOR
A synonym for
DB_TYPE_CURSOR.Deprecated since cx_Oracle 8.0.
- oracledb.FIXED_CHAR
A synonym for
DB_TYPE_CHAR.Deprecated since cx_Oracle 8.0.
- oracledb.FIXED_NCHAR
A synonym for
DB_TYPE_NCHAR.Deprecated since cx_Oracle 8.0.
- oracledb.INTERVAL
A synonym for
DB_TYPE_INTERVAL_DS.Deprecated since cx_Oracle 8.0.
- oracledb.LONG_BINARY
A synonym for
DB_TYPE_LONG_RAW.Deprecated since cx_Oracle 8.0.
- oracledb.LONG_STRING
A synonym for
DB_TYPE_LONG.Deprecated since cx_Oracle 8.0.
- oracledb.NATIVE_FLOAT
A synonym for
DB_TYPE_BINARY_DOUBLE.Deprecated since cx_Oracle 8.0.
- oracledb.NATIVE_INT
A synonym for
DB_TYPE_BINARY_INTEGER.Deprecated since cx_Oracle 8.0.
- oracledb.NCHAR
A synonym for
DB_TYPE_NCHAR.Deprecated since cx_Oracle 8.0.
- oracledb.NCLOB
A synonym for
DB_TYPE_NCLOB.Deprecated since cx_Oracle 8.0.
- oracledb.OBJECT
A synonym for
DB_TYPE_OBJECT.Deprecated since cx_Oracle 8.0.
- oracledb.TIMESTAMP
A synonym for
DB_TYPE_TIMESTAMP.Deprecated since cx_Oracle 8.0.
1.5.25.Other Types
All of these types are extensions to the DB API definition.
- oracledb.ApiType
This type object is the Python type of the database API type constants
BINARY,DATETIME,NUMBER,ROWIDandSTRING.
- oracledb.DbType
This type object is the Python type of thedatabase type constants.
- oracledb.LOB
This type object is the Python type of
DB_TYPE_BLOB,DB_TYPE_BFILE,DB_TYPE_CLOBandDB_TYPE_NCLOBdatathat is returned from cursors.
1.5.26.Two-Phase Commit (TPC) Constants
The constants for the two-phase commit (TPC) functionstpc_begin() andtpc_end() are listedbelow.
- oracledb.TPC_BEGIN_JOIN
Joins an existing TPC transaction.
- oracledb.TPC_BEGIN_NEW
Creates a new TPC transaction.
- oracledb.TPC_BEGIN_PROMOTE
Promotes a local transaction to a TPC transaction.
- oracledb.TPC_BEGIN_RESUME
Resumes an existing TPC transaction.
- oracledb.TPC_END_NORMAL
Ends the TPC transaction participation normally.
- oracledb.TPC_END_SUSPEND
Suspends the TPC transaction.
1.5.27.Vector Format Constants
These constants belong to the enumeration calledVectorFormat and arepossible values for theFetchInfo.vector_format attribute.
Added in version 2.2.0.
Changed in version 2.3.0:The integer constants for the vector format constants were replaced withthe enumerationVectorFormat.
- oracledb.VECTOR_FORMAT_BINARY
This constant is used to represent the storage format of VECTOR columnsusing 8-bit unsigned integers.
This enumerated value can also be identified by
oracledb.VectorFormat.BINARY.Added in version 2.3.0.
- oracledb.VECTOR_FORMAT_FLOAT32
This constant is used to represent the storage format of VECTOR columnsusing 32-bit floating point numbers.
This enumerated value can also be identified by
oracledb.VectorFormat.FLOAT32.
- oracledb.VECTOR_FORMAT_FLOAT64
This constant is used to represent the storage format of VECTOR columnsusing 64-bit floating point numbers.
This enumerated value can also be identified by
oracledb.VectorFormat.FLOAT64.
- oracledb.VECTOR_FORMAT_INT8
This constant is used to represent the storage format of VECTOR columnsusing 8-bit signed integers.
This enumerated value can also be identified by
oracledb.VectorFormat.INT8.
1.6.Oracledb Exceptions
SeeCatching Exceptions for usage information.
- exceptionoracledb.Warning
Exception raised for important warnings and defined by the DB API but notactually used by python-oracledb.
- exceptionoracledb.Error
Exception that is the base class of all other exceptions defined bypython-oracledb and is a subclass of the Python StandardError exception(defined in the module exceptions).
- exceptionoracledb.InterfaceError
Exception raised for errors that are related to the database interfacerather than the database itself. It is a subclass of Error.
Exception messages of this class will have the prefix DPY and an errornumber in the range 1000 - 1999.
- exceptionoracledb.DatabaseError
Exception raised for errors that are related to the database. It is asubclass of Error.
Exception messages of this class will have the prefix DPY and an errornumber in the range 4000 - 4999.
- exceptionoracledb.DataError
Exception raised for errors that are due to problems with the processeddata. It is a subclass of DatabaseError.
Exception messages of this class are generated by the database and willhave a prefix such as ORA
- exceptionoracledb.OperationalError
Exception raised for errors that are related to the operation of thedatabase but are not necessarily under the control of the programmer. It isa subclass of DatabaseError.
Exception messages of this class will have the prefix DPY and an errornumber in the range 6000 - 6999.
- exceptionoracledb.IntegrityError
Exception raised when the relational integrity of the database is affected.It is a subclass of DatabaseError.
Exception messages of this class are generated by the database and willhave a prefix such as ORA
- exceptionoracledb.InternalError
Exception raised when the database encounters an internal error. It is asubclass of DatabaseError.
Exception messages of this class will have the prefix DPY and an errornumber in the range 5000 - 5999.
- exceptionoracledb.ProgrammingError
Exception raised for programming errors. It is a subclass of DatabaseError.
Exception messages of this class will have the prefix DPY and an errornumber in the range 2000 - 2999.
- exceptionoracledb.NotSupportedError
Exception raised when a method or database API was used which is notsupported by the database. It is a subclass of DatabaseError.
Exception messages of this class will have the prefix DPY and an errornumber in the range 3000 - 3999.
1.7.Oracledb _Error Objects
SeeCatching Exceptions for usage information.
Note
PEP 249 (Python Database API Specification v2.0) says the following aboutexception values:
[…] The values of these exceptions are not defined. They shouldgive the user a fairly good idea of what went wrong, though. […]
With python-oracledb every exception object has exactly one argument in theargs tuple. This argument is anoracledb._Error object which hasthe following six read-only attributes.
- _Error.code
Integer attribute representing the Oracle error number (ORA-XXXXX).
- _Error.offset
Integer attribute representing the error offset when applicable.
- _Error.full_code
String attribute representing the top-level error prefix and thecode that is shown in the
_Error.message.
- _Error.message
String attribute representing the Oracle message of the error. This messagemay be localized by the environment of the Oracle connection.
- _Error.context
String attribute representing the context in which the exception wasraised.
- _Error.isrecoverable
Boolean attribute representing whether the error is recoverable or not.This requires Oracle Database 12.1 (or later). If python-oracledb Thickmode is used, then Oracle Client 12.1 (or later) is also required.
SeeTransaction Guard for more information.
1.8.Oracledb Plugins
Thenamespace packageoracledb.plugins can contain plugins to extend the capability ofpython-oracledb. SeeBuilding Custom Plugins. Note that the namespaceoracledb.plugins.ldap_support is reserved for future use by thepython-oracledb project.
To use the python-oracledb plugins in your application, import usingimportoracledb.plugins.<nameofplugin>, for example:
importoracledb.plugins.oci_config_provider
Added in version 3.0.0.
1.8.1.Oracle Cloud Infrastructure (OCI) Object Storage Configuration Provider Plugin
oci_config_provider is a plugin that can be imported to provide access todatabase connection credentials and application configuration informationstored in theOCI Object Storage configuration provider.
This plugin is implemented as aconnection protocol hook function to handle connection strings which have the prefixconfig-ociobject, seeOCI Object Storage connection strings. The plugin parses these connection strings and gets thestored configuration information. Python-oracledb then uses this information toconnect to Oracle Database.
To use this plugin in python-oracledb Thick mode, you must setdefaults.thick_mode_dsn_passthrough toFalse. Alternatively useConnectParams.parse_connect_string(), seeUsing the ConnectParams Builder Class.
SeeUsing an OCI Object Storage Centralized Configuration Provider for more information.
Added in version 3.0.0.
1.8.2.Azure App Configuration Provider Plugin
azure_config_provider is a plugin that can be imported to provide access todatabase connection credentials and application configuration informationstored in theAzure App Configuration provider.
This plugin is implemented as aconnection protocol hook function to handle connection strings which have the prefixconfig-azure, seeAzure App Configuration connection strings. The plugin parses these connection strings and gets thestored configuration information. Python-oracledb then uses this information toconnect to Oracle Database.
To use this plugin in python-oracledb Thick mode, you must setdefaults.thick_mode_dsn_passthrough toFalse. Alternatively useConnectParams.parse_connect_string(), seeUsing the ConnectParams Builder Class.
SeeUsing an Azure App Centralized Configuration Provider for more information.
Added in version 3.0.0.
1.8.3.Oracle Cloud Infrastructure (OCI) Cloud Native Authentication Plugin
oci_tokens is a plugin that can be imported to use theOracle CloudInfrastructure (OCI) Software Development Kit (SDK) forgenerating access tokens when authenticating with OCI Identity and AccessManagement (IAM) token-based authentication.
This plugin is implemented as aparameter hook function which uses theextra_auth_params parameter values ofyour connection and pool creation calls to generate OCI IAM access tokens.Python-oracledb then uses these tokens to connect to Oracle Database.
SeeOCI Cloud Native Authentication with the oci_tokens Plugin for more information.
Added in version 3.0.0.
1.8.4.Azure Cloud Native Authentication Plugin
azure_tokens is a plugin that can be imported to use theMicrosoftAuthentication Library (MSAL)for generating access tokens when authenticating with OAuth 2.0 token-basedauthentication.
This plugin is implemented as aparameter hook function which uses theextra_auth_params parameter values ofyour connection and pool creation calls to generate OAuth2 access tokens.Python-oracledb then uses these tokens to connect to Oracle Database.
SeeAzure Cloud Native Authentication with the azure_tokens Plugin for more information.
Added in version 3.0.0.