Struct Query 

pub struct Query<'a> { /* private fields */ }

A query object with bind parameters.

Implementations

impl<'a> Query<'a>

pub const MAX_PARAMETERS: usize = 2100

The largest number of parameters SQL Server accepts in one statement.

A statement carrying more is rejected by the server with “The incoming request has too many parameters. The server supports a maximum of 2100 parameters.” — which arrives only after the whole batch has been sent.

This matters most for an IN list or a multi-row INSERT, where the count comes from the length of a collection rather than from the SQL text: the limit is reached by data volume, at run time, on a batch that may be larger than any that was tested. Split such a batch into chunks of at most MAX_PARAMETERS / parameters_per_row items.

Example

// A three-column INSERT: three parameters per row.
let rows_per_statement = Query::MAX_PARAMETERS / 3;
assert_eq!(rows_per_statement, 700);

pub fn new(sql: impl Into<Cow<'a, str>>) -> Self

Construct a new query object with the given SQL. If the SQL is parameterized, the given number of parameters must be bound to the object before executing.

The sql can define the parameter placement by annotating them with @PN, where N is the index of the parameter, starting from 1.

pub fn bind(&mut self, param: impl IntoSql<'a> + 'a)

Bind a new parameter to the query. Must be called exactly as many times as there are parameters in the given SQL. Otherwise the query will fail on execution.

pub fn bind_iter( &mut self, params: impl IntoIterator<Item = impl IntoSql<'a> + 'a>, )

Bind every item of an iterator, in order.

Equivalent to calling bind once per item. Pairs with placeholders to build an IN list, where the number of parameters is only known at runtime.

Example

let ids = vec![1i32, 2, 3];

let sql = format!(
    "SELECT name FROM users WHERE id IN ({})",
    Query::placeholders(1, ids.len()),
);

let mut query = Query::new(sql);
query.bind_iter(ids);

assert_eq!(query.param_count(), 3);

pub fn param_count(&self) -> usize

How many parameters have been bound so far.

Useful for checking against MAX_PARAMETERS before executing a statement whose parameter count is decided at runtime.

pub fn placeholders(first: usize, count: usize) -> String

Build a @P1, @P2, … placeholder list for count parameters, numbered from first.

SQL Server has no array parameter, so an IN list must name one placeholder per value, and IN (@P1) bound to a comma-separated string matches nothing rather than failing. Generating the list is the only way to write such a query, and this does it without a format loop at every call site.

first is 1-based, matching the @P1 numbering Query::new documents.

Example

assert_eq!(Query::placeholders(1, 3), "@P1, @P2, @P3");

// Continuing after parameters that are already bound.
assert_eq!(Query::placeholders(4, 2), "@P4, @P5");

A count of zero yields an empty string. IN () is a syntax error, so a caller with nothing to match on should skip the query rather than build one:

let ids: Vec<i32> = Vec::new();
assert!(Query::placeholders(1, ids.len()).is_empty());

pub async fn execute<S>(self, client: &mut Client<S>) -> Result<ExecuteResult>

where S: AsyncRead + AsyncWrite + Unpin + Send,

Executes SQL statements in the SQL Server, returning the number rows affected. Useful for INSERT, UPDATE and DELETE statements. See Client#execute for a simpler API if the parameters are statically known.

Example

let mut query = Query::new("INSERT INTO ##Test (id) VALUES (@P1), (@P2), (@P3)");

query.bind("foo");
query.bind(2i32);
query.bind(String::from("bar"));

let results = query.execute(&mut client).await?;

pub async fn query<'b, S>( self, client: &'b mut Client<S>, ) -> Result<QueryStream<'b>>

where S: AsyncRead + AsyncWrite + Unpin + Send,

Executes SQL statements in the SQL Server, returning resulting rows. Useful for SELECT statements. See Client#query for a simpler API if the parameters are statically known.

Example

let mut query = Query::new("SELECT @P1, @P2, @P3");

query.bind(1i32);
query.bind(2i32);
query.bind(3i32);

let stream = query.query(&mut client).await?;

Trait Implementations

impl<'a> Debug for Query<'a>

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

Formats the value using the given formatter.