Struct oracle::Connection

pub struct Connection { /* fields omitted */ }

Connection to an Oracle database

Methods

impl Connection

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

Connects to an Oracle database with username, password and connect_string.

When you need to set more parameters before connecting to the server, see Connector.

Examples

To connect to a local database.

let conn = oracle::Connection::new("scott", "tiger", "").unwrap();

To connect to a remote database specified by easy connect naming.

let conn = oracle::Connection::new("scott", "tiger", "server_name:1521/service_name").unwrap();

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

Prepares a statement and returns it for subsequent execution/fetching

Examples

let conn = oracle::Connection::new("scott", "tiger", "").unwrap();
let mut stmt = conn.prepare("insert into emp(empno, ename) values (:1, :2)").unwrap();

// insert one row.
stmt.execute(&(113, "John")).unwrap();

// insert another row.
stmt.execute(&(114, "Smith")).unwrap();

fn execute<T, U>(&self, sql: &str, params: &T) -> Result<Statement> where
    T: ToSqlInTuple<U>, 

Prepares a statement, binds values and executes it in one call.

Examples

let conn = oracle::Connection::new("scott", "tiger", "").unwrap();

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

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

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

Cancels execution of running statements in the connection

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

Commits the current active transaction

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

Rolls back the current active transaction

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

Closes the connection before the end of lifetime.

This fails when open statements or LOBs exist.

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

Gets information about the server version

Examples

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

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

Changes the password for the specified user

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

Pings the connection to see if it is still alive

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

Gets current schema associated with the connection

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

Sets current schema associated with the connection

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

Gets edition associated with the connection

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

Gets external name associated with the connection

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

Sets external name associated with the connection

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

Gets internal name associated with the connection

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

Sets internal name associated with the connection

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

Gets the statement cache size

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

Sets the statement cache size

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.

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.

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.

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.

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

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

use oracle::{Connector, AuthMode};
// connect to an idle instance
let conn = Connector::new("sys", "change_on_install", "")
             .prelim_auth(true) // required to connect to an idle instance
             .auth_mode(AuthMode::SYSDBA) // connect as sysdba
             .connect().unwrap();

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

// connect again without prelim_auth
let conn = Connector::new("sys", "change_on_install", "")
             .auth_mode(AuthMode::SYSDBA) // connect as sysdba
             .connect().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();
...

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.

use oracle::{Connector, AuthMode, ShutdownMode};
// connect
let conn = Connector::new("sys", "change_on_install", "")
             .auth_mode(AuthMode::SYSDBA) // connect as sysdba
             .connect().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(oracle::ShutdownMode::Final).unwrap();

Same with shutdown abort on sqlplus.

use oracle::{Connector, AuthMode, ShutdownMode};
// connect
let conn = Connector::new("sys", "change_on_install", "")
             .auth_mode(AuthMode::SYSDBA) // connect as sysdba
             .connect().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.