connection.rst @b1ea2624-b8ae-45ea-8f7f-f02dd21e77cd/upstream — view markup · raw · history · blame
Connection Object
Note
Any outstanding changes will be rolled back when the connection object is destroyed or closed.
System Message: INFO/1 (<string>, line 14)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 14)
Unknown directive type "method".
.. method:: Connection.__enter__()
The entry point for the connection as a context manager. It returns itself.
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 23)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 23)
Unknown directive type "method".
.. method:: Connection.__exit__()
The exit point for the connection as a context manager. This will close
the connection and roll back any uncommitted transaction.
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 33)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 33)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 44)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 44)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 55)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 55)
Unknown directive type "method".
.. method:: 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
:attr:`~Connection.internal_name` and :attr:`~Connection.external_name`
attributes must be set.
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 71)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 71)
Unknown directive type "attribute".
.. attribute:: Connection.callTimeout
This read-write attribute specifies the amount of time (in milliseconds)
that a single round-trip to the database may take before a timeout will
occur. A value of 0 means that no timeout will take place.
.. versionadded:: 7.0
.. note::
This attribute is an extension to the DB API definition and is only
available in Oracle Client 18c and higher.
System Message: INFO/1 (<string>, line 85)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 85)
Unknown directive type "method".
.. method:: Connection.cancel()
Break a long-running transaction.
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 94)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 94)
Unknown directive type "method".
.. method:: Connection.changepassword(oldpassword, newpassword)
Change the password of the logon.
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 103)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 103)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 113)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 113)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 123)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 123)
Unknown directive type "method".
.. method:: 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.
All open cursors and LOBs created by the connection will be closed and will
also no longer be usable.
Internally, references to the connection are held by cursor objects,
LOB objects, subscription objects, etc. Once all of these references are
released, the connection itself will be closed automatically. Either
control references to these related objects carefully or explicitly close
connections in order to ensure sufficient resources are available.
System Message: INFO/1 (<string>, line 139)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 139)
Unknown directive type "method".
.. method:: Connection.commit()
Commit any pending transactions to the database.
System Message: INFO/1 (<string>, line 144)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 144)
Unknown directive type "method".
.. method:: Connection.createlob(lobType)
Create and return a new temporary :ref:`LOB object <lobobj>` of the
specified type. The lobType parameter should be one of
:data:`cx_Oracle.CLOB`, :data:`cx_Oracle.BLOB` or :data:`cx_Oracle.NCLOB`.
.. versionadded:: 6.2
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 157)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 157)
Unknown directive type "attribute".
.. attribute:: Connection.current_schema
This read-write attribute sets the current schema attribute for the
session. Setting this value is the same as executing the SQL statement
"ALTER SESSION SET CURRENT_SCHEMA". The attribute is set (and verified) on
the next call that does a round trip to the server. The value is placed
before unqualified database objects in SQL statements you then execute.
.. note::
This attribute is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 170)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 170)
Unknown directive type "method".
.. method:: Connection.cursor()
Return a new :ref:`cursor object <cursorobj>` using the connection.
System Message: INFO/1 (<string>, line 175)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 175)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 186)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 186)
Unknown directive type "method".
.. method:: Connection.deq(name, options, msgproperties, payload)
Returns a message id after successfully dequeuing a message. The options
object can be created using :meth:`~Connection.deqoptions()` and the
msgproperties object can be created using
:meth:`~Connection.msgproperties()`. The payload must be an object created
using :meth:`ObjectType.newobject()`.
.. versionadded:: 5.3
.. deprecated:: 7.2
Use the methods :meth:`Queue.deqOne()` or :meth:`Queue.deqMany()`
instead.
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 206)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 206)
Unknown directive type "method".
.. method:: Connection.deqoptions()
Returns an object specifying the options to use when dequeuing messages.
See :ref:`deqoptions` for more information.
.. versionadded:: 5.3
.. deprecated:: 7.2
Use the attribute :attr:`Queue.deqOptions` instead.
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 222)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 222)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 232)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 232)
Unknown directive type "attribute".
.. attribute:: 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).
.. versionadded:: 5.3
.. note::
This attribute is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 245)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 245)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 255)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 255)
Unknown directive type "method".
.. method:: Connection.enq(name, options, msgproperties, payload)
Returns a message id after successfully enqueuing a message. The options
object can be created using :meth:`~Connection.enqoptions()` and the
msgproperties object can be created using
:meth:`~Connection.msgproperties()`. The payload must be an object created
using :meth:`ObjectType.newobject()`.
.. versionadded:: 5.3
.. deprecated:: 7.2
Use the methods :meth:`Queue.enqOne()` or :meth:`Queue.enqMany()`
instead.
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 275)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 275)
Unknown directive type "method".
.. method:: Connection.enqoptions()
Returns an object specifying the options to use when enqueuing messages.
See :ref:`enqoptions` for more information.
.. versionadded:: 5.3
.. deprecated:: 7.2
Use the attribute :attr:`Queue.enqOptions` instead.
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 291)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 291)
Unknown directive type "attribute".
.. attribute:: Connection.external_name
This read-write attribute specifies the external name that is used by the
connection when logging distributed transactions.
.. versionadded:: 5.3
.. note::
This attribute is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 303)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 303)
Unknown directive type "method".
.. method:: Connection.getSodaDatabase()
Return a :ref:`SodaDatabase <sodadb>` object for Simple Oracle Document
Access (SODA). All SODA operations are performed either on the returned
SodaDatabase object or from objects created by the returned SodaDatabase
object. See `here <http://www.oracle.com/pls/topic/lookup?
ctx=dblatest&id=GUID-BE42F8D3-B86B-43B4-B2A3-5760A4DF79FB>`__ for
additional information on SODA.
.. versionadded:: 7.0
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 319)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 319)
Unknown directive type "method".
.. method:: Connection.gettype(name)
Return a :ref:`type object <objecttype>` given its name. This can then be
used to create objects which can be bound to cursors created by this
connection.
.. versionadded:: 5.3
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 332)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 332)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 343)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 343)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 357)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 357)
Unknown directive type "attribute".
.. attribute:: Connection.internal_name
This read-write attribute specifies the internal name that is used by the
connection when logging distributed transactions.
.. versionadded:: 5.3
.. note::
This attribute is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 369)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 369)
Unknown directive type "attribute".
.. attribute:: 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.
.. versionadded:: 5.3
.. note:
This attribute is an extension to the DB API definition. It is only
available when Oracle Database 12.1 or higher is in use on both the
server and the client.
System Message: INFO/1 (<string>, line 385)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 385)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 395)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 395)
Unknown directive type "attribute".
.. attribute:: 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.
.. note:
This attribute is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 406)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 406)
Unknown directive type "method".
.. method:: Connection.msgproperties(payload, correlation, delay, exceptionq, \
expiration, priority)
Returns an object specifying the properties of messages used in advanced
queuing. See :ref:`msgproperties` for more information.
Each of the parameters are optional. If specified, they act as a shortcut
for setting each of the equivalently named properties.
.. versionadded:: 5.3
.. versionchanged:: 7.2 Added parameters
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 424)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 424)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 434)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 434)
Unknown directive type "attribute".
.. attribute:: 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.
See :ref:`outputtypehandlers`.
.. note::
This attribute is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 451)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 451)
Unknown directive type "method".
.. method:: 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.
System Message: INFO/1 (<string>, line 461)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 461)
Unknown directive type "method".
.. method:: 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.
System Message: INFO/1 (<string>, line 472)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 472)
Unknown directive type "method".
.. method:: Connection.queue(name, payloadType=None)
Creates a :ref:`queue <queue>` which is used to enqueue and dequeue
messages in Advanced Queueing.
The name parameter is expected to be a string identifying the queue in
which messages are to be enqueued or dequeued.
The payloadType parameter, if specified, is expected to be an
:ref:`object type <objecttype>` that identifies the type of payload the
queue expects. If not specified, RAW data is enqueued and dequeued.
.. versionadded:: 7.2
.. note::
This method is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 491)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 491)
Unknown directive type "method".
.. method:: Connection.rollback()
Rollback any pending transactions.
System Message: INFO/1 (<string>, line 496)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 496)
Unknown directive type "method".
.. method:: Connection.shutdown([mode])
Shutdown the database. In order to do this the connection must be connected
as :data:`~cx_Oracle.SYSDBA` or :data:`~cx_Oracle.SYSOPER`. Two calls must
be made unless the mode specified is :data:`~cx_Oracle.DBSHUTDOWN_ABORT`.
An example is shown below:
::
import cx_Oracle
connection = cx_Oracle.connect(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.
System Message: INFO/1 (<string>, line 519)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 519)
Unknown directive type "method".
.. method:: Connection.startup(force=False, restrict=False, pfile=None)
Startup the database. This is equivalent to the SQL\*Plus command "startup
nomount". The connection must be connected as :data:`~cx_Oracle.SYSDBA` or
:data:`~cx_Oracle.SYSOPER` with the :data:`~cx_Oracle.PRELIM_AUTH` option
specified for this to work.
The pfile parameter, if specified, is expected to be a string identifying
the location of the parameter file (PFILE) which will be used instead of
the stored parameter file (SPFILE).
An example is shown below:
::
import cx_Oracle
connection = cx_Oracle.connect(
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.
System Message: INFO/1 (<string>, line 549)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 549)
Unknown directive type "attribute".
.. attribute:: 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.
The default value is 20.
See :ref:`Statement Caching <stmtcache>` for more information.
.. note::
This attribute is an extension to the DB API definition.
System Message: INFO/1 (<string>, line 564)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 564)
Unknown directive type "method".
.. method:: 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, ipAddress=None, groupingClass=0, groupingValue=0, groupingType=cx_Oracle.SUBSCR_GROUPING_TYPE_SUMMARY, name=None, clientInitiated=False)
Return a new :ref:`subscription object <subscrobj>` that receives
notifications for events that take place in the database that match the
given parameters.
The namespace parameter specifies the namespace the subscription uses. It
can be one of :data:`cx_Oracle.SUBSCR_NAMESPACE_DBCHANGE` or
:data:`cx_Oracle.SUBSCR_NAMESPACE_AQ`.
The protocol parameter specifies the protocol to use when notifications are
sent. Currently the only valid value is :data:`cx_Oracle.SUBSCR_PROTO_OCI`.
The callback is expected to be a callable that accepts a single parameter.
A :ref:`message object <msgobjects>` 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 parameter enables filtering of the messages that are sent
(insert, update, delete). The default value will send notifications for all
operations. This parameter is only used when the namespace is set to
:data:`cx_Oracle.SUBSCR_NAMESPACE_DBCHANGE`.
The port parameter specifies the listening port for callback notifications
from the database server. If not specified, an unused port will be selected
by the Oracle Client libraries.
The qos parameter specifies quality of service options. It should be one or
more of the following flags, OR'ed together:
:data:`cx_Oracle.SUBSCR_QOS_RELIABLE`,
:data:`cx_Oracle.SUBSCR_QOS_DEREG_NFY`,
:data:`cx_Oracle.SUBSCR_QOS_ROWIDS`,
:data:`cx_Oracle.SUBSCR_QOS_QUERY`,
:data:`cx_Oracle.SUBSCR_QOS_BEST_EFFORT`.
The ipAddress parameter specifies the IP address (IPv4 or IPv6) in standard
string notation to bind for callback notifications from the database
server. If not specified, the client IP address will be determined by the
Oracle Client libraries.
The groupingClass parameter specifies what type of grouping of
notifications should take place. Currently, if set, this value can only be
set to the value :data:`cx_Oracle.SUBSCR_GROUPING_CLASS_TIME`, which
will group notifications by the number of seconds specified in the
groupingValue parameter. The groupingType parameter should be one of the
values :data:`cx_Oracle.SUBSCR_GROUPING_TYPE_SUMMARY` (the default) or
:data:`cx_Oracle.SUBSCR_GROUPING_TYPE_LAST`.
The name parameter is used to identify the subscription and is specific to
the selected namespace. If the namespace parameter is
:data:`cx_Oracle.SUBSCR_NAMESPACE_DBCHANGE` then the name is optional and
can be any value. If the namespace parameter is
:data:`cx_Oracle.SUBSCR_NAMESPACE_AQ`, however, the name must be in the
format '<QUEUE_NAME>' for single consumer queues and
'<QUEUE_NAME>:<CONSUMER_NAME>' for multiple consumer queues, and identifies
the queue that will be monitored for messages. The queue name may include
the schema, if needed.
The clientInitiated parameter is used to determine if client initiated
connections or server initiated connections (the default) will be
established. Client initiated connections are only available in Oracle
Client 19.4 and Oracle Database 19.4 and higher.
.. versionadded:: 6.4
The parameters ipAddress, groupingClass, groupingValue, groupingType
and name were added.
.. versionadded:: 7.3
The parameter clientInitiated was added.
.. note::
This method is an extension to the DB API definition.
.. note::
The subscription can be deregistered in the database by calling the
function :meth:`~Connection.unsubscribe()`. If this method is not
called and the connection that was used to create the subscription is
explicitly closed using the function :meth:`~Connection.close()`, the
subscription will not be deregistered in the database.
System Message: INFO/1 (<string>, line 652)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 652)
Unknown directive type "attribute".
.. attribute:: Connection.tag
This read-write attribute initially contains the actual tag of the session
that was acquired from a pool by :meth:`SessionPool.acquire()`. If the
connection was not acquired from a pool or no tagging parameters were
specified (tag and matchanytag) when the connection was acquired from the
pool, this value will be None. If the value is changed, it must be a string
containing name=value pairs like "k1=v1;k2=v2".
If this value is not None when the connection is released back to the pool
it will be used to retag the session. This value can be overridden in the
call to :meth:`SessionPool.release()`.
.. note::
This attribute is an extension to the DB API definition.
.. versionadded:: 7.1
System Message: INFO/1 (<string>, line 672)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 672)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 682)
No directive entry for "method" in module "docutils.parsers.rst.languages.en". Trying "method" as canonical directive name.System Message: ERROR/3 (<string>, line 682)
Unknown directive type "method".
.. method:: Connection.unsubscribe(subscr)
Unsubscribe from events in the database that were originally subscribed to
using :meth:`~Connection.subscribe()`. The connection used to unsubscribe
should be the same one used to create the subscription, or should access
the same database and be connected as the same user name.
.. versionadded:: 6.4
System Message: INFO/1 (<string>, line 692)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 692)
Unknown directive type "attribute".
.. attribute:: 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.
System Message: INFO/1 (<string>, line 702)
No directive entry for "attribute" in module "docutils.parsers.rst.languages.en". Trying "attribute" as canonical directive name.System Message: ERROR/3 (<string>, line 702)
Unknown directive type "attribute".
.. attribute:: 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.
.. note::
If you connect to Oracle Database 18 or higher with client libraries
12.2 or lower that you will only receive the base version (such as
18.0.0.0.0) instead of the full version (18.3.0.0.0).
Docutils System Messages
System Message: INFO/1 (<string>, line 1)
Hyperlink target "connobj" is not referenced.