Struct odbc_api::Prepared

source · [−]
pub struct Prepared<S> { /* private fields */ }
Expand description

A prepared query. Prepared queries are useful if the similar queries should executed more than once.

Implementations

Transfer ownership to the underlying statement handle.

The resulting type is one level of indirection away from the raw pointer of the ODBC API. It no longer has any guarantees about bound buffers, but is still guaranteed to be a valid allocated statement handle. This serves together with crate::handles::StatementImpl::into_sys or crate::handles::Statement::as_sys this serves as an escape hatch to access the functionality provided by crate::sys not yet accessible through safe abstractions.

Execute the prepared statement.

  • params: Used to bind these parameters before executing the statement. You can use () to represent no parameters. In regards to binding arrays of parameters: Should params specify a parameter set size of 0, nothing is executed, and Ok(None) is returned. See the crate::parameter module level documentation for more information on how to pass parameters.

Describes parameter marker associated with a prepared SQL statement.

Parameters
  • parameter_number: Parameter marker number ordered sequentially in increasing parameter order, starting at 1.

Unless you want to roll your own column buffer implementation users are encouraged to use Self::into_text_inserter instead.

Safety
  • Parameters must all be valid for insertion. An example for an invalid parameter would be a text buffer with a cell those indiactor value exceeds the maximum element length. This can happen after when truncation occurs then writing into a buffer.
source

pub fn into_text_inserter(
    self,
    capacity: usize,
    max_str_len: impl IntoIterator<Item = usize>
) -> Result<ColumnarBulkInserter<S, TextColumn<u8>>, Error>

Use this to insert rows of string input into the database.

use odbc_api::{Connection, Error};

fn insert_text<'e>(connection: Connection<'e>) -> Result<(), Error>{
    // Insert six rows of text with two columns each into the database in batches of 3. In a
    // real usecase you are likely to achieve a better results with a higher batch size.

    // Note the two `?` used as placeholders for the parameters.
    let prepared = connection.prepare("INSERT INTO NationalDrink (country, drink) VALUES (?, ?)")?;
    // We assume both parameter inputs never exceed 50 bytes.
    let mut prebound = prepared.into_text_inserter(3, [50, 50])?;
     
    // A cell is an option to byte. We could use `None` to represent NULL but we have no
    // need to do that in this example.
    let as_cell = |s: &'static str| { Some(s.as_bytes()) } ;

    // First batch of values
    prebound.append(["England", "Tea"].into_iter().map(as_cell))?;
    prebound.append(["Germany", "Beer"].into_iter().map(as_cell))?;
    prebound.append(["Russia", "Vodka"].into_iter().map(as_cell))?;

    // Execute statement using values bound in buffer.
    prebound.execute()?;
    // Clear buffer contents, otherwise the previous values would stay in the buffer.
    prebound.clear();

    // Second batch of values
    prebound.append(["India", "Tea"].into_iter().map(as_cell))?;
    prebound.append(["France", "Wine"].into_iter().map(as_cell))?;
    prebound.append(["USA", "Cola"].into_iter().map(as_cell))?;

    // Send second batch to the database
    prebound.execute()?;

    Ok(())
}

A crate::ColumnarBulkInserter which takes ownership of both the statement and the bound array parameter buffers.

use odbc_api::{Connection, Error, IntoParameter, buffers::{BufferDescription, BufferKind}};

fn insert_birth_years(
    conn: &Connection,
    names: &[&str],
    years: &[i16]
) -> Result<(), Error> {
    // All columns must have equal length.
    assert_eq!(names.len(), years.len());

    let prepared = conn.prepare("INSERT INTO Birthdays (name, year) VALUES (?, ?)")?;

    // Create a columnar buffer which fits the input parameters.
    let buffer_description = [
        BufferDescription {
            kind: BufferKind::Text { max_str_len: 255 },
            nullable: false,
        },
        BufferDescription {
            kind: BufferKind::I16,
            nullable: false,
        },
    ];
    // The capacity must be able to hold at least the largest batch. We do everything in one
    // go, so we set it to the length of the input parameters.
    let capacity = names.len();
    // Allocate memory for the array column parameters and bind it to the statement.
    let mut prebound = prepared.into_any_column_inserter(capacity, buffer_description)?;
    // Length of this batch
    prebound.set_num_rows(capacity);


    // Fill the buffer with values column by column
    let mut col = prebound
        .column_mut(0)
        .as_text_view()
        .expect("We know the name column to hold text.");

    for (index, name) in names.iter().enumerate() {
        col.set_cell(index, Some(name.as_bytes()));
    }

    let col = prebound
        .column_mut(1)
        .as_slice::<i16>()
        .expect("We know the year column to hold i16.");
    col.copy_from_slice(years);

    prebound.execute()?;
    Ok(())
}

A crate::ColumnarBulkInserter which has ownership of the bound array parameter buffers and borrows the statement. For most usecases Self::into_any_column_inserter is what you want to use, yet on some instances you may want to bind new paramater buffers to the same prepared statement. E.g. to grow the capacity dynamicaly during insertions with several chunks. In such usecases you may only want to borrow the prepared statemnt, so it can be reused with a different set of parameter buffers.

Trait Implementations

Get an exclusive reference to the underlying statement handle. This method is used to implement other more higher level methods on top of it. It is not intended to be called by users of this crate directly, yet it may serve as an escape hatch for low level usecases. Read more

Fetch a column description using the column index. Read more

Number of columns in result set. Can also be used to see wether execting a prepared Statement (crate::Prepared) would yield a result set, as this would return 0 if it does not. Read more

true if a given column in a result set is unsigned or not a numeric type, false otherwise. Read more

Returns the size in bytes of the columns. For variable sized types the maximum size is returned, excluding a terminating zero. Read more

Maximum number of characters required to display data from the column. Read more

Precision of the column. Read more

The applicable scale for a numeric data type. For DECIMAL and NUMERIC data types, this is the defined scale. It is undefined for all other data types. Read more

The column alias, if it applies. If the column alias does not apply, the column name is returned. If there is no column name or a column alias, an empty string is returned. Read more

Use this if you want to iterate over all column names and allocate a String for each one. Read more

Data type of the specified column. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.