Struct oci_rs::statement::Statement

pub struct Statement<'conn> { /* fields omitted */ }

Represents a statement that is executed against a database.

A Statement cannot be created directly, instead it is brought to life through the .create_prepared_statement method of a Connection. It can only live as long as its parent Connection and when it goes out of scope the underlying resources will be released via a Drop implementation.

A Statement is stateful. Binding parameters and retrieving the result set will update the state of the object. The underlying OCI objects are stateful and re-use of an OCI statement for new binding parameters or diferent results is more efficient than allocating resources for a new statement. At the moment changing the SQL requires a new Statement but it might prove useful in future to allow this to be also changed without new allocation in the OCI library.

See the module level documentation for an overview plus examples.

Methods

impl<'conn> Statement<'conn>

fn bind(&mut self, params: &[&ToSqlValue]) -> Result<(), OciError>

Sets the parameters that will be used in a SQL statement with bind variables.

The parameters are anything that implement the ToSqlValue trait.

Errors

Any error in the underlying calls to the OCI library will be returned.

Examples

Here are various ways to bind paramters:

use oci_rs::connection::Connection;

let conn = Connection::new("localhost:1521/xe", "oci_rs", "test").unwrap();


// Insert some values using bind variables
let sql_insert = "INSERT INTO Dogs (DogId, Name)
                  VALUES (:id, :name)";

let mut insert = conn.create_prepared_statement(sql_insert).unwrap();

let id = 1;
let name = "Poodle";

insert.bind(&[&id, &name]).unwrap();
insert.execute().unwrap();

insert.bind(&[&2, &"Bulldog"]).unwrap();
insert.execute().unwrap();

insert.commit();

let sql_select = "SELECT Name FROM Dogs";

let mut select = conn.create_prepared_statement(sql_select).unwrap();
select.execute().unwrap();

let correct_results = vec!["Poodle".to_string(), "Bulldog".to_string()];
let results: Vec<String> = select.lazy_result_set()
                                 .map(|row_result| row_result.unwrap())
                                 .map(|row| row[0].value::<String>().unwrap())
                                 .collect();

assert_eq!(results, correct_results);

For large scale inserts to the database this is a bit inefficient as many calls to bind the parameters are needed. OCI does support batch processing and/or arrays of bind parameters, however this is not yet available through this crate.

fn execute(&mut self) -> Result<(), OciError>

Executes the SQL statement.

Errors

Any error in the underlying calls to the OCI library will be returned.

fn result_set(&mut self) -> Result<&Vec<Row>, OciError>

Returns the results of a SELECT statement.

After the execution of a SELECT statement a result set will be available from the database. This will contain none or many Rows of data depending on the query. There are two options for seeing the results, the first is to call this method to retrieve all the rows in one go, the second is to iterate through them row by row.

Should you go for the first option then the rows will be fetched from once this method is called. They will not be fetched eagerly as part of the .execute call, although this is not apparent to the caller. Once the results are retrieved from the database then they will be held until either the Statement goes out of scope or .execute is called again. This way, repeated calls to .result_set will be the same. If there are no data then an empty Vec<Row> will be returned.

The OCI library internally manages the number of rows that are pre-fetched from the database. This can be tweaked at the OCI level, but is not currently available in this crate. The OCI default is one row, so for each call to the database two rows are retrieved, thus half the number of round trips needed.

Errors

Any error in the underlying calls to the OCI library will be returned.

fn lazy_result_set(&mut self) -> RowIter

Returns the results of a SELECT statement row by row via the RowIter iterator.

The RowIter returned can then be used to run through the rows of data in the result set. This is a more attractive option if there are many rows or you want to process the results in a pipeline.

The same comments about pre-fetching configuration applies here as to .result_set.

Errors

This method will not report errors directly however subsequent use of RowIter will return any OCI errors encountered as each row is fetched.

Examples

use oci_rs::connection::Connection;

let conn = Connection::new("localhost:1521/xe", "oci_rs", "test").unwrap();


// Insert some values using bind variables
let sql_insert = "INSERT INTO Countries (CountryId, Name)
                  VALUES (:id, :name)";
let mut insert = conn.create_prepared_statement(sql_insert).unwrap();

let countries = vec!["Great Britain",
                     "Australia",
                     "Burma",
                     "Japan",
                     "Sudan",
                     "France",
                     "Germany",
                     "China"];

for (index, country) in countries.iter().enumerate(){
    let id = (index + 1) as i64;
    insert.bind(&[&id, country]).unwrap();
    insert.execute();
}
insert.commit();

let sql_select = "SELECT Name FROM Countries";
let mut select = conn.create_prepared_statement(sql_select).unwrap();
select.execute().unwrap();

let results: Vec<String> = select.lazy_result_set()
                                 .map(|row_result| row_result.unwrap())
                                 .map(|row| row[0].value::<String>().unwrap())
                                 .filter(|country| country.contains("c") ||
                                                   country.contains("C"))
                                 .map(|country| country.to_uppercase())
                                 .collect();
assert_eq!(results.len(), 2);
assert!(results.contains(&"CHINA".to_string()));
assert!(results.contains(&"FRANCE".to_string()));

fn commit(&self) -> Result<(), OciError>

Commits the changes to the database.

When a statement makes changes to the database Oracle implicitly starts a transaction. If all is well and the session is closed normally this will cause an implicit commit of the changes. If anything goes wrong and the sesssion is not closed or the connection is broken, Oracle will roll back the changes. This method, therefore allows you to commit changes when you want, rather than relying on a successfull disconnection.

Errors

Any error in the underlying calls to the OCI library will be returned.

Trait Implementations

impl<'conn> Debug for Statement<'conn>

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

Formats the value using the given formatter.

impl<'conn> Drop for Statement<'conn>

fn drop(&mut self)

Frees any internal handles allocated by the OCI library.

Panics

Panics if the resources can't be freed. This would be a failure of the underlying OCI function.