Struct oracle::Connection

pub struct Connection { /* fields omitted */ }

Connection to an Oracle database

Methods

impl Connection

pub fn connect(
    username: &str,
    password: &str,
    connect_string: &str,
    params: &[ConnParam]
) -> Result<Connection>

Connects to an Oracle server

Examples

Connect to a local database.

let conn = Connection::connect("scott", "tiger", "", &[]).unwrap();

Connect to a remote database specified by easy connect naming.

let conn = Connection::connect("scott", "tiger",
                               "server_name:1521/service_name", &[]).unwrap();

Connect as sysdba.

let conn = Connection::connect("system", "manager", "",
                               &[ConnParam::Sysdba]).unwrap();

pub fn new(
    username: &str,
    password: &str,
    connect_string: &str
) -> Result<Connection>

Deprecated since 0.0.6

: use Connection::connect() instead

pub fn prepare(&self, sql: &str) -> Result<Statement>

Prepares a statement and returns it for subsequent execution/fetching

Examples

let conn = Connection::connect("scott", "tiger", "", &[]).unwrap();
let mut stmt = conn.prepare("insert into emp(empno, ename) values (:id, :name)").unwrap();

// insert one row. (set parameters by position)
stmt.execute(&[&113, &"John"]).unwrap();

// insert another row. (set parameters by name)
stmt.execute_named(&[("id", &114),
                     ("name", &"Smith")]).unwrap();

pub fn execute(&self, sql: &str, params: &[&ToSql]) -> Result<Statement>

Prepares a statement, binds values by position and executes it in one call. It will retunrs Err when the statemnet is a select statement.

Examples

let conn = Connection::connect("scott", "tiger", "", &[]).unwrap();

// execute a statement without bind parameters
conn.execute("insert into emp(empno, ename) values (113, 'John')", &[]).unwrap();

// execute a statement with binding parameters by position
conn.execute("insert into emp(empno, ename) values (:1, :2)", &[&114, &"Smith"]).unwrap();

pub fn execute_named(
    &self,
    sql: &str,
    params: &[(&str, &ToSql)]
) -> Result<Statement>

Prepares a statement, binds values by name and executes it in one call. It will retunrs Err when the statemnet is a select statement.

The bind variable names are compared case-insensitively.

Examples

let conn = Connection::connect("scott", "tiger", "", &[]).unwrap();

// execute a statement with binding parameters by name
conn.execute_named("insert into emp(empno, ename) values (:id, :name)",
                   &[("id", &114),
                     ("name", &"Smith")]).unwrap();

pub fn query(&self, sql: &str, params: &[&ToSql]) -> Result<ResultSet<Row>>

Executes a select statement and returns a result set containing Rows.

pub fn query_named(
    &self,
    sql: &str,
    params: &[(&str, &ToSql)]
) -> Result<ResultSet<Row>>

Executes a select statement using named parameters and returns a result set containing Rows.

pub fn query_as<T>(&self, sql: &str, params: &[&ToSql]) -> Result<ResultSet<T>> where
    T: RowValue, 

Executes a select statement and returns a result set containing RowValues.

pub fn query_as_named<T>(
    &self,
    sql: &str,
    params: &[(&str, &ToSql)]
) -> Result<ResultSet<T>> where
    T: RowValue, 

Executes a select statement using named parameters and returns a result set containing RowValues.

pub fn query_row(&self, sql: &str, params: &[&ToSql]) -> Result<Row>

Gets one row from a query in one call.

pub fn query_row_named(
    &self,
    sql: &str,
    params: &[(&str, &ToSql)]
) -> Result<Row>

Gets one row from a query using named bind parameters in one call.

pub fn query_row_as<T>(&self, sql: &str, params: &[&ToSql]) -> Result<T::Item> where
    T: RowValue, 

Gets one row from a query as specified type in one call.

This is same with the combination of prepare, query_as and next. However the former is a bit optimized about memory usage. The former prepares memory for one row. On the other hand the latter internally prepares memory for 100 rows by default in order to reduce the number of network roundtrips when many rows are fetched.

