Struct Cursor

Source

pub struct Cursor { /* private fields */ }

Expand description

Executes queries on a connection and manages retrieval of the results. It can be obtained using the cursor() method on the connection.

The method execute() can be used to send SQL statements to the server. The server will return zero or more replies, usually one per statement. A reply may be an error, an acknowledgement such as “your UPDATE statement affected 1001 rows”, or a result set. This method will immediately abort with Err(CursorError::Server(_)) if any of the replies is an error message, not just the first reply.

Most retrieval methods on a cursor operate on the current reply. To move on to the next reply, call next_reply(). The only exception is next_row(), which will automatically try to skip to the next result set reply if the current reply is not a result set. This is useful because people often write things like

CREATE TABLE foo(..);
INSERT INTO foo SELECT .. FROM other_table;
INSERT INTO foo SELECT .. FROM yet_another_table;
SELECT COUNT(*) FROM foo;

and they expect to be able to directly retrieve the count, not get an error message “CREATE TABLE did not return a result set”. Note that next_row() will not automatically skip to the next result set if the current result set is exhausted.

To retrieve data from a result set, first call next_row(). This tries to move the cursor to the next row and returns a boolean indicating if a new row was found. if so, methods like get_str(colnr) and get_i32(colnr) can be used to retrieve individual fields from this row. Note that you must call next_row() before you call a getter. Before the first call to next_row(), the cursor is before the first row, not at the first row. This behaviour is convenient because it allows to write things like

cursor.execute("SELECT * FROM mytable")?;
while cursor.next_row()? {
    let value: Option<&str> = cursor.get_str(0)?;
    println!("{}", value.unwrap());
}

Implementations§

Source §

impl Cursor

Source

pub fn execute(&mut self, statements: &str) -> CursorResult<()>

Execute the given SQL statements and place the cursor at the first reply. The results of any earlier queries on this cursor are discarded.

Source

pub fn affected_rows(&self) -> Option<i64>

Retrieve the number of affected rows from the current reply. INSERT, UPDATE and SELECT statements provide the number of affected rows, but for example CREATE TABLE doesn’t. Returns a signed value because we’re not entirely sure whether the server ever sends negative values to indicate exceptional conditions.

TODO figure this out and deal with it.

Source

pub fn has_result_set(&self) -> bool

Return true if the current reply is a result set.

Source

pub fn next_reply(&mut self) -> CursorResult<bool>

Try to move the cursor to the next reply.

Source

pub fn close(self) -> CursorResult<()>

Destroy the cursor, discarding all results. This may need to communicate with the server to release resources there.

Source

pub fn column_metadata(&self) -> &[ResultColumn]

Return information about the columns of the current result set.

Source

pub fn next_row(&mut self) -> CursorResult<bool>

Advance the cursor to the next available row in the result set, returning a boolean that indicates whether such a row was present.

When the cursor enters a new result set after execute() or next_reply(), it is initially positioned before the first row, and the first call to this method will advance it to be at the first row. This means you always have to call this method before calling getters.

Source §

impl Cursor

These getters can be called to retrieve values from the current row, after next_row() has confirmed that that row exists. They return None if the value is NULL.

Source