Struct Query

pub struct Query<'q, DB, A>
where
    DB: Database,
{ /* private fields */ }

A single SQL query as a prepared statement. Returned by query().

Implementations

impl<'q, DB> Query<'q, DB, <DB as Database>::Arguments<'q>>

where DB: Database,

pub fn bind<T>(self, value: T) -> Query<'q, DB, <DB as Database>::Arguments<'q>>

where T: 'q + Encode<'q, DB> + Type<DB>,

Bind a value for use with this SQL query.

If the number of times this is called does not match the number of bind parameters that appear in the query (? for most SQL flavors, $1 .. $N for Postgres) then an error will be returned when this query is executed.

There is no validation that the value is of the type expected by the query. Most SQL flavors will perform type coercion (Postgres will return a database error).

If encoding the value fails, the error is stored and later surfaced when executing the query.

pub fn try_bind<T>( &mut self, value: T, ) -> Result<(), Box<dyn Error + Sync + Send>>

where T: 'q + Encode<'q, DB> + Type<DB>,

Like Query::try_bind but immediately returns an error if encoding the value failed.

impl<'q, DB, A> Query<'q, DB, A>

where DB: Database + HasStatementCache,

pub fn persistent(self, value: bool) -> Query<'q, DB, A>

If true, the statement will get prepared once and cached to the connection’s statement cache.

If queried once with the flag set to true, all subsequent queries matching the one with the flag will use the cached statement until the cache is cleared.

If false, the prepared statement will be closed after execution.

Default: true.

impl<'q, DB, A> Query<'q, DB, A>

where A: Send + 'q + IntoArguments<'q, DB>, DB: Database,

pub fn map<F, O>( self, f: F, ) -> Map<'q, DB, impl FnMut(<DB as Database>::Row) + Send, A>

where F: FnMut(<DB as Database>::Row) -> O + Send, O: Unpin,

Map each row in the result to another type.

See try_map for a fallible version of this method.

The query_as method will construct a mapped query using a FromRow implementation.

pub fn try_map<F, O>(self, f: F) -> Map<'q, DB, F, A>

where F: FnMut(<DB as Database>::Row) -> Result<O, Error> + Send, O: Unpin,

Map each row in the result to another type.

The query_as method will construct a mapped query using a FromRow implementation.

pub async fn execute<'e, 'c, E>( self, executor: E, ) -> Result<<DB as Database>::QueryResult, Error>

where 'c: 'e, 'q: 'e, A: 'e, E: Executor<'c, Database = DB>,

Execute the query and return the total number of rows affected.

pub async fn execute_many<'e, 'c, E>( self, executor: E, ) -> Pin<Box<dyn Stream<Item = Result<<DB as Database>::QueryResult, Error>> + Send + 'e>>

where 'c: 'e, 'q: 'e, A: 'e, E: Executor<'c, Database = DB>,

👎Deprecated: Only the SQLite driver supports multiple statements in one prepared statement and that behavior is deprecated. Use sqlx::raw_sql() instead. See https://github.com/launchbadge/sqlx/issues/3108 for discussion.

Execute multiple queries and return the rows affected from each query, in a stream.

pub fn fetch<'e, 'c, E>( self, executor: E, ) -> Pin<Box<dyn Stream<Item = Result<<DB as Database>::Row, Error>> + Send + 'e>>

where 'c: 'e, 'q: 'e, A: 'e, E: Executor<'c, Database = DB>,

Execute the query and return the generated results as a stream.

pub fn fetch_many<'e, 'c, E>( self, executor: E, ) -> Pin<Box<dyn Stream<Item = Result<Either<<DB as Database>::QueryResult, <DB as Database>::Row>, Error>> + Send + 'e>>

where 'c: 'e, 'q: 'e, A: 'e, E: Executor<'c, Database = DB>,

👎Deprecated: Only the SQLite driver supports multiple statements in one prepared statement and that behavior is deprecated. Use sqlx::raw_sql() instead. See https://github.com/launchbadge/sqlx/issues/3108 for discussion.

Execute multiple queries and return the generated results as a stream.

For each query in the stream, any generated rows are returned first, then the QueryResult with the number of rows affected.

pub async fn fetch_all<'e, 'c, E>( self, executor: E, ) -> Result<Vec<<DB as Database>::Row>, Error>

where 'c: 'e, 'q: 'e, A: 'e, E: Executor<'c, Database = DB>,

Execute the query and return all the resulting rows collected into a Vec.

Note: beware result set size.

This will attempt to collect the full result set of the query into memory.

To avoid exhausting available memory, ensure the result set has a known upper bound, e.g. using LIMIT.

pub async fn fetch_one<'e, 'c, E>( self, executor: E, ) -> Result<<DB as Database>::Row, Error>

where 'c: 'e, 'q: 'e, A: 'e, E: Executor<'c, Database = DB>,

Execute the query, returning the first row or Error::RowNotFound otherwise.

Note: for best performance, ensure the query returns at most one row.

Depending on the driver implementation, if your query can return more than one row, it may lead to wasted CPU time and bandwidth on the database server.

Even when the driver implementation takes this into account, ensuring the query returns at most one row can result in a more optimal query plan.

If your query has a WHERE clause filtering a unique column by a single value, you’re good.

Otherwise, you might want to add LIMIT 1 to your query.

pub async fn fetch_optional<'e, 'c, E>( self, executor: E, ) -> Result<Option<<DB as Database>::Row>, Error>

where 'c: 'e, 'q: 'e, A: 'e, E: Executor<'c, Database = DB>,

Execute the query, returning the first row or None otherwise.

Note: for best performance, ensure the query returns at most one row.

Depending on the driver implementation, if your query can return more than one row, it may lead to wasted CPU time and bandwidth on the database server.

Even when the driver implementation takes this into account, ensuring the query returns at most one row can result in a more optimal query plan.

If your query has a WHERE clause filtering a unique column by a single value, you’re good.

Otherwise, you might want to add LIMIT 1 to your query.

Trait Implementations

impl<'q, DB, A> Execute<'q, DB> for Query<'q, DB, A>

where DB: Database, A: Send + IntoArguments<'q, DB>,

fn sql(&self) -> &'q str

Gets the SQL that will be executed.

fn statement(&self) -> Option<&<DB as Database>::Statement<'q>>

Gets the previously cached statement, if available.

fn take_arguments( &mut self, ) -> Result<Option<<DB as Database>::Arguments<'q>>, Box<dyn Error + Sync + Send>>

Returns the arguments to be bound against the query string.

fn persistent(&self) -> bool

Returns true if the statement should be cached.