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 and is only available in Oracle 10g. 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.

Note

This attribute is an extension to the DB API definition.

Connection.begin()
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 twophase argument to the Connection constructor must be a true value. See the comments on the Connection constructor for more information (Module Interface).

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 and is only available in Oracle 10g.

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 (Cursor Object) using the connection.

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 using msgproperties(). The payload must be an object created using newobject().

New in version development.

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 development.

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 development.

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.

Note

This attribute is an extension to the DB API definition and is only available in Python 2.x when not built in unicode mode.

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 using msgproperties(). The payload must be an object created using newobject().

New in version development.

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 development.

Note

This method is an extension to the DB API definition.

Connection.gettype(name)

Return a type object (Object Type Objects) given its name. This can then be used to create objects which can be bound to cursors created by this connection.

New in version development.

Note

This method 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.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 development.

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 and is only available in Oracle 10g. 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 development.

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 and is only available in Python 2.x when not built in unicode mode.

Connection.outputtypehandler

This read-write attribute specifies a method called for each value that is 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 values 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 and is only available in Oracle 10g R2 and higher.

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.register(code, when, function)

Register the function as an OCI callback. The code is one of the function codes defined in the Oracle documentation of which the most common ones are defined as constants in this module. The when parameter is one of UCBTYPE_ENTRY, UCBTYPE_EXIT or UCBTYPE_REPLACE. The function is a Python function which will accept the parameters that the OCI function accepts, modified as needed to return Python objects that are of some use. Note that this is a highly experimental method and can cause cx_Oracle to crash if not used properly. In particular, the OCI does not provide sizing information to the callback so attempts to access a variable beyond the allocated size will crash cx_Oracle. Use with caution.

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 connected as SYSDBA or SYSOPER. First shutdown using one of the DBSHUTDOWN constants defined in the constants (Constants) section. Next issue the SQL statements required to close the database (“alter database close normal”) and dismount the database (“alter database dismount”) followed by a second call to this method with the DBSHUTDOWN_FINAL mode.

Note

This method is an extension to the DB API definition and is only available in Oracle 10g R2 and higher.

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 or SYSOPER with the PRELIM_AUTH option specified for this to work. Once this method has completed, connect again without the PRELIM_AUTH option and issue the statements required to mount (“alter database mount”) and open (“alter database open”) the database.

Note

This method is an extension to the DB API definition and is only available in Oracle 10g R2 and higher.

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, rowids=False, port=0, qos=0, cqqos=0)

Return a new Subscription object (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 which is a message object. The timeout value specifies that the subscription expires after the given time in seconds. The default value of 0 indicates that the subscription does not expire. The operations argument enables filtering of the messages that are sent (insert, update, delete). The rowids flag specifies whether the rowids of affected rows should be included in the messages that are sent. The port specifies the listening port for callback notifications from the database server. The qos argument specifies quality of service options common to all subscriptions. Currently the only meaningful option is cx_Oracle.SUBSCR_QOS_PURGE_ON_NTFN which indicates that the subscription should be automatically unregistered after the first notification. The default value of 0 indicates that the subscription should persist after notification. The cqqos argument specifies quality of service options specific to continuous query notification. The default value of 0 indicates that change notification is required at database object granularity. The flag cx_Oracle.SUBSCR_CQ_QOS_QUERY specifies that change notification is required at query result set granularity, and the flag SUBSCR_CQ_QOS_BEST_EFFORT specifies that best effort filtering is accpetable, and false positive notifications may be received.

Note

This method is an extension to the DB API definition and is only available in Oracle 10g R2 and higher.

Note

Query result set change notification is only available in Oracle 11g and higher.

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.unregister(code, when)

Unregister the function as an OCI callback. The code is one of the function codes defined in the Oracle documentation of which the most common ones are defined as constants in this module. The when parameter is one of UCBTYPE_ENTRY, UCBTYPE_EXIT or UCBTYPE_REPLACE.

Note

This method 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.