Struct odbc_api::parameter::BlobRead

pub struct BlobRead<R> { /* private fields */ }

Wraps an std::io::BufRead and implements self::Blob. Use this to stream contents from an std::io::BufRead to the database. The blob implementation is going to directly utilize the Buffer of the std::io::BufRead implementation, so the batch size is likely equal to that capacity.

Implementations

impl<R> BlobRead<R>

pub fn with_upper_bound(buf_read: R, upper_bound: usize) -> Self

Construct a blob read from any std::io::BufRead. The upper bound is used in the type description then binding the blob as a parameter.

Examples

This is more flexible than Self::from_path. Note however that files provide metadata about the length of the data, which io::BufRead does not. This is not an issue for most drivers, but some can perform optimization if they know the size in advance. In the tests SQLite has shown a bug to only insert empty data if no size hint has been provided.

use std::io::BufRead;
use odbc_api::{Connection, parameter::{Blob, BlobRead}, IntoParameter, Error};

fn insert_image_to_db(
    conn: &Connection<'_>,
    id: &str,
    image_data: impl BufRead) -> Result<(), Error>
{
    const MAX_IMAGE_SIZE: usize = 4 * 1024 * 1024;
    let mut blob = BlobRead::with_upper_bound(image_data, MAX_IMAGE_SIZE);

    let sql = "INSERT INTO Images (id, image_data) VALUES (?, ?)";
    let parameters = (&id.into_parameter(), &mut blob.as_blob_param());
    conn.execute(sql, parameters)?;
    Ok(())
}

pub unsafe fn with_exact_size(buf_read: R, exact_size: usize) -> Self

Construct a blob read from any std::io::BufRead. The upper bound is used in the type description then binding the blob as a parameter and is also passed to indicate the size of the actual value to the ODBC driver.

Safety

The ODBC driver may use the exact size hint to allocate buffers internally. Too short may lead to invalid writes and too long may lead to invalid reads, so to be save the hint must be exact.

impl BlobRead<BufReader<File>>

pub fn from_path(path: &Path) -> Result<Self>

Construct a blob from a Path. The metadata of the file is used to give the ODBC driver a size hint.

Example

BlobRead::from_path is the most convinient way to turn a file path into a Blob parameter. The following example also demonstrates that the streamed blob parameter can be combined with reqular input parmeters like id.

use std::{error::Error, path::Path};
use odbc_api::{Connection, parameter::{Blob, BlobRead}, IntoParameter};

fn insert_image_to_db(
    conn: &Connection<'_>,
    id: &str,
    image_path: &Path) -> Result<(), Box<dyn Error>>
{
    let mut blob = BlobRead::from_path(&image_path)?;

    let sql = "INSERT INTO Images (id, image_data) VALUES (?, ?)";
    let parameters = (&id.into_parameter(), &mut blob.as_blob_param());
    conn.execute(sql, parameters)?;
    Ok(())
}

Trait Implementations

impl<R> Blob for BlobRead<R> where
    R: BufRead, 

fn c_data_type(&self) -> CDataType

CData type of the binary data returned in the batches. Likely to be either crate::sys::CDataType::Binary, crate::sys::CDataType::Char or crate::sys::CDataType::WChar.

fn size_hint(&self) -> Option<usize>

Hint passed on to the driver regarding the combined size of all the batches. This hint is passed then the parameter is bound to the statement, so its meaning is only defined before the first call to next_batch. If None no hint about the total length of the batches is passed to the driver and the indicator will be set to crate::sys::DATA_AT_EXEC.

fn next_batch(&mut self) -> Result<Option<&[u8]>>

Retrieve the netxt batch of data from the source. Batches may not be empty. None indicates the last batch has been reached.

fn as_blob_param(&mut self) -> BlobParam<'_> where
    Self: Sized, 

Convinience function. Same as calling self::BlobParam::new.

impl<R> HasDataType for BlobRead<R> where
    R: BufRead, 

fn data_type(&self) -> DataType

The SQL data as which the parameter is bound to ODBC.