Struct StatementBuilder

pub struct StatementBuilder<'conn, 'sql> { /* private fields */ }

A builder to create a Statement with various configuration

Implementations

impl<'conn, 'sql> StatementBuilder<'conn, 'sql>

pub fn fetch_array_size( &mut self, size: u32, ) -> &mut StatementBuilder<'conn, 'sql>

Changes the array size used for performing fetches.

This specifies the number of rows allocated before performing fetches. The default value is 100. Higher value reduces the number of network round trips to fetch rows but requires more memory. The preferable value depends on the query and the environment.

If the query returns only onw row, it is better to change size to one.

let mut stmt = conn
    .statement("select StringCol from TestStrings where IntCol = :1")
    .fetch_array_size(1)
    .build()?;
assert_eq!(stmt.query_row_as::<String>(&[&1])?, "String 1");
assert_eq!(stmt.query_row_as::<String>(&[&2])?, "String 2");

pub fn prefetch_rows(&mut self, size: u32) -> &mut StatementBuilder<'conn, 'sql>

The number of rows that will be prefetched by the Oracle Client library when a query is executed. The default value is DPI_DEFAULT_PREFETCH_ROWS (2). Increasing this value may reduce the number of round-trips to the database that are required in order to fetch rows, but at the cost of increasing memory requirements. Setting this value to 0 will disable prefetch completely, which may be useful when the timing for fetching rows must be controlled by the caller.

pub fn lob_locator(&mut self) -> &mut StatementBuilder<'conn, 'sql>

Enables lob data types to be fetched or bound as Clob, Nclob or Blob.

Lob data types are internally bound as string or bytes by default. It is proper for small data but not for big data. That’s because when a lob contains 1 gigabyte data, the whole data are copied to the client and consume 1 gigabyte or more memory. When lob_locator is set and a column is fetched as Clob, data are copied using Read::read.

Examples

let mut stmt = conn
    .statement("select ClobCol from TestClobs where IntCol = :1")
    .lob_locator()
    .build()?;
let mut clob = stmt.query_row_as::<Clob>(&[&1i32])?;

// Copy contents of clob using 1MB buffer.
let mut buf = vec![0u8; 1 * 1024 * 1024];
loop {
  let size = clob.read(&mut buf)?;
  if size == 0 {
    break;
  }
  out.write(&buf[0..size]);
}

pub fn tag<T>(&mut self, tag_name: T) -> &mut StatementBuilder<'conn, 'sql>

where T: Into<String>,

Specifies the key to be used for searching for the statement in the statement cache. If the key is not found, the SQL text specified by Connection::statement is used to create a statement.

Examples

// When both SQL text and a tag are specifed and the tag is not found
// in the statement cache, the SQL text is used to make a statement.
// The statement is backed to the cache with the tag when
// it is closed.
let mut stmt = conn.statement("select 1 from dual").tag("query one").build()?;
assert_eq!(stmt.query_row_as::<i32>(&[])?, 1);
stmt.close()?;

// When only a tag is specified and the tag is found in the cache,
// the statement with the tag is returned.
let mut stmt = conn.statement("").tag("query one").build()?;
assert_eq!(stmt.query_row_as::<i32>(&[])?, 1);
stmt.close()?;

// When only a tag is specified and the tag isn't found in the cache,
// ORA-24431 is returned.
let err = conn.statement("").tag("not existing tag").build().unwrap_err();
match err {
  Error::OciError(err) if err.code() == 24431 => {
    // ORA-24431: Statement does not exist in the cache
  },
  _ => panic!("unexpected err {:?}", err),
}

// WARNING: The SQL statement is not checked when the tag is found.
let mut stmt = conn.statement("select 2 from dual").tag("query one").build()?;
// The result must be 2 if the SQL text is used. However it is 1
// because the statement tagged with "query one" is "select 1 from dual".
assert_eq!(stmt.query_row_as::<i32>(&[])?, 1);
stmt.close()?;

pub fn exclude_from_cache(&mut self) -> &mut StatementBuilder<'conn, 'sql>

Excludes the statement from the cache even when stmt_cache_size is not zero.

pub fn build(&self) -> Result<Statement>