1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
#####################################
Compliance to Python Database API 2.0
#####################################
.. currentmodule:: kinterbasdb
Incompatibilities
=================
.. data:: DATETIME
KInterbasDB's deferred loading of dynamic type translators causes
this singleton to behave in violation of the standard until the
:func:`kinterbasdb.init()` function has been called (whether explicitly or
implicitly). For more information, see the documnation section about
`Deferred Loading of Dynamic Type Translators`.
Unsupported Optional Features
=============================
.. method:: Cursor.nextset()
This method is not implemented because the database engine does not support
opening multiple result sets simultaneously with a single cursor.
Nominally Supported Optional Features
=====================================
.. class:: Cursor
.. attribute:: arraysize
As required by the spec, the value of this attribute is observed with
respect to the `fetchmany` method. However, changing the value of this
attribute does not make any difference in fetch efficiency because
the database engine only supports fetching a single row at a time.
.. method:: setinputsizes()
Although this method is present, it does nothing, as allowed by the spec.
.. method:: setoutputsize()
Although this method is present, it does nothing, as allowed by the spec.
Extensions and Caveats
======================
KInterbasDB offers a large feature set beyond the minimal requirements
of the Python DB API. Most of these extensions are documented in the
section of this document entitled `Native Database Engine Features and
Extensions Beyond the Python DB API`.
This section attempts to document only those features that overlap
with the DB API, or are too insignificant to warrant their own
subsection elsewhere.
.. function:: connect()
This function supports the following optional keyword arguments in addition
to those required by the spec:
:role: For connecting to a database with a specific SQL role.
*Example:*
.. sourcecode:: python
kinterbasdb.connect(dsn='host:/path/database.db', user='limited_user',
password='pass', role='MORE_POWERFUL_ROLE')
:charset: For explicitly specifying the character set of the connection.
See Firebird Documentation for a list of available character sets, and
`Unicode Fields and KInterbasDB` section for information on handling
extended character sets with KInterbasDB.
*Example:*
.. sourcecode:: python
kinterbasdb.connect(dsn='host:/path/database.db', user='sysdba',
password='pass', charset='UTF8')
:dialect: The SQL dialect is feature for backward compatibility with Interbase® 5.5
or earlier. The default dialect is `3` (the most featureful dialect, default
for Firebird). If you want to connect to `legacy` databases, you must
explicitly set this argument's value to `1`. Dialect `2` is a transitional
dialect that is normally used only during ports from IB < 6 to IB >= 6
or Firebird. See Firebird documentation for more information about
SQL Dialects.
*Example:*
.. sourcecode:: python
kinterbasdb.connect(dsn='host:/path/database.db', user='sysdba',
password='pass', dialect=1)
:timeout: (`Optional`) Dictionary with timeout and action specification. See section
about `Connection Timeouts <beyond-python-db-api.html#connection-timeout>`_ for details.
.. class:: Connection
.. attribute:: charset
*(read-only)* The character set of the connection (set via the `charset`
parameter of :func:`kinterbasdb.connect()`). See Firebird Documentation for a list
of available character sets, and `Unicode Fields and KInterbasDB` section
for information on handling extended character sets with KInterbasDB.
.. attribute:: dialect
This integer attribute indicates which SQL dialect the connection is using.
You should not change a connection's dialect; instead, discard the connection
and establish a new one with the desired dialect. For more information, see
the documentation of the `dialect` argument of the `connect` function.
.. attribute:: server_version
*(read-only)* The version string of the database server to which this connection
is connected. For example, a connection to Firebird 1.0 on Windows has the following
`server_version`: `WI-V6.2.794 Firebird 1.0`
.. method:: execute_immediate
Executes a statement without caching its prepared form. The statement must *not* be
of a type that returns a result set. In most cases (especially cases in which the same
statement -- perhaps a parameterized statement -- is executed repeatedly),
it is better to create a cursor using the connection's `cursor` method, then execute
the statement using one of the cursor's execute methods.
Arguments:
:sql: String containing the SQL statement to execute.
.. attribute:: precision_mode
Although this attribute is present in KInterbasDB 3.1+ and works in a backward-compatible
fashion, it is deprecated in favor of the more general dynamic type translation feature.
.. method:: commit(retaining=False)
.. method:: rollback(retaining=False)
The `commit` and `rollback` methods accept an optional boolean parameter `retaining`
(default `False`) that indicates whether the transactional context of the transaction
being resolved should be recycled. For details, see the Advanced
Transaction Control: Retaining Operations section of this document.
The `rollback` method accepts an optional string parameter `savepoint`
that causes the transaction to roll back only as far as the designated
savepoint, rather than rolling back entirely. For details, see the
Advanced Transaction Control: Savepoints section of this document.
.. class:: Cursor
.. attribute:: description
KInterbasDB makes absolutely no guarantees about `description` except those
required by the Python Database API Specification 2.0 (that is, `description`
is either `None` or a sequence of 7-element sequences). Therefore, client
programmers should *not* rely on `description` being an instance of a particular
class or type. KInterbasDB provides several named positional constants to be
used as indices into a given element of `description` . The contents
of all `description` elements are defined by the DB API spec; these
constants are provided merely for convenience.
.. sourcecode:: python
DESCRIPTION_NAME
DESCRIPTION_TYPE_CODE
DESCRIPTION_DISPLAY_SIZE
DESCRIPTION_INTERNAL_SIZE
DESCRIPTION_PRECISION
DESCRIPTION_SCALE
DESCRIPTION_NULL_OK
Here is an example of accessing the *name* of the first field in the
`description` of cursor `cur`:
.. sourcecode:: python
nameOfFirstField = cur.description[0][kinterbasdb.DESCRIPTION_NAME]
For more information, see the documentation of Cursor.description in
the `DB API Specification <Python-DB-API-2.0.html>`__.
.. attribute:: rowcount
Although KInterbasDB's `Cursor`s implement this
attribute, the database engine's own support for the determination of
"rows affected"/"rows selected" is quirky. The database engine only
supports the determination of rowcount for `INSERT`, `UPDATE`,
`DELETE`, and `SELECT` statements. When stored procedures become
involved, row count figures are usually not available to the client.
Determining rowcount for `SELECT` statements is problematic: the
rowcount is reported as zero until at least one row has been fetched
from the result set, and the rowcount is misreported if the result set
is larger than 1302 rows. The server apparently marshals result sets
internally in batches of 1302, and will misreport the rowcount for
result sets larger than 1302 rows until the 1303rd row is fetched,
result sets larger than 2604 rows until the 2605th row is fetched, and
so on, in increments of 1302. As required by the Python DB API Spec,
the rowcount attribute "is -1 in case no executeXX() has been
performed on the cursor or the rowcount of the last operation is not
determinable by the interface".
.. method:: fetchone()
.. method:: fetchmany()
.. method:: fetchall()
KInterbasDB makes absolutely no guarantees about
the return value of the `fetchone` / `fetchmany` / `fetchall` methods
except that it is a sequence indexed by field position. KInterbasDB
makes absolutely no guarantees about the return value of the
`fetchonemap` / `fetchmanymap` / `fetchallmap` methods (documented
below) except that it is a mapping of field name to field value.
Therefore, client programmers should *not* rely on the return value
being an instance of a particular class or type.
.. method:: fetchonemap()
This method is just like the standard
`fetchone` method of the DB API, except that it returns a mapping of
field name to field value, rather than a sequence.
.. method:: fetchmanymap()
This method is just like the standard
`fetchmany` method of the DB API, except that it returns a sequence of
mappings of field name to field value, rather than a sequence of
sequences.
.. method:: fetchallmap()
This method is just like the standard
`fetchall` method of the DB API, except that it returns a sequence of
mappings of field name to field value, rather than a sequence of
sequences.
.. method:: iter()
.. method:: itermap()
These methods are equivalent to the
`fetchall` and `fetchallmap` methods, respectively, except that they
return iterators rather than materialized sequences. `iter` and
`itermap` are exercised in this example.
|