Type inference for the return type doesn't work. You need to specify it explicitly as conn.query_row_as::<...>(sql_stmt, bind_parameters). See RowValue for available return types.

Examples

let conn = Connection::connect("scott", "tiger", "", &[]).unwrap();

// get a row as `(i32, String)`.
let sql = "select empno, ename from emp where empno = 7369";
let tuple = conn.query_row_as::<(i32, String)>(sql, &[]).unwrap();
assert_eq!(tuple.0, 7369);
assert_eq!(tuple.1, "SMITH");

// get it as same type using a destructuring let and a bind parameter.
let sql = "select empno, ename from emp where empno = :1";
let (empno, ename) = conn.query_row_as::<(i32, String)>(sql, &[&7369]).unwrap();
assert_eq!(empno, 7369);
assert_eq!(ename, "SMITH");

pub fn query_row_as_named<T>(
    &self,
    sql: &str,
    params: &[(&str, &ToSql)]
) -> Result<T::Item> where
    T: RowValue, 

Gets one row from a query with named bind parameters as specified type in one call.

See query_row_as for more detail.

Examples

let conn = Connection::connect("scott", "tiger", "", &[]).unwrap();

// fetch as a tuple whose type is `(i32, String)` with a named bind parameter "empno".
let sql = "select empno, ename from emp where empno = :empno";
let (empno, ename) = conn.query_row_as_named::<(i32, String)>(sql, &[("empno", &7369)]).unwrap();
assert_eq!(empno, 7369);
assert_eq!(ename, "SMITH");

pub fn break_execution(&self) -> Result<()>

Cancels execution of running statements in the connection

pub fn commit(&self) -> Result<()>

Commits the current active transaction

pub fn rollback(&self) -> Result<()>

Rolls back the current active transaction

pub fn close(&self) -> Result<()>

Closes the connection before the end of lifetime.

This fails when open statements or LOBs exist.

pub fn server_version(&self) -> Result<(Version, String)>

Gets information about the server version

Examples

let conn = Connection::connect("scott", "tiger", "", &[]).unwrap();
let (version, banner) = conn.server_version().unwrap();
println!("Oracle Version: {}", version);
println!("--- Version Banner ---");
println!("{}", banner);
println!("---------------------");

pub fn change_password(
    &self,
    username: &str,
    old_password: &str,
    new_password: &str
) -> Result<()>

Changes the password for the specified user

pub fn ping(&self) -> Result<()>

Pings the connection to see if it is still alive

pub fn current_schema(&self) -> Result<String>

Gets current schema associated with the connection

pub fn set_current_schema(&self, current_schema: &str) -> Result<()>

Sets current schema associated with the connection

pub fn edition(&self) -> Result<String>

Gets edition associated with the connection

pub fn external_name(&self) -> Result<String>

Gets external name associated with the connection

pub fn set_external_name(&self, external_name: &str) -> Result<()>

Sets external name associated with the connection

pub fn internal_name(&self) -> Result<String>

Gets internal name associated with the connection

pub fn set_internal_name(&self, internal_name: &str) -> Result<()>

Sets internal name associated with the connection

pub fn stmt_cache_size(&self) -> Result<u32>

Gets the statement cache size

pub fn set_stmt_cache_size(&self, size: u32) -> Result<()>

Sets the statement cache size

pub fn set_module(&self, module: &str) -> Result<()>

Sets module associated with the connection

This is same with calling DBMS_APPLICATION_INFO.SET_MODULE but without executing a statement. The module name is piggybacked to the server with the next network round-trip.

pub fn set_action(&self, action: &str) -> Result<()>

Sets action associated with the connection

This is same with calling DBMS_APPLICATION_INFO.SET_ACTION but without executing a statement. The action name is piggybacked to the server with the next network round-trip.

pub fn set_client_info(&self, client_info: &str) -> Result<()>

Sets client info associated with the connection

This is same with calling DBMS_APPLICATION_INFO.SET_CLIENT_INFO but without executing a statement. The client info is piggybacked to the server with the next network round-trip.

pub fn autocommit(&self) -> bool

Gets autocommit mode. It is false by default.

pub fn set_autocommit(&mut self, autocommit: bool)

Enables or disables autocommit mode. It is disabled by default.

pub fn set_client_identifier(&self, client_identifier: &str) -> Result<()>

Sets client identifier associated with the connection

This is same with calling DBMS_SESSION.SET_IDENTIFIER but without executing a statement. The client identifier is piggybacked to the server with the next network round-trip.

pub fn set_db_op(&self, db_op: &str) -> Result<()>

Sets name of the database operation to be monitored in the database. Sets to '' if you want to end monitoring the current running database operation.

This is same with calling DBMS_SQL_MONITOR.BEGIN_OPERATION but without executing a statement. The database operation name is piggybacked to the server with the next network round-trip.

See Monitoring Database Operations in Oracle Database SQL Tuning Guide

pub fn object_type(&self, name: &str) -> Result<ObjectType>

Gets an object type information from name

let conn = Connection::connect("scott", "tiger", "", &[]).unwrap();
let objtype = conn.object_type("MDSYS.SDO_GEOMETRY");

pub fn startup_database(&self, modes: &[StartupMode]) -> Result<()>

Starts up a database

This corresponds to sqlplus command startup nomount. You need to connect the databas as system privilege in prelim_auth mode in advance. After this method is executed, you need to reconnect the server as system privilege without prelim_auth and executes alter database mount and then alter database open.

Examples

Connect to an idle instance as sysdba and start up a database

// connect as sysdba with prelim_auth mode
let conn = Connection::connect("sys", "change_on_install", "",
                                &[ConnParam::Sysdba,
                                  ConnParam::PrelimAuth,
                                  ]).unwrap();

// start the instance
conn.startup_database(&[]).unwrap();
conn.close().unwrap();

// connect again without prelim_auth
let conn = Connection::connect("sys", "change_on_install", "",
                                &[ConnParam::Sysdba,
                                  ]).unwrap();

// mount and open a database
conn.execute("alter database mount", &[]).unwrap();
conn.execute("alter database open", &[]).unwrap();

Start up a database in restricted mode

...
conn.startup_database(&[StartupMode::Restrict]).unwrap();
...

If the database is running, shut it down with mode ABORT and then start up in restricted mode

...
conn.startup_database(&[StartupMode::Force, StartupMode::Restrict]).unwrap();
...

pub fn shutdown_database(&self, mode: ShutdownMode) -> Result<()>

Shuts down a database

When this method is called with ShutdownMode::Default, ShutdownMode::Transactional, ShutdownMode::TransactionalLocal or ShutdownMode::Immediate, execute "alter database close normal" and "alter database dismount" and call this method again with ShutdownMode::Final.

When this method is called with ShutdownMode::Abort, the database is aborted immediately.

Examples

Same with shutdown immediate on sqlplus.

// connect as sysdba
let conn = Connection::connect("sys", "change_on_install", "",
                               &[ConnParam::Sysdba]).unwrap();

// begin 'shutdown immediate'
conn.shutdown_database(ShutdownMode::Immediate).unwrap();

// close and dismount the database
conn.execute("alter database close normal", &[]).unwrap();
conn.execute("alter database dismount", &[]).unwrap();

// finish shutdown
conn.shutdown_database(ShutdownMode::Final).unwrap();

Same with shutdown abort on sqlplus.

// connect as sysdba
let conn = Connection::connect("sys", "change_on_install", "",
                               &[ConnParam::Sysdba]).unwrap();

// 'shutdown abort'
conn.shutdown_database(ShutdownMode::Abort).unwrap();

// The database is aborted here.

Trait Implementations

impl Drop for Connection

fn drop(&mut self)

Executes the destructor for this type.