The Cursor class in the Polypheny Python Driver is a fundamental interface for interacting with the database. It allows executing SQL commands, fetching data, and managing the context of a particular database operation. This class follows the Python Database API Specification v2.0 (PEP 249), providing a consistent and familiar interface for database operations.
Initialization
The Cursor object is typically not instantiated directly but obtained through the cursor() method of a Connection object.
Example:
cursor = connection.cursor()
Attributes
-
description: This read-only attribute provides information about each column in the last result set. It is a sequence of 7-item sequences, each containing column information, such as name, type, and size. It isNoneif no query has been executed or if the query does not return rows. -
rowcount: This read-only attribute specifies the number of rows that the last.execute*()produced (for DQL statements likeSELECT) or affected (for DML statements likeUPDATEorINSERT). The value is -1 if no.execute*()has been performed on the cursor or the row count cannot be determined. -
arraysize: This attribute specifies the number of rows to fetch at a time with.fetchmany(). It defaults to 1, meaning to fetch a single row at a time.
execute(query, params=None, *, fetch_size=None)
Executes a SQL statement.
query: A SQL query or command to execute.params: Optional sequence or mapping of parameters to bind to the query.fetch_size: Optional integer to determine the number of rows to fetch per network round trip.
Usage:
cursor.execute("SELECT * FROM my_table WHERE id = %s", (123,))
executemany(query, seq_of_params)
Prepares a database operation (query or command) and then executes it against all parameter sequences or mappings found in the sequence seq_of_params.
query: A SQL query or command to execute.seq_of_params: A sequence of sequences or mappings of parameters to bind to the query.
Usage:
cursor.executemany("INSERT INTO my_table (col1, col2) VALUES (%s, %s)", [(1, 'a'), (2, 'b'), (3, 'c')])
fetchone()
Fetches the next row of a query result set, returning a single sequence, or None when no more data is available.
Usage:
row = cursor.fetchone()
fetchmany(size=cursor.arraysize)
Fetches the next set of rows of a query result, returning a list of sequences. An empty list is returned when no more rows are available.
size: Optional integer specifying the number of rows to fetch.
Usage:
rows = cursor.fetchmany(10)
fetchall()
Fetches all remaining rows of a query result, returning them as a list of sequences. An empty list is returned when no more rows are available.
Usage:
all_rows = cursor.fetchall()
close()
Closes the cursor, freeing any associated resources. Once closed, the cursor is no longer usable.
Usage:
cursor.close()
setinputsizes(sizes)
This method is used to predefine memory areas for the parameters. It is part of the Python DB API specification. In the Polypheny Python Driver, this is a no-op method.
setoutputsize(size, column=None)
Sets a column buffer size for fetches of large columns (e.g., LONG, BLOB, etc.). The column is specified as an index into the result sequence. Not specifying the column will set the default size for all large columns in the cursor.
Error Handling
The Cursor class is designed to raise exceptions defined in the polypheny.exceptions module for error conditions, such as ProgrammingError for programming-related errors (e.g., syntax error in an SQL statement) and OperationalError for database operation errors (e.g., unexpected disconnection).
See Error Handling for more details.
Note
The Cursor class is central to database operations in the Polypheny Python Driver. Proper management of cursor objects, including closing them when they are no longer needed, is crucial for efficient resource management and avoiding potential memory leaks in long-running applications.
