oci_rs

oci_rs provides a Rust wrapper to the Oracle Call Interface (OCI) library. The Oracle site describes OCI as a "...comprehensive, high performance, native C language interface to Oracle Database for custom or packaged applications...".

Documentation is available here.

Setup

This crate is developed against version 12.2 of the OCI library. It is expected to work with 12.x.x but is not tested. The OCI client library needs to be installed on your machine and can be downloaded here.

If you are on Linux then you are likely to need to tell the linker where to find the files. Adding this to my .bashrc file worked for me, however the details may vary according to your distro. The below works on OpenSuse.

text export LIBRARY_PATH=$LIBRARY_PATH:/usr/lib/oracle/12.2/client64/lib/

This crate has been briefly tested against Windows but difficulties were faced. The OCI library is named differently and so updates will be needed in the bindings to make it compile. Once I can get chance to work out how to even build this using Visual Studio on Windows, this will be addressed.

Testing has been done against a local installation of Oracle 11g Express Edition. In order to run the crate tests then a local database needs to be available on localhost:1521/xe with a user oci_rs and password test.

Note that users of Debian based systems will face a lot of bother using Oracle databases locally. It does not install easily due to lack of official packages and the use of Alien will not help much. There are lots of complicated instructions available on the internet for how to get it to work, however the easiest is to run it in a Docker container. I have switched to Ubuntu and have had to resort to using Docker.

In order to use oci_rs add this to your Cargo.toml:

toml [dependencies] oci_rs = "0.6.0" and this to your crate root:

rust extern crate oci_rs;

Examples

In the following example we will create a connection to a database and then create a table, insert a couple of rows using bind variables and then execute a query to fetch them back again. There is a lot of error handling needed. Every OCI function call can fail and so Result and Option are used extensively. The below code takes the usual documentation shortcut of calling unwrap() a lot but doing so in real client code will prove ill-fated. Any remote database connection is inherently unreliable.

```rust use oci_rs::connection::Connection;

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

// Create a table let sqlcreate = "CREATE TABLE Toys (ToyId int, Name varchar(20), Price float)"; let mut create = conn.createpreparedstatement(sqlcreate).unwrap();

// Execute the create statement create.execute().unwrap();

// Commit in case we lose connection (an abnormal disconnection would result // in an automatic roll-back.) create.commit().unwrap();

// Insert some values using bind variables let sqlinsert = "INSERT INTO Toys (ToyId, Name, Price) VALUES (:id, :name, :price)"; let mut insert = conn.createpreparedstatement(sqlinsert).unwrap();

let values = [(1, "Barbie", 23.45), (2, "Dinosaurs", -5.21)];

// Run through the list of values, bind them and execute the statement for value in values.iter() { insert.bind(&[&value.0, &value.1, &value.2]).unwrap(); insert.execute().unwrap() }

insert.commit().unwrap();

// Create a query let sql_select = "SELECT * FROM Toys WHERE Name='Barbie'";

let mut select = conn.createpreparedstatement(sql_select).unwrap();

// Execute select.execute().unwrap();

// Get the result set let resultset = select.resultset().unwrap(); asserteq!(resultset.len(), 1); let firstrow = &resultset[0];

// Types are automatically converted let id: i64 = firstrow[0].value().unwrap(); let name: String = firstrow[1].value().unwrap(); let price: f64 = first_row[2].value().unwrap();

asserteq!(id, 1); asserteq!(name, "Barbie"); assert_eq!(price, 23.45);

```