Connection Object¶
Note
Any outstanding changes will be rolled back when the connection object is destroyed or closed.
-
Connection.
__enter__
()¶ The entry point for the connection as a context manager, a feature available in Python 2.5 and higher. It returns itself.
Note
This method is an extension to the DB API definition.
-
Connection.
__exit__
()¶ The exit point for the connection as a context manager, a feature available in Python 2.5 and higher. In the event of an exception, the transaction is rolled back; otherwise, the transaction is committed.
Note
This method is an extension to the DB API definition.
-
Connection.
action
¶ This write-only attribute sets the action column in the v$session table. It is a string attribute and cannot be set to None – use the empty string instead.
Note
This attribute is an extension to the DB API definition.
-
Connection.
autocommit
¶ This read-write attribute determines whether autocommit mode is on or off. When autocommit mode is on, all statements are committed as soon as they have completed executing.
Note
This attribute is an extension to the DB API definition.
-
Connection.
begin
([formatId, transactionId, branchId])¶ Explicitly begin a new transaction. Without parameters, this explicitly begins a local transaction; otherwise, this explicitly begins a distributed (global) transaction with the given parameters. See the Oracle documentation for more details.
Note that in order to make use of global (distributed) transactions, the
internal_name
andexternal_name
attributes must be set.Note
This method is an extension to the DB API definition.
-
Connection.
cancel
()¶ Cancel a long-running transaction.
Note
This method is an extension to the DB API definition.
-
Connection.
changepassword
(oldpassword, newpassword)¶ Change the password of the logon.
Note
This method is an extension to the DB API definition.
-
Connection.
client_identifier
¶ This write-only attribute sets the client_identifier column in the v$session table.
Note
This attribute is an extension to the DB API definition.
-
Connection.
clientinfo
¶ This write-only attribute sets the client_info column in the v$session table.
Note
This attribute is an extension to the DB API definition.
-
Connection.
close
()¶ Close the connection now, rather than whenever __del__ is called. The connection will be unusable from this point forward; an Error exception will be raised if any operation is attempted with the connection. The same applies to any cursor objects trying to use the connection.
-
Connection.
commit
()¶ Commit any pending transactions to the database.
-
Connection.
current_schema
¶ This read-write attribute sets the current schema attribute for the session.
Note
This attribute is an extension to the DB API definition.
-
Connection.
cursor
()¶ Return a new cursor object using the connection.
-
Connection.
dbop
¶ This write-only attribute sets the database operation that is to be monitored. This can be viewed in the DBOP_NAME column of the V$SQL_MONITOR table.
Note
This attribute is an extension to the DB API definition.
-
Connection.
deq
(name, options, msgproperties, payload)¶ Returns a message id after successfully dequeuing a message. The options object can be created using
deqoptions()
and the msgproperties object can be created usingmsgproperties()
. The payload must be an object created usingObjectType.newobject()
.New in version 5.3.
Note
This method is an extension to the DB API definition.
-
Connection.
deqoptions
()¶ Returns an object specifying the options to use when dequeuing messages. See Dequeue Options for more information.
New in version 5.3.
Note
This method is an extension to the DB API definition.
-
Connection.
dsn
¶ This read-only attribute returns the TNS entry of the database to which a connection has been established.
Note
This attribute is an extension to the DB API definition.
-
Connection.
edition
¶ This read-only attribute gets the session edition and is only available in Oracle Database 11.2 (both client and server must be at this level or higher for this to work).
New in version 5.3.
Note
This attribute is an extension to the DB API definition.
-
Connection.
encoding
¶ This read-only attribute returns the IANA character set name of the character set in use by the Oracle client for regular strings.
Note
This attribute is an extension to the DB API definition.
-
Connection.
enq
(name, options, msgproperties, payload)¶ Returns a message id after successfully enqueuing a message. The options object can be created using
enqoptions()
and the msgproperties object can be created usingmsgproperties()
. The payload must be an object created usingObjectType.newobject()
.New in version 5.3.
Note
This method is an extension to the DB API definition.
-
Connection.
enqoptions
()¶ Returns an object specifying the options to use when enqueuing messages. See Enqueue Options for more information.
New in version 5.3.
Note
This method is an extension to the DB API definition.
-
Connection.
external_name
¶ This read-write attribute specifies the external name that is used by the connection when logging distributed transactions.
New in version 5.3.
Note
This attribute is an extension to the DB API definition.
-
Connection.
gettype
(name)¶ Return a type object given its name. This can then be used to create objects which can be bound to cursors created by this connection.
New in version 5.3.
Note
This method is an extension to the DB API definition.
-
Connection.
handle
¶ This read-only attribute returns the OCI service context handle for the connection. It is primarily provided to facilitate testing the creation of a connection using the OCI service context handle.
Note
This attribute is an extension to the DB API definition.
-
Connection.
inputtypehandler
¶ This read-write attribute specifies a method called for each value that is bound to a statement executed on any cursor associated with this connection. The method signature is handler(cursor, value, arraysize) and the return value is expected to be a variable object or None in which case a default variable object will be created. If this attribute is None, the default behavior will take place for all values bound to statements.
Note
This attribute is an extension to the DB API definition.
-
Connection.
internal_name
¶ This read-write attribute specifies the internal name that is used by the connection when logging distributed transactions.
New in version 5.3.
Note
This attribute is an extension to the DB API definition.
-
Connection.
ltxid
¶ This read-only attribute returns the logical transaction id for the connection. It is used within Oracle Transaction Guard as a means of ensuring that transactions are not duplicated. See the Oracle documentation and the provided sample for more information.
New in version 5.3.
-
Connection.
maxBytesPerCharacter
¶ This read-only attribute returns the maximum number of bytes each character can use for the client character set.
Note
This attribute is an extension to the DB API definition.
-
Connection.
module
¶ This write-only attribute sets the module column in the v$session table. The maximum length for this string is 48 and if you exceed this length you will get ORA-24960.
-
Connection.
msgproperties
()¶ Returns an object specifying the properties of messages used in advanced queuing. See Message Properties for more information.
New in version 5.3.
Note
This method is an extension to the DB API definition.
-
Connection.
nencoding
¶ This read-only attribute returns the IANA character set name of the national character set in use by the Oracle client.
Note
This attribute is an extension to the DB API definition.
-
Connection.
outputtypehandler
¶ This read-write attribute specifies a method called for each column that is going to be fetched from any cursor associated with this connection. The method signature is handler(cursor, name, defaultType, length, precision, scale) and the return value is expected to be a variable object or None in which case a default variable object will be created. If this attribute is None, the default behavior will take place for all columns fetched from cursors.
Note
This attribute is an extension to the DB API definition.
-
Connection.
ping
()¶ Ping the server which can be used to test if the connection is still active.
Note
This method is an extension to the DB API definition.
-
Connection.
prepare
()¶ Prepare the distributed (global) transaction for commit. Return a boolean indicating if a transaction was actually prepared in order to avoid the error ORA-24756 (transaction does not exist).
Note
This method is an extension to the DB API definition.
-
Connection.
rollback
()¶ Rollback any pending transactions.
-
Connection.
shutdown
([mode])¶ Shutdown the database. In order to do this the connection must be connected as
SYSDBA
orSYSOPER
. Two calls must be made unless the mode specified isDBSHUTDOWN_ABORT
. An example is shown below:import cx_Oracle connection = cx_Oracle.Connection(mode = cx_Oracle.SYSDBA) connection.shutdown(mode = cx_Oracle.DBSHUTDOWN_IMMEDIATE) cursor = connection.cursor() cursor.execute("alter database close normal") cursor.execute("alter database dismount") connection.shutdown(mode = cx_Oracle.DBSHUTDOWN_FINAL)
Note
This method is an extension to the DB API definition.
-
Connection.
startup
(force=False, restrict=False)¶ Startup the database. This is equivalent to the SQL*Plus command “startup nomount”. The connection must be connected as
SYSDBA
orSYSOPER
with thePRELIM_AUTH
option specified for this to work. An example is shown below:import cx_Oracle connection = cx_Oracle.Connection( mode = cx_Oracle.SYSDBA | cx_Oracle.PRELIM_AUTH) connection.startup() connection = cx_Oracle.connect(mode = cx_Oracle.SYSDBA) cursor = connection.cursor() cursor.execute("alter database mount") cursor.execute("alter database open")
Note
This method is an extension to the DB API definition.
-
Connection.
stmtcachesize
¶ This read-write attribute specifies the size of the statement cache. This value can make a significant difference in performance (up to 100x) if you have a small number of statements that you execute repeatedly.
Note
This attribute is an extension to the DB API definition.
-
Connection.
subscribe
(namespace=cx_Oracle.SUBSCR_NAMESPACE_DBCHANGE, protocol=cx_Oracle.SUBSCR_PROTO_OCI, callback=None, timeout=0, operations=OPCODE_ALLOPS, port=0, qos=0)¶ Return a new subscription object using the connection. Currently the namespace and protocol arguments cannot have any other meaningful values.
The callback is expected to be a callable that accepts a single argument. A message object is passed to this callback whenever a notification is received.
The timeout value specifies that the subscription expires after the given time in seconds. The default value of 0 indicates that the subscription never expires.
The operations argument enables filtering of the messages that are sent (insert, update, delete). The default value will send notifications for all operations.
The port specifies the listening port for callback notifications from the database server. If not specified, an unused port will be selected by the database.
The qos argument specifies quality of service options. It should be one or more of the following flags, OR’ed together:
cx_Oracle.SUBSCR_QOS_RELIABLE
,cx_Oracle.SUBSCR_QOS_DEREG_NFY
,cx_Oracle.SUBSCR_QOS_ROWIDS
,cx_Oracle.SUBSCR_QOS_QUERY
,cx_Oracle.SUBSCR_QOS_BEST_EFFORT
.Note
This method is an extension to the DB API definition.
Note
Do not close the connection before the subscription object is deleted or the subscription object will not be deregistered in the database. This is done automatically if connection.close() is never called.
-
Connection.
tnsentry
¶ This read-only attribute returns the TNS entry of the database to which a connection has been established.
Note
This attribute is an extension to the DB API definition.
-
Connection.
username
¶ This read-only attribute returns the name of the user which established the connection to the database.
Note
This attribute is an extension to the DB API definition.
-
Connection.
version
¶ This read-only attribute returns the version of the database to which a connection has been established.
Note
This attribute is an extension to the DB API definition.