pgdbCursor – The cursor object¶
-
class
pgdb.
pgdbCursor
¶
These objects represent a database cursor, which is used to manage the context of a fetch operation. Cursors created from the same connection are not isolated, i.e., any changes done to the database by a cursor are immediately visible by the other cursors. Cursors created from different connections can or can not be isolated, depending on the level of transaction isolation. The default PostgreSQL transaction isolation level is “read committed”.
Cursor objects respond to the following methods and attributes.
Note that pgdbCursor
objects also implement both the iterator and the
context manager protocol, i.e. you can iterate over them and you can use them
in a with
statement.
description – details regarding the result columns¶
-
pgdbCursor.
description
¶ This read-only attribute is a sequence of 7-item tuples.
Each of these tuples contains information describing one result column:
- name
- type_code
- display_size
- internal_size
- precision
- scale
- null_ok
Note that display_size, precision, scale and null_ok are not implemented.
This attribute will be
None
for operations that do not return rows or if the cursor has not had an operation invoked via thepgdbCursor.execute()
orpgdbCursor.executemany()
method yet.
rowcount – number of rows of the result¶
-
pgdbCursor.
rowcount
¶ This read-only attribute specifies the number of rows that the last
pgdbCursor.execute()
orpgdbCursor.executemany()
call produced (for DQL statements like SELECT) or affected (for DML statements like UPDATE or INSERT). The attribute is -1 in case no such method call has been performed on the cursor or the rowcount of the last operation cannot be determined by the interface.
close – close the cursor¶
-
pgdbCursor.
close
()¶ Close the cursor now (rather than whenever it is deleted)
Return type: None
The cursor will be unusable from this point forward; an Error
(or subclass) exception will be raised if any operation is attempted
with the cursor.
execute – execute a database operation¶
-
pgdbCursor.
execute
(operation[, parameters])¶ Prepare and execute a database operation (query or command)
Parameters: - operation (str) – the database operation
- parameters – a sequence or mapping of parameters
Returns: the cursor, so you can chain commands
Parameters may be provided as sequence or mapping and will be bound to
variables in the operation. Variables are specified using Python extended
format codes, e.g. " ... WHERE name=%(name)s"
.
A reference to the operation will be retained by the cursor. If the same operation object is passed in again, then the cursor can optimize its behavior. This is most effective for algorithms where the same operation is used, but different parameters are bound to it (many times).
The parameters may also be specified as list of tuples to e.g. insert multiple
rows in a single operation, but this kind of usage is deprecated:
pgdbCursor.executemany()
should be used instead.
Note that in case this method raises a DatabaseError
, you can get
information about the error condition that has occurred by introspecting
its DatabaseError.sqlstate
attribute, which will be the SQLSTATE
error code associated with the error. Applications that need to know which
error condition has occurred should usually test the error code, rather than
looking at the textual error message.
executemany – execute many similar database operations¶
-
pgdbCursor.
executemany
(operation[, seq_of_parameters])¶ Prepare and execute many similar database operations (queries or commands)
Parameters: - operation (str) – the database operation
- seq_of_parameters – a sequence or mapping of parameter tuples or mappings
Returns: the cursor, so you can chain commands
Prepare a database operation (query or command) and then execute it against all parameter tuples or mappings found in the sequence seq_of_parameters.
Parameters are bounded to the query using Python extended format codes,
e.g. " ... WHERE name=%(name)s"
.
fetchone – fetch next row of the query result¶
-
pgdbCursor.
fetchone
()¶ Fetch the next row of a query result set
Returns: the next row of the query result set Return type: list or None
Fetch the next row of a query result set, returning a single list,
or None
when no more data is available.
An Error
(or subclass) exception is raised if the previous call to
pgdbCursor.execute()
or pgdbCursor.executemany()
did not produce
any result set or no call was issued yet.
fetchmany – fetch next set of rows of the query result¶
-
pgdbCursor.
fetchmany
([size=None][, keep=False])¶ Fetch the next set of rows of a query result
Parameters: - size (int or None) – the number of rows to be fetched
- keep – if set to true, will keep the passed arraysize
Tpye keep: bool
Returns: the next set of rows of the query result
Return type: list of lists
Fetch the next set of rows of a query result, returning a list of lists. An empty sequence is returned when no more rows are available.
The number of rows to fetch per call is specified by the size parameter.
If it is not given, the cursor’s arraysize
determines the number of
rows to be fetched. If you set the keep parameter to True, this is kept as
new arraysize
.
The method tries to fetch as many rows as indicated by the size parameter. If this is not possible due to the specified number of rows not being available, fewer rows may be returned.
An Error
(or subclass) exception is raised if the previous call to
pgdbCursor.execute()
or pgdbCursor.executemany()
did not produce
any result set or no call was issued yet.
Note there are performance considerations involved with the size parameter.
For optimal performance, it is usually best to use the arraysize
attribute. If the size parameter is used, then it is best for it to retain
the same value from one pgdbCursor.fetchmany()
call to the next.
fetchall – fetch all rows of the query result¶
-
pgdbCursor.
fetchall
()¶ Fetch all (remaining) rows of a query result
Returns: the set of all rows of the query result Return type: list of list
Fetch all (remaining) rows of a query result, returning them as list of lists.
Note that the cursor’s arraysize
attribute can affect the performance
of this operation.
row_factory – process a row of the query result¶
-
pgdbCursor.
row_factory
(row)¶ Process rows before they are returned
Parameters: row (list) – the currently processed row of the result set Returns: the transformed row that the fetch methods shall return
Note
This method is not part of the DB-API 2 standard.
You can overwrite this method with a custom row factory, e.g. if you want to return rows as dicts instead of lists:
class DictCursor(pgdb.pgdbCursor):
def row_factory(self, row):
return dict((d[0], v) for d, v in zip(self.description, row))
cur = DictCursor(con)
New in version 4.0.
arraysize - the number of rows to fetch at a time¶
-
pgdbCursor.
arraysize
¶ The number of rows to fetch at a time
This read/write attribute specifies the number of rows to fetch at a time with
pgdbCursor.fetchmany()
. It defaults to 1 meaning to fetch a single row
at a time.