951 lines
26 KiB
ReStructuredText
951 lines
26 KiB
ReStructuredText
.. module:: cx_Oracle
|
|
|
|
.. _module:
|
|
|
|
****************
|
|
Module Interface
|
|
****************
|
|
|
|
.. function:: Binary(string)
|
|
|
|
Construct an object holding a binary (long) string value.
|
|
|
|
|
|
.. function:: clientversion()
|
|
|
|
Return the version of the client library being used as a 5-tuple. The five
|
|
values are the major version, minor version, update number, patch number and
|
|
port update number.
|
|
|
|
.. note::
|
|
|
|
This method is an extension to the DB API definition and is only
|
|
available in Oracle 10g Release 2 and higher.
|
|
|
|
|
|
.. function:: Connection([user, password, dsn, mode, handle, pool, threaded, twophase, events, cclass, purity, newpassword])
|
|
connect([user, password, dsn, mode, handle, pool, threaded, twophase, events, cclass, purity, newpassword])
|
|
|
|
Constructor for creating a connection to the database. Return a Connection
|
|
object (:ref:`connobj`). All arguments are optional and can be specified as
|
|
keyword parameters.
|
|
|
|
The dsn (data source name) is the TNS entry (from the Oracle names server or
|
|
tnsnames.ora file) or is a string like the one returned from makedsn(). If
|
|
only one parameter is passed, a connect string is assumed which is to be of
|
|
the format ``user/password@dsn``, the same format accepted by Oracle
|
|
applications such as SQL\*Plus.
|
|
|
|
If the mode is specified, it must be one of :data:`SYSDBA`, :data:`SYSASM` or
|
|
:data:`SYSOPER` which are defined at the module level; otherwise it defaults
|
|
to the normal mode of connecting.
|
|
|
|
If the handle is specified, it must be of type OCISvcCtx\* and is only of
|
|
use when embedding Python in an application (like PowerBuilder) which has
|
|
already made the connection.
|
|
|
|
The pool argument is expected to be a session pool object (:ref:`sesspool`)
|
|
and the use of this argument is the equivalent of calling pool.acquire().
|
|
|
|
The threaded argument is expected to be a boolean expression which
|
|
indicates whether or not Oracle should use the mode OCI_THREADED to wrap
|
|
accesses to connections with a mutex. Doing so in single threaded
|
|
applications imposes a performance penalty of about 10-15% which is why the
|
|
default is False.
|
|
|
|
The twophase argument is expected to be a boolean expression which
|
|
indicates whether or not the attributes should be set on the connection
|
|
object to allow for two phase commit. The default for this value is also
|
|
False because of bugs in Oracle prior to Oracle 10g.
|
|
|
|
The events argument is expected to be a boolean expression which indicates
|
|
whether or not to initialize Oracle in events mode (only available in Oracle
|
|
11g and higher).
|
|
|
|
The cclass argument is expected to be a string and defines the connection
|
|
class for database resident connection pooling (DRCP) in Oracle 11g and
|
|
higher.
|
|
|
|
The purity argument is expected to be one of :data:`ATTR_PURITY_NEW` (the
|
|
session must be new without any prior session state),
|
|
:data:`ATTR_PURITY_SELF` (the session may have been used before) or
|
|
:data:`ATTR_PURITY_DEFAULT` (the default behavior which is defined by Oracle
|
|
in its documentation). This argument is only relevant in Oracle 11g and
|
|
higher.
|
|
|
|
The newpassword argument is expected to be a string if specified and sets
|
|
the password for the logon during the connection process.
|
|
|
|
|
|
.. function:: Cursor(connection)
|
|
|
|
Constructor for creating a cursor. Return a new Cursor object
|
|
(:ref:`cursorobj`) using the connection.
|
|
|
|
.. note::
|
|
|
|
This method is an extension to the DB API definition.
|
|
|
|
|
|
.. function:: Date(year, month, day)
|
|
|
|
Construct an object holding a date value.
|
|
|
|
|
|
.. function:: DateFromTicks(ticks)
|
|
|
|
Construct an object holding a date value from the given ticks value (number
|
|
of seconds since the epoch; see the documentation of the standard Python
|
|
time module for details).
|
|
|
|
|
|
.. function:: makedsn(host, port, sid, [service_name])
|
|
|
|
Return a string suitable for use as the dsn for the connect() method. This
|
|
string is identical to the strings that are defined by the Oracle names
|
|
server or defined in the tnsnames.ora file. If you wish to use the service
|
|
name instead of the sid, do not include a value for the parameter sid and
|
|
use the keyword parameter service_name instead.
|
|
|
|
.. note::
|
|
|
|
This method is an extension to the DB API definition.
|
|
|
|
|
|
.. function:: SessionPool(user, password, database, min, max, increment, [connectiontype, threaded, getmode=cx_Oracle.SPOOL_ATTRVAL_NOWAIT, homogeneous=True, externalauth=True])
|
|
|
|
Create a session pool (see Oracle documentation for more information) and
|
|
return a session pool object (:ref:`sesspool`). This allows for very fast
|
|
connections to the database and is of primary use in a server where the same
|
|
connection is being made multiple times in rapid succession (a web server,
|
|
for example). If the connection type is specified, all calls to acquire()
|
|
will create connection objects of that type, rather than the base type
|
|
defined at the module level. The threaded attribute is expected to be a
|
|
boolean expression which indicates whether or not Oracle should use the mode
|
|
OCI_THREADED to wrap accesses to connections with a mutex. Doing so in
|
|
single threaded applications imposes a performance penalty of about 10-15%
|
|
which is why the default is False.
|
|
|
|
.. note::
|
|
|
|
This method is an extension to the DB API definition.
|
|
|
|
|
|
.. function:: Time(hour, minute, second)
|
|
|
|
Construct an object holding a time value.
|
|
|
|
|
|
.. function:: TimeFromTicks(ticks)
|
|
|
|
Construct an object holding a time value from the given ticks value (number
|
|
of seconds since the epoch; see the documentation of the standard Python
|
|
time module for details).
|
|
|
|
|
|
.. function:: Timestamp(year, month, day, hour, minute, second)
|
|
|
|
Construct an object holding a time stamp value.
|
|
|
|
|
|
.. function:: TimestampFromTicks(ticks)
|
|
|
|
Construct an object holding a time stamp value from the given ticks value
|
|
(number of seconds since the epoch; see the documentation of the standard
|
|
Python time module for details).
|
|
|
|
|
|
|
|
.. _constants:
|
|
|
|
Constants
|
|
=========
|
|
|
|
Global
|
|
------
|
|
|
|
.. data:: apilevel
|
|
|
|
String constant stating the supported DB API level. Currently '2.0'.
|
|
|
|
|
|
.. data:: buildtime
|
|
|
|
String constant stating the time when the binary was built.
|
|
|
|
.. note::
|
|
|
|
This constant is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: paramstyle
|
|
|
|
String constant stating the type of parameter marker formatting expected by
|
|
the interface. Currently 'named' as in 'where name = :name'.
|
|
|
|
|
|
.. data:: SYSDBA
|
|
|
|
Value to be passed to the connect() method which indicates that SYSDBA
|
|
access is to be acquired. See the Oracle documentation for more details.
|
|
|
|
.. note::
|
|
|
|
This constant is an extension to the DB API definition.
|
|
|
|
.. data:: SYSASM
|
|
|
|
Value to be passed to the connect() method which indicates that SYSASM
|
|
access is to be acquired. See the Oracle documentation for more details.
|
|
|
|
.. note::
|
|
|
|
This constant is an extension to the DB API definition.
|
|
|
|
.. data:: SYSOPER
|
|
|
|
Value to be passed to the connect() method which indicates that SYSOPER
|
|
access is to be acquired. See the Oracle documentation for more details.
|
|
|
|
.. note::
|
|
|
|
This constant is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: threadsafety
|
|
|
|
Integer constant stating the level of thread safety that the interface
|
|
supports. Currently 2, which means that threads may share the module and
|
|
connections, but not cursors. Sharing means that a thread may use a
|
|
resource without wrapping it using a mutex semaphore to implement resource
|
|
locking.
|
|
|
|
Note that in order to make use of multiple threads in a program which
|
|
intends to connect and disconnect in different threads, the threaded
|
|
argument to the Connection constructor must be a true value. See the
|
|
comments on the Connection constructor for more information (:ref:`module`).
|
|
|
|
|
|
.. data:: version
|
|
|
|
String constant stating the version of the module. Currently '|release|'.
|
|
|
|
.. note::
|
|
|
|
This attribute is an extension to the DB API definition.
|
|
|
|
|
|
Database Callbacks
|
|
------------------
|
|
|
|
.. note::
|
|
|
|
These constants are extensions to the DB API definition.
|
|
|
|
|
|
.. data:: FNCODE_BINDBYNAME
|
|
|
|
This constant is used to register callbacks on the OCIBindByName() function
|
|
of the OCI.
|
|
|
|
|
|
.. data:: FNCODE_BINDBYPOS
|
|
|
|
This constant is used to register callbacks on the OCIBindByPos() function
|
|
of the OCI.
|
|
|
|
|
|
.. data:: FNCODE_DEFINEBYPOS
|
|
|
|
This constant is used to register callbacks on the OCIDefineByPos() function
|
|
of the OCI.
|
|
|
|
|
|
.. data:: FNCODE_STMTEXECUTE
|
|
|
|
This constant is used to register callbacks on the OCIStmtExecute() function
|
|
of the OCI.
|
|
|
|
|
|
.. data:: FNCODE_STMTFETCH
|
|
|
|
This constant is used to register callbacks on the OCIStmtFetch() function
|
|
of the OCI.
|
|
|
|
|
|
.. data:: FNCODE_STMTPREPARE
|
|
|
|
This constant is used to register callbacks on the OCIStmtPrepare() function
|
|
of the OCI.
|
|
|
|
|
|
.. data:: UCBTYPE_ENTRY
|
|
|
|
This constant is used to register callbacks on entry to the function of the
|
|
OCI. In other words, the callback will be called prior to the execution of
|
|
the OCI function.
|
|
|
|
|
|
.. data:: UCBTYPE_EXIT
|
|
|
|
This constant is used to register callbacks on exit from the function of the
|
|
OCI. In other words, the callback will be called after the execution of the
|
|
OCI function.
|
|
|
|
|
|
.. data:: UCBTYPE_REPLACE
|
|
|
|
This constant is used to register callbacks that completely replace the call
|
|
to the OCI function.
|
|
|
|
|
|
Database Change Notification
|
|
----------------------------
|
|
|
|
.. note::
|
|
|
|
These constants are extensions to the DB API definition.
|
|
|
|
|
|
.. data:: EVENT_DEREG
|
|
|
|
This constant is a possible value for the type of a message and indicates
|
|
that the subscription object has been deregistered.
|
|
|
|
|
|
.. data:: EVENT_NONE
|
|
|
|
This constant is a possible value for the type of a message and provides no
|
|
additional information about the event.
|
|
|
|
|
|
.. data:: EVENT_OBJCHANGE
|
|
|
|
This constant is a possible value for the type of a message and indicates
|
|
that an object change of some sort has taken place.
|
|
|
|
|
|
.. data:: EVENT_QUERYCHANGE
|
|
|
|
This constant is a possible value for the type of a message and indicates
|
|
that the result set of a registered query has changed.
|
|
|
|
|
|
.. data:: EVENT_SHUTDOWN
|
|
|
|
This constant is a possible value for the type of a message and indicates
|
|
that the instance is in the process of being shut down.
|
|
|
|
|
|
.. data:: EVENT_SHUTDOWN_ANY
|
|
|
|
This constant is a possible value for the type of a message and indicates
|
|
that any instance (when running RAC) is in the process of being shut down.
|
|
|
|
|
|
.. data:: EVENT_STARTUP
|
|
|
|
This constant is a possible value for the type of a message and indicates
|
|
that the instance is in the process of being started up.
|
|
|
|
|
|
.. data:: OPCODE_ALLOPS
|
|
|
|
This constant is the default value when creating a subscription and
|
|
specifies that messages are to be sent for all operations.
|
|
|
|
|
|
.. data:: OPCODE_ALLROWS
|
|
|
|
This constant is a possible value for the operation attribute of one of the
|
|
table objects that are part of a message. It specifies that the table has
|
|
been completely invalidated.
|
|
|
|
|
|
.. data:: OPCODE_ALTER
|
|
|
|
This constant is a possible value for the operation attribute of one of the
|
|
table objects that are part of a message. It specifies that the table has
|
|
been altered in some fashion using DDL.
|
|
|
|
|
|
.. data:: OPCODE_DELETE
|
|
|
|
This constant can be used when creating a subscription and specifies that
|
|
messages are to be sent only when data is deleted. It is also a possible
|
|
value for the operation attribute of one of the table objects that are part
|
|
of a message.
|
|
|
|
|
|
.. data:: OPCODE_DROP
|
|
|
|
This constant is a possible value for the operation attribute of one of the
|
|
table objects that are part of a message. It specifies that the table has
|
|
been dropped.
|
|
|
|
|
|
.. data:: OPCODE_INSERT
|
|
|
|
This constant can be used when creating a subscription and specifies that
|
|
messages are to be sent only when data is inserted. It is also a possible
|
|
value for the operation attribute of one of the table objects that are part
|
|
of a message.
|
|
|
|
|
|
.. data:: OPCODE_UPDATE
|
|
|
|
This constant can be used when creating a subscription and specifies that
|
|
messages are to be sent only when data is updated. It is also a possible
|
|
value for the operation attribute of one of the table objects that are part
|
|
of a message.
|
|
|
|
|
|
.. data:: SUBSCR_CQ_QOS_QUERY
|
|
|
|
This constant can be used when creating a subscription and specifies that
|
|
notifications should only be sent if the result set of the registered query
|
|
changes. By default no false positive notifictions will be generated.
|
|
|
|
|
|
.. data:: SUBSCR_CQ_QOS_BEST_EFFORT
|
|
|
|
This constant can be used when creating a subscription and specifies that
|
|
best effort filtering for query result set changes is acceptable. False
|
|
positive notifications may be received. This behaviour may be suitable for
|
|
caching applications.
|
|
|
|
|
|
.. data:: SUBSCR_CQ_QOS_CLQRYCACHE
|
|
|
|
This constant is a future possible value for the cqqos argument when
|
|
creating a subscription. It specifies that client query caching be enabled.
|
|
|
|
|
|
.. data:: SUBSCR_NAMESPACE_DBCHANGE
|
|
|
|
This constant is the default (and currently only) value for the namespace
|
|
argument when creating a subscription.
|
|
|
|
|
|
.. data:: SUBSCR_PROTO_HTTP
|
|
|
|
This constant is a future possible value for the protocol argument when
|
|
creating a subscription. It specifies that notification will be sent to the
|
|
HTTP URL when a message is generated.
|
|
|
|
|
|
.. data:: SUBSCR_PROTO_MAIL
|
|
|
|
This constant is a future possible value for the protocol argument when
|
|
creating a subscription. It specifies that an e-mail message should be sent
|
|
to the target when a message is generated.
|
|
|
|
|
|
.. data:: SUBSCR_PROTO_OCI
|
|
|
|
This constant is the default (and currently only valid) value for the
|
|
protocol argument when creating a subscription.
|
|
|
|
|
|
.. data:: SUBSCR_PROTO_SERVER
|
|
|
|
This constant is a future possible value for the protocol argument when
|
|
creating a subscription. It specifies that the database procedure will be
|
|
invoked when a message is generated.
|
|
|
|
|
|
.. data:: SUBSCR_QOS_HAREG
|
|
|
|
This constant is a future possible value for the qos argument when
|
|
creating a subscription.
|
|
|
|
|
|
.. data:: SUBSCR_QOS_MULTICBK
|
|
|
|
This constant is a future possible value for the qos argument when
|
|
creating a subscription.
|
|
|
|
|
|
.. data:: SUBSCR_QOS_PAYLOAD
|
|
|
|
This constant is a future possible value for the qos argument when
|
|
creating a subscription. It specifies that a payload be delivered with the
|
|
message.
|
|
|
|
|
|
.. data:: SUBSCR_QOS_PURGE_ON_NTFN
|
|
|
|
This constant can be used when creating a subscription and specifies that
|
|
the subscription should be automatically unregistered after the first
|
|
notification.
|
|
|
|
|
|
.. data:: SUBSCR_QOS_RELIABLE
|
|
|
|
This constant is a future possible value for the qos argument when
|
|
creating a subscription. It specifies that notifications should not be lost
|
|
in the event of database failure.
|
|
|
|
|
|
.. data:: SUBSCR_QOS_REPLICATE
|
|
|
|
This constant is a future possible value for the qos argument when
|
|
creating a subscription.
|
|
|
|
|
|
.. data:: SUBSCR_QOS_SECURE
|
|
|
|
This constant is a future possible value for the qos argument when
|
|
creating a subscription.
|
|
|
|
|
|
Database Resident Connection Pooling
|
|
------------------------------------
|
|
|
|
.. note::
|
|
|
|
These constants are extensions to the DB API definition.
|
|
|
|
|
|
.. data:: ATTR_PURITY_DEFAULT
|
|
|
|
This constant is used when using database resident connection pooling (DRCP)
|
|
and specifies that the purity of the session is the default value used by
|
|
Oracle (see Oracle's documentation for more information).
|
|
|
|
|
|
.. data:: ATTR_PURITY_NEW
|
|
|
|
This constant is used when using database resident connection pooling (DRCP)
|
|
and specifies that the session acquired from the pool should be new and not
|
|
have any prior session state.
|
|
|
|
|
|
.. data:: ATTR_PURITY_SELF
|
|
|
|
This constant is used when using database resident connection pooling (DRCP)
|
|
and specifies that the session acquired from the pool need not be new and
|
|
may have prior session state.
|
|
|
|
|
|
Database Startup/Shutdown
|
|
-------------------------
|
|
|
|
.. note::
|
|
|
|
These constants are extensions to the DB API definition.
|
|
|
|
|
|
.. data:: PRELIM_AUTH
|
|
|
|
This constant is used to define the preliminary authentication mode required
|
|
for performing database startup and shutdown.
|
|
|
|
|
|
.. data:: DBSHUTDOWN_ABORT
|
|
|
|
This constant is used in database shutdown to indicate that the program
|
|
should not wait for current calls to complete or for users to disconnect
|
|
from the database. Use only in unusual circumstances since database recovery
|
|
may be necessary upon next startup.
|
|
|
|
|
|
.. data:: DBSHUTDOWN_FINAL
|
|
|
|
This constant is used in database shutdown to indicate that the instance can
|
|
be truly halted. This should only be done after the database has been shut
|
|
down in one of the other modes (except abort) and the database has been
|
|
closed and dismounted using the appropriate SQL commands. See the method
|
|
:meth:`~Connection.shutdown()` in the section on connections
|
|
(:ref:`connobj`).
|
|
|
|
|
|
.. data:: DBSHUTDOWN_IMMEDIATE
|
|
|
|
This constant is used in database shutdown to indicate that all uncommitted
|
|
transactions should be rolled back and any connected users should be
|
|
disconnected.
|
|
|
|
|
|
.. data:: DBSHUTDOWN_TRANSACTIONAL
|
|
|
|
This constant is used in database shutdown to indicate that further
|
|
connections should be prohibited and no new transactions should be allowed.
|
|
It then waits for active transactions to complete.
|
|
|
|
|
|
.. data:: DBSHUTDOWN_TRANSACTIONAL_LOCAL
|
|
|
|
This constant is used in database shutdown to indicate that further
|
|
connections should be prohibited and no new transactions should be allowed.
|
|
It then waits for only local active transactions to complete.
|
|
|
|
|
|
Session Pooling
|
|
---------------
|
|
|
|
.. note::
|
|
|
|
These constants are extensions to the DB API definition.
|
|
|
|
|
|
.. data:: SPOOL_ATTRVAL_FORCEGET
|
|
|
|
This constant is used to define the "get" mode on session pools and
|
|
indicates that a new connection will be returned if there are no free
|
|
sessions available in the pool.
|
|
|
|
|
|
.. data:: SPOOL_ATTRVAL_NOWAIT
|
|
|
|
This constant is used to define the "get" mode on session pools and
|
|
indicates that an exception is raised if there are no free sessions
|
|
available in the pool.
|
|
|
|
|
|
.. data:: SPOOL_ATTRVAL_WAIT
|
|
|
|
This constant is used to define the "get" mode on session pools and
|
|
indicates that the acquisition of a connection waits until a session is
|
|
freed if there are no free sessions available in the pool.
|
|
|
|
|
|
Types
|
|
=====
|
|
|
|
.. data:: BINARY
|
|
|
|
This type object is used to describe columns in a database that are binary
|
|
(in Oracle this is RAW columns).
|
|
|
|
|
|
.. data:: BFILE
|
|
|
|
This type object is used to describe columns in a database that are BFILEs.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: BLOB
|
|
|
|
This type object is used to describe columns in a database that are BLOBs.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: BOOLEAN
|
|
|
|
This type object is used to represent PL/SQL booleans.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition. It is only available
|
|
in Oracle 12.1 and higher and within PL/SQL. It cannot be used in
|
|
columns.
|
|
|
|
|
|
.. data:: CLOB
|
|
|
|
This type object is used to describe columns in a database that are CLOBs.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: CURSOR
|
|
|
|
This type object is used to describe columns in a database that are cursors
|
|
(in PL/SQL these are known as ref cursors).
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: DATETIME
|
|
|
|
This type object is used to describe columns in a database that are dates.
|
|
|
|
|
|
.. data:: FIXED_CHAR
|
|
|
|
This type object is used to describe columns in a database that are fixed
|
|
length strings (in Oracle this is CHAR columns); these behave differently in
|
|
Oracle than varchar2 so they are differentiated here even though the DB API
|
|
does not differentiate them.
|
|
|
|
.. note::
|
|
|
|
This attribute is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: FIXED_NCHAR
|
|
|
|
This type object is used to describe columns in a database that are NCHAR
|
|
columns in Oracle; these behave differently in Oracle than nvarchar2 so they
|
|
are differentiated here even though the DB API does not differentiate them.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: FIXED_UNICODE
|
|
|
|
.. note::
|
|
|
|
Deprecated. Please use FIXED_NCHAR instead.
|
|
|
|
|
|
.. data:: INTERVAL
|
|
|
|
This type object is used to describe columns in a database that are of type
|
|
interval day to second.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: LOB
|
|
|
|
This type object is the Python type of :data:`BLOB` and :data:`CLOB` data
|
|
that is returned from cursors.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: LONG_BINARY
|
|
|
|
This type object is used to describe columns in a database that are long
|
|
binary (in Oracle these are LONG RAW columns).
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: LONG_NCHAR
|
|
|
|
This type object is used to describe columns in a database that are long
|
|
NCHAR columns. There is no direct support for this in Oracle but long
|
|
NCHAR strings are bound this way in order to avoid the "unimplemented or
|
|
unreasonable conversion requested" error.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: LONG_STRING
|
|
|
|
This type object is used to describe columns in a database that are long
|
|
strings (in Oracle these are LONG columns).
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: LONG_UNICODE
|
|
|
|
.. note::
|
|
|
|
Deprecated. Please use LONG_NCHAR instead.
|
|
|
|
|
|
.. data:: NATIVE_FLOAT
|
|
|
|
This type object is used to describe columns in a database that are of type
|
|
binary_double or binary_float and is only available in Oracle 10g.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: NCHAR
|
|
|
|
This type object is used to describe national character strings (NVARCHAR2)
|
|
in Oracle.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: NCLOB
|
|
|
|
This type object is used to describe columns in a database that are NCLOBs.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: NUMBER
|
|
|
|
This type object is used to describe columns in a database that are numbers.
|
|
|
|
|
|
.. data:: OBJECT
|
|
|
|
This type object is used to describe columns in a database that are objects.
|
|
|
|
.. note::
|
|
|
|
This type is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: ROWID
|
|
|
|
This type object is used to describe the pseudo column "rowid".
|
|
|
|
|
|
.. data:: STRING
|
|
|
|
This type object is used to describe columns in a database that are strings
|
|
(in Oracle this is VARCHAR2 columns).
|
|
|
|
|
|
.. data:: TIMESTAMP
|
|
|
|
This type object is used to describe columns in a database that are
|
|
timestamps.
|
|
|
|
.. note::
|
|
|
|
This attribute is an extension to the DB API definition.
|
|
|
|
|
|
.. data:: UNICODE
|
|
|
|
.. note::
|
|
|
|
Deprecated. Please use NCHAR instead.
|
|
|
|
|
|
.. _exceptions:
|
|
|
|
Exceptions
|
|
==========
|
|
|
|
.. exception:: Warning
|
|
|
|
Exception raised for important warnings and defined by the DB API but not
|
|
actually used by cx_Oracle.
|
|
|
|
|
|
.. exception:: Error
|
|
|
|
Exception that is the base class of all other exceptions defined by
|
|
cx_Oracle and is a subclass of the Python StandardError exception (defined
|
|
in the module exceptions).
|
|
|
|
|
|
.. exception:: InterfaceError
|
|
|
|
Exception raised for errors that are related to the database interface
|
|
rather than the database itself. It is a subclass of Error.
|
|
|
|
|
|
.. exception:: DatabaseError
|
|
|
|
Exception raised for errors that are related to the database. It is a
|
|
subclass of Error.
|
|
|
|
|
|
.. exception:: DataError
|
|
|
|
Exception raised for errors that are due to problems with the processed
|
|
data. It is a subclass of DatabaseError.
|
|
|
|
|
|
.. exception:: OperationalError
|
|
|
|
Exception raised for errors that are related to the operation of the
|
|
database but are not necessarily under the control of the progammer. It is a
|
|
subclass of DatabaseError.
|
|
|
|
|
|
.. exception:: IntegrityError
|
|
|
|
Exception raised when the relational integrity of the database is affected.
|
|
It is a subclass of DatabaseError.
|
|
|
|
|
|
.. exception:: InternalError
|
|
|
|
Exception raised when the database encounters an internal error. It is a
|
|
subclass of DatabaseError.
|
|
|
|
|
|
.. exception:: ProgrammingError
|
|
|
|
Exception raised for programming errors. It is a subclass of DatabaseError.
|
|
|
|
|
|
.. exception:: NotSupportedError
|
|
|
|
Exception raised when a method or database API was used which is not
|
|
supported by the database. It is a subclass of DatabaseError.
|
|
|
|
|
|
Exception handling
|
|
==================
|
|
|
|
.. note::
|
|
|
|
PEP 249 (Python Database API Specification v2.0) says the following about
|
|
exception values:
|
|
|
|
[...] The values of these exceptions are not defined. They should
|
|
give the user a fairly good idea of what went wrong, though. [...]
|
|
|
|
With cx_Oracle every exception object has exactly one argument in the
|
|
``args`` tuple. This argument is a ``cx_Oracle._Error`` object which has
|
|
the following four read-only attributes.
|
|
|
|
.. attribute:: _Error.code
|
|
|
|
Integer attribute representing the Oracle error number (ORA-XXXXX).
|
|
|
|
.. attribute:: _Error.offset
|
|
|
|
Integer attribute representing the error offset when applicable.
|
|
|
|
.. attribute:: _Error.message
|
|
|
|
String attribute representing the Oracle message of the error. This
|
|
message is localized by the environment of the Oracle connection.
|
|
|
|
.. attribute:: _Error.context
|
|
|
|
String attribute representing the context in which the exception was
|
|
raised..
|
|
|
|
This allows you to use the exceptions for example in the following way:
|
|
|
|
::
|
|
|
|
import sys
|
|
import cx_Oracle
|
|
|
|
connection = cx_Oracle.Connection("user/pw@tns")
|
|
cursor = connection.cursor()
|
|
|
|
try:
|
|
cursor.execute("select 1 / 0 from dual")
|
|
except cx_Oracle.DatabaseError, exc:
|
|
error, = exc.args
|
|
print >> sys.stderr, "Oracle-Error-Code:", error.code
|
|
print >> sys.stderr, "Oracle-Error-Message:", error.message
|
|
|