Rust-oracle
This is an Oracle database driver for Rust based on ODPI-C.
Change Log
See ChangeLog.md.
Build-time Requirements
- C compiler. See
Compile-time Requirements
in this document.
Run-time Requirements
- Oracle client 11.2 or later. See ODPI-C installation document.
Usage
Put this in your Cargo.toml
:
[dependencies]
oracle = "0.5"
When you need to fetch or bind chrono
data types, enable chrono
feature:
[dependencies]
oracle = { version = "0.5", features = ["chrono"] }
Examples
Executes select statements and get rows:
use ;
// Connect to a database.
let conn = connect?;
let sql = "select ename, sal, comm from emp where deptno = :1";
// Select a table with a bind variable.
println!;
let rows = conn.query?;
for row_result in rows
// Another way to fetch rows.
// The rows iterator returns Result<(String, i32, Option<i32>)>.
println!;
let rows = conn.?;
for row_result in rows
Executes select statements and get the first rows:
use Connection;
// Connect to a database.
let conn = connect?;
let sql = "select ename, sal, comm from emp where empno = :1";
// Print the first row.
let row = conn.query_row?;
let ename: String = row.get?;
let sal: i32 = row.get?;
let comm: = row.get?;
println!;
println!;
// When no rows are found, conn.query_row() returns `Err(Error::NoDataFound)`.
// Get the first row as a tupple
let row = conn.?;
println!;
println!;
Executes non-select statements:
use Connection;
// Connect to a database.
let conn = connect?;
conn.execute?;
// Execute a statement with positional parameters.
conn.execute?;
// Execute a statement with named parameters.
conn.execute_named?;
// Commit the transaction.
conn.commit?;
// Delete rows
conn.execute?;
// Rollback the transaction.
conn.rollback?;
Prints column information:
use Connection;
// Connect to a database.
let conn = connect?;
let sql = "select ename, sal, comm from emp where 1 = 2";
let rows = conn.query?;
// Print column names
for info in rows.column_info
println!;
// Print column types
for info in rows.column_info
println!;
Prepared statement:
use Connection;
let conn = connect?;
// Create a prepared statement
let mut stmt = conn.prepare?;
// Insert one row
stmt.execute?;
// Insert another row
stmt.execute?;
This is more efficient than two conn.execute()
.
An SQL statement is executed in the DBMS as follows:
- step 1. Parse the SQL statement and create an execution plan.
- step 2. Execute the plan with bind parameters.
When a prepared statement is used, step 1 is called only once.
NLS_LANG parameter
NLS_LANG consists of three components: language, territory and charset. However the charset component is ignored and UTF-8(AL32UTF8) is used as charset because rust characters are UTF-8.
The territory component specifies numeric format, date format and so on. However it affects only conversion in Oracle. See the following example:
use Connection;
// The territory is France.
set_var;
let conn = connect?;
// 10.1 is converted to a string in Oracle and fetched as a string.
let result = conn.?;
assert_eq!; // The decimal mark depends on the territory.
// 10.1 is fetched as a number and converted to a string in rust-oracle
let result = conn.?;
assert_eq!; // The decimal mark is always period(.).
Note that NLS_LANG must be set before first rust-oracle function execution if required.
TODO
- Connection pooling using ODPI-C Pool Functions (Note: r2d2-oracle is available for connection pooling.)
- BFILEs (External LOBs) (Note: Reading contents of BFILEs as
Vec<u8>
is supported.) - Scrollable cursors
- Better Oracle object type support
- XML data type
- JSON data type
License
Rust-oracle and ODPI-C bundled in rust-oracle are under the terms of: