Struct odbc_api::ColumnarBulkInserter

pub struct ColumnarBulkInserter<'o, C> { /* private fields */ }

Can be used to execute a statement with bulk array paramters. Contrary to its name any statement with parameters can be executed, not only INSERT however inserting large amounts of data in batches is the primary intended usecase.

Binding new buffers is quite expensive in ODBC, so the parameter buffers are reused for each batch (so the pointers bound to the statment stay valid). So we copy each batch of data into the buffers already bound first rather than binding user defined buffer. Often the data might need to be transformed anyway, so the copy is no actual overhead. Once the buffers are filled with a batch, we send the data.

Implementations

impl<'o, C> ColumnarBulkInserter<'o, C>

pub unsafe fn new(
    statement: StatementImpl<'o>,
    parameters: Vec<C>
) -> Result<Self, Error> where
    C: ColumnBuffer + HasDataType, 

Users are not encouraged to call this directly.

Safety

• Statement is expected to be a perpared statement.
• 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.

pub fn execute(
    &mut self
) -> Result<Option<CursorImpl<&mut StatementImpl<'o>>>, Error>

Execute the prepared statement, with the parameters bound

pub fn clear(&mut self)

Sets the number of rows in the buffer to zero.

pub fn num_rows(&self) -> usize

Number of valid rows in the buffer

pub fn set_num_rows(&mut self, num_rows: usize)

Set number of valid rows in the buffer. Mustt not be larger than the batch size. If the specified number than the number of valid rows currently held by the buffer additional they will just hold the value previously assigned to them. Therfore if extending the number of valid rows users should take care to assign values to these rows. However, even if not assigend it is always guaranteed that every cell is valid for insertion and will not cause out of bounds access down in the ODBC driver. Therfore this method is safe.

impl<'o> ColumnarBulkInserter<'o, TextColumn<u8>>

pub fn append<'b>(
    &mut self,
    row: impl Iterator<Item = Option<&'b [u8]>>
) -> Result<(), Error>

Takes one element from the iterator for each internal column buffer and appends it to the end of the buffer. Should a cell of the row be too large for the associated column buffer, the column buffer will be reallocated with 1.2 times its size, and rebound to the statement.

This method panics if it is tried to insert elements beyond batch size. It will also panic if row does not contain at least one item for each internal column buffer.