Struct Prepared 

pub struct Prepared { /* private fields */ }

A prepared statement.

The statement is parsed here and bound at each execution, with the values in hand. That is the opposite of the usual arrangement, where a prepared statement is planned once and the values are pushed into the plan, and it is on purpose for now: an analytical query is planned against the data it reads, so a plan built without knowing that $1 is 1 or 1000000 is a plan built blind. Parsing is the part that is pure overhead, and that happens once.

What a parameter can be written as is DuckDB’s list: ? numbered by where it is, ?1 and $1 numbered by hand, and $name. A parameter used twice is one parameter, because it is one value to provide.

use rudb::Database;
use rudb_common::Value;

let db = Database::new();
db.execute("CREATE TABLE t (a INTEGER)")?;
db.execute("INSERT INTO t VALUES (1), (2), (3)")?;

let counted = db.prepare("SELECT count(*) FROM t WHERE a > ?")?;
assert_eq!(counted.value(&[Value::Integer(1)])?, Value::BigInt(2));
assert_eq!(counted.value(&[Value::Integer(2)])?, Value::BigInt(1));

Implementations

impl Prepared

pub fn sql(&self) -> &str

The statement as it was written.

pub fn parameters(&self) -> &[String]

The parameters the statement uses, once each, in the order they were written.

The identifier of a positional parameter is its number as a string, so a statement written with ? twice has parameters 1 and 2.

pub fn execute(&self, values: &[Value]) -> Result<QueryResult>

Runs the statement with values by position, numbered from one.

Errors

If a parameter was given no value, if a value was given for a parameter the statement does not use, or anything binding and running the statement reports.

pub fn execute_named(&self, values: &[(&str, Value)]) -> Result<QueryResult>

Runs the statement with values by name, which is what $name wants.

A name is matched without regard to case, which is what DuckDB does for this and for nothing else. Positional parameters can be given this way too, under the identifiers 1, 2 and so on, since a position is only a name that happens to be a number.

Errors

The same as Prepared::execute.

pub fn value(&self, values: &[Value]) -> Result<Value>

Runs the statement with values by position and returns the single value it produced.

Errors

Everything Prepared::execute can raise, plus an error if the result is not one row of one column.

Trait Implementations

impl Clone for Prepared

fn clone(&self) -> Prepared

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Prepared

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

Formats the value using the given formatter.