Struct mysql_async::QueryResult

pub struct QueryResult<'a, 't: 'a, P> { /* private fields */ }

Result of a query or statement execution.

Represents an asynchronous query result, that may not be fully consumed.

Note

Unconsumed query results are dropped implicitly when corresponding connection is dropped or queried. Also note, that in this case all remaining errors will be emitted to the caller:

use mysql_async::*;
use mysql_async::prelude::*;
let mut conn = Conn::new(get_opts()).await?;

// second result set will contain an error,
// but the first result set is ok, so this line will pass
conn.query_iter("DO 1; BLABLA;").await?;
// `QueryResult` was dropped withot being consumed

// driver must cleanup any unconsumed result to perform another query on `conn`,
// so this operation will be performed implicitly, but the unconsumed result
// contains an error claiming about 'BLABLA', so this error will be emitted here:
assert!(conn.query_iter("DO 1").await.unwrap_err().to_string().contains("BLABLA"));

Implementations

impl<'a, 't: 'a, P> QueryResult<'a, 't, P>

where P: Protocol + Unpin,

pub fn stream<'r, T: Unpin + FromRow + Send + 'static>( &'r mut self, ) -> BoxFuture<'r, Result<Option<ResultSetStream<'r, 'a, 't, T, P>>>>

Returns a Stream for the current result set.

The returned stream satisfies futures_util::TryStream, so you can use futures_util::TryStreamExt functions on it.

Behavior

Conversion

This stream will convert each row into T using FromRow implementation. If the row type is unknown please use the Row type for T to make this conversion infallible.

Consumption

The call to QueryResult::stream entails the consumption of the current result set, practically this means that the second call to QueryResult::stream will return the next result set stream even if the stream returned from the first call wasn’t explicitly consumed:

let mut conn = Conn::new(get_opts()).await?;

// This query result will contain two result sets.
let mut result = conn.query_iter("SELECT 1; SELECT 2;").await?;

// The first result set stream is dropped here without being consumed,
let _ = result.stream::<u8>().await?;
// so it will be implicitly consumed here.
let mut stream = result.stream::<u8>().await?.expect("the second result set must be here");
assert_eq!(2_u8, stream.next().await.unwrap()?);

Errors

Note, that QueryResult::stream may error if:

• current result set contains an error,
• previously unconsumed result set stream contained an error.

let mut conn = Conn::new(get_opts()).await?;

// The second result set of this query will contain an error.
let mut result = conn.query_iter("SELECT 1; SELECT FOO(); SELECT 2;").await?;

// First result set stream is dropped here without being consumed,
let _ = result.stream::<Row>().await?;
// so it will be implicitly consumed on the second call to `QueryResult::stream`
// that will error complaining about unknown FOO
assert!(result.stream::<Row>().await.unwrap_err().to_string().contains("FOO"));

pub fn stream_and_drop<T: Unpin + FromRow + Send + 'static>( self, ) -> BoxFuture<'a, Result<Option<ResultSetStream<'a, 'a, 't, T, P>>>>

Owned version of the QueryResult::stream.

Returned stream will stop iteration on the first result set boundary.

See also Query::stream, Queryable::query_stream, Queryable::exec_stream.

The following example uses the Query::stream function that is based on the QueryResult::stream_and_drop:

let pool = Pool::new(get_opts());
let mut conn = pool.get_conn().await?;

// This example uses the `Query::stream` function that is based on `QueryResult::stream_and_drop`:
let mut stream = "SELECT 1 UNION ALL SELECT 2".stream::<u8, _>(&mut conn).await?;
let rows = stream.try_collect::<Vec<_>>().await.unwrap();
assert_eq!(vec![1, 2], rows);

// Only the first result set will go into the stream:
let mut stream = r"
    SELECT 'foo' UNION ALL SELECT 'bar';
    SELECT 'baz' UNION ALL SELECT 'quux';".stream::<String, _>(&mut conn).await?;
let rows = stream.try_collect::<Vec<_>>().await.unwrap();
assert_eq!(vec!["foo".to_owned(), "bar".to_owned()], rows);

// We can also build a `'static` stream by giving away the connection:
let stream = "SELECT 2 UNION ALL SELECT 3".stream::<u8, _>(conn).await?;
// `tokio::spawn` requires `'static`
let handle = tokio::spawn(async move {
    stream.try_collect::<Vec<_>>().await.unwrap()
});
assert_eq!(vec![2, 3], handle.await?);

impl<'a, 't: 'a, P> QueryResult<'a, 't, P>

where P: Protocol,

pub fn new<T: Into<Connection<'a, 't>>>(conn: T) -> Self

pub fn is_empty(&self) -> bool

true if there are no more rows nor result sets in this query.

This function will return false if the last result set was taken by the QueryResult::stream that was dropped before being fully consumed (i.e. caller will get false even if QueryResult data is reachable only for library internals).

pub fn last_insert_id(&self) -> Option<u64>

Last insert id, if any.

pub fn affected_rows(&self) -> u64

Number of affected rows as reported by the server, or 0.

pub fn info(&self) -> Cow<'_, str>

Text information as reported by the server, or an empty string.

pub fn warnings(&self) -> u16

Number of warnings as reported by the server, or 0.

pub async fn collect<R>(&mut self) -> Result<Vec<R>>

where R: FromRow + Send + 'static,

Collects the current result set of this query result.

It is parametrized by R and internally calls R::from_row(Row) on each row.

It will collect rows up to a neares result set boundary. This means that you should call collect as many times as result sets in your query result. For example query SELECT 'foo'; SELECT 'foo', 'bar'; will produce QueryResult with two result sets in it. One can use QueryResult::is_empty to make sure that there is no more result sets.

Panic

It’ll panic if any row isn’t convertible to R (i.e. programmer error or unknown schema).

• In case of programmer error see FromRow docs;
• In case of unknown schema use QueryResult::try_collect.

pub async fn try_collect<R>( &mut self, ) -> Result<Vec<StdResult<R, FromRowError>>>

where R: FromRow + Send + 'static,

Collects the current result set of this query result.

It works the same way as QueryResult::collect but won’t panic if row isn’t convertible to R.

pub async fn collect_and_drop<R>(self) -> Result<Vec<R>>

where R: FromRow + Send + 'static,

Collects the current result set of this query result and drops everything else.

Panic

It’ll panic if any row isn’t convertible to R (i.e. programmer error or unknown schema).

• In case of programmer error see FromRow docs;
• In case of unknown schema use QueryResult::try_collect.

pub async fn try_collect_and_drop<R>( self, ) -> Result<Vec<StdResult<R, FromRowError>>>

where R: FromRow + Send + 'static,

Collects the current result set of this query result and drops everything else.

It works the same way as QueryResult::collect_and_drop but won’t panic if row isn’t convertible to R.

pub async fn for_each<F>(&mut self, fun: F) -> Result<()>

where F: FnMut(Row),

Executes fun on every row of the current result set.

It will stop on the nearest result set boundary (see QueryResult::collect docs).

pub async fn for_each_and_drop<F>(self, fun: F) -> Result<()>

where F: FnMut(Row),

Executes fun on every row of the current result set and drops everything else.

pub async fn map<F, U>(&mut self, fun: F) -> Result<Vec<U>>

where F: FnMut(Row) -> U,

Maps every row of the current result set to U using fun.

It will stop on the nearest result set boundary (see QueryResult::collect docs).

pub async fn map_and_drop<F, U>(self, fun: F) -> Result<Vec<U>>

where F: FnMut(Row) -> U,

Map every row of the current result set to U using fun and drops everything else.

pub async fn reduce<T, F, U>(&mut self, init: U, fun: F) -> Result<U>

where F: FnMut(U, T) -> U, T: FromRow + Send + 'static,

Reduces rows of the current result set to U using fun.

It will stop on the nearest result set boundary (see QueryResult::collect docs).

pub async fn reduce_and_drop<T, F, U>(self, init: U, fun: F) -> Result<U>

where F: FnMut(U, T) -> U, T: FromRow + Send + 'static,

Reduces rows of the current result set to U using fun and drops everything else.

pub async fn drop_result(self) -> Result<()>

Drops this query result.

pub fn columns_ref(&self) -> &[Column]

Returns a reference to a columns list of this query result.

Empty list means that this result set was never meant to contain rows.

pub fn columns(&self) -> Option<Arc<[Column]>>

Returns a copy of a columns list of this query result.

Trait Implementations

impl<'a, 't: 'a, P> Debug for QueryResult<'a, 't, P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.