Struct hdbconnect::PreparedStatement

pub struct PreparedStatement { /* fields omitted */ }

Allows injection-safe SQL execution and repeated calls of the same statement with different parameters with as few roundtrips as possible.

Providing Input Parameters

Type systems

It is helpful to understand the involved type systems - there are four!

• The database type system consists of the standard SQL types and proprietary types to represent values, like TINYINT, FLOAT, NVARCHAR, and many others. This type system is NOT directly visible to the client!
• The wire has its own type system - it's focus is on efficient data transfer. hdbconnect has to deal with these types appropriately. hdbconnect::TypeId enumerates a somewhat reduced superset of the server-side and the wire type system.
• The driver API represents values as variants of HdbValue; this type system hides the complexity of the wire type system and aims to be as close to the rust type system as possible
• The application is written in rust, and uses the rust type system.

From Rust to HdbValue

Prepared statements typically take one or more input parameter(s). As part of the statement preparation, the database server provides the client with detailed metadata for these parameters, which are kept by the PreparedStatement.

The parameter values can be handed over to the PreparedStatement either as Serializable rust types, or explicitly as HdbValue instances. If they are handed over as Serializable rust types, then the built-in serde_db-based conversion will convert them directly into those HdbValue variants that correspond to the TypeId that the server has requested. The application can also provide the values explicitly as HdbValue instances and by that enforce the usage of a different wire type and of server-side type conversions.

Sending HdbValues to the database

Sending an HdbValue::DECIMAL e.g. to the database can occur in different formats: with older HANA versions, a proprietary DECIMAL format is used that is independent of the number range of the concrete field. In newer HANA versions, three different formats are used (FIXED8, FIXED12 and FIXED16) that together allow for a wider value range and a lower bandwidth.

Similarly, a HdbValue::STRING is used to transfer values to all string-like wire types. But the wire protocol sometimes also allow sending data in another wire type than requested. If the database e.g. requests an INT, you can also send a String representation of the number, by using HdbValue::STRING("1088"), instead of the binary INT representation HdbValue::INT(1088).

Methods

impl PreparedStatement

pub fn execute<T: Serialize>(&mut self, input: &T) -> HdbResult<HdbResponse>

Converts the input into a row of parameters, if it is consistent with the metadata, and executes the statement immediately.

let mut statement = connection.prepare("select * from phrases where ID = ? and text = ?")?;
let hdbresponse = statement.execute(&(42, "Foo is bar"))?;

If the statement has no parameter, execute it like this:

let hdbresponse = stmt.execute(&())?;

pub fn execute_row(
    &mut self,
    hdb_values: Vec<HdbValue>
) -> HdbResult<HdbResponse>

Consumes the input as a row of parameters for immediate execution.

Useful mainly for generic code. In most cases execute() is more convenient.

pub fn add_batch<T: Serialize>(&mut self, input: &T) -> HdbResult<()>

Converts the input into a row of parameters and adds it to the batch, if it is consistent with the metadata.

pub fn add_row_to_batch(&mut self, hdb_values: Vec<HdbValue>) -> HdbResult<()>

Consumes the input as a row of parameters for the batch.

Useful mainly for generic code. In most cases add_batch() is more convenient.

pub fn execute_batch(&mut self) -> HdbResult<HdbResponse>

Executes the statement with the collected batch, and clears the batch.

Does nothing and returns with an error, if no batch exists.

pub fn parameter_descriptors(&self) -> Option<&[ParameterDescriptor]>

Descriptors of all parameters of the prepared statement (in, out, inout), if any.

Trait Implementations

impl Drop for PreparedStatement

fn drop(&mut self)

Frees all server-side ressources that belong to this prepared statement.

impl Debug for PreparedStatement

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

Formats the value using the given formatter.