[−][src]Struct oracle::Connection
Connection to an Oracle database
Implementations
impl Connection
[src]
pub fn connect<U, P, C>(
username: U,
password: P,
connect_string: C
) -> Result<Connection> where
U: AsRef<str>,
P: AsRef<str>,
C: AsRef<str>,
[src]
username: U,
password: P,
connect_string: C
) -> Result<Connection> where
U: AsRef<str>,
P: AsRef<str>,
C: AsRef<str>,
Connects to an Oracle server using username, password and connect string.
If you need to connect the server with additional parameters such as SYSDBA privilege, use Connector instead.
Examples
Connect to a local database.
let conn = Connection::connect("scott", "tiger", "")?;
Connect to a remote database specified by easy connect naming.
let conn = Connection::connect("scott", "tiger", "server_name:1521/service_name")?;
pub fn close(&self) -> Result<()>
[src]
Closes the connection before the end of lifetime.
This fails when open statements or LOBs exist.
pub fn prepare(&self, sql: &str, params: &[StmtParam]) -> Result<Statement<'_>>
[src]
Prepares a statement
Examples
Executes a SQL statement with different parameters.
let mut stmt = conn.prepare("insert into emp(empno, ename) values (:id, :name)", &[])?; let emp_list = [ (7369, "Smith"), (7499, "Allen"), (7521, "Ward"), ]; // insert rows using positional parameters for emp in &emp_list { stmt.execute(&[&emp.0, &emp.1])?; } let emp_list = [ (7566, "Jones"), (7654, "Martin"), (7698, "Blake"), ]; // insert rows using named parameters for emp in &emp_list { stmt.execute_named(&[("id", &emp.0), ("name", &emp.1)])?; }
Query methods in Connection allocate memory for 100 rows by default
to reduce the number of network round trips in case that many rows are
fetched. When 100 isn't preferable, use StmtParam::FetchArraySize(u32)
to customize it.
// fetch top 10 rows. let mut stmt = conn.prepare("select * from (select empno, ename from emp order by empno) where rownum <= 10", &[StmtParam::FetchArraySize(10)])?; for row_result in stmt.query_as::<(i32, String)>(&[])? { let (empno, ename) = row_result?; println!("empno: {}, ename: {}", empno, ename); }
pub fn query(
&self,
sql: &str,
params: &[&dyn ToSql]
) -> Result<ResultSet<'_, Row>>
[src]
&self,
sql: &str,
params: &[&dyn ToSql]
) -> Result<ResultSet<'_, Row>>
Executes a select statement and returns a result set containing Rows.
See Query Methods.
pub fn query_named(
&self,
sql: &str,
params: &[(&str, &dyn ToSql)]
) -> Result<ResultSet<'_, Row>>
[src]
&self,
sql: &str,
params: &[(&str, &dyn ToSql)]
) -> Result<ResultSet<'_, Row>>
Executes a select statement using named parameters and returns a result set containing Rows.
See Query Methods.
pub fn query_as<T>(
&self,
sql: &str,
params: &[&dyn ToSql]
) -> Result<ResultSet<'_, T>> where
T: RowValue,
[src]
&self,
sql: &str,
params: &[&dyn ToSql]
) -> Result<ResultSet<'_, T>> where
T: RowValue,
Executes a select statement and returns a result set containing RowValues.
See Query Methods.
pub fn query_as_named<T>(
&self,
sql: &str,
params: &[(&str, &dyn ToSql)]
) -> Result<ResultSet<'_, T>> where
T: RowValue,
[src]
&self,
sql: &str,
params: &[(&str, &dyn ToSql)]
) -> Result<ResultSet<'_, T>> where
T: RowValue,
Executes a select statement using named parameters and returns a result set containing RowValues.
See Query Methods.
pub fn query_row(&self, sql: &str, params: &[&dyn ToSql]) -> Result<Row>
[src]
Gets one row from a query using positoinal bind parameters.
See Query Methods.
pub fn query_row_named(
&self,
sql: &str,
params: &[(&str, &dyn ToSql)]
) -> Result<Row>
[src]
&self,
sql: &str,
params: &[(&str, &dyn ToSql)]
) -> Result<Row>
Gets one row from a query using named bind parameters.
See Query Methods.
pub fn query_row_as<T>(&self, sql: &str, params: &[&dyn ToSql]) -> Result<T> where
T: RowValue,
[src]
T: RowValue,
Gets one row from a query as specified type.
See Query Methods.
pub fn query_row_as_named<T>(
&self,
sql: &str,
params: &[(&str, &dyn ToSql)]
) -> Result<T> where
T: RowValue,
[src]
&self,
sql: &str,
params: &[(&str, &dyn ToSql)]
) -> Result<T> where
T: RowValue,
Gets one row from a query with named bind parameters as specified type.
See Query Methods.
pub fn execute(&self, sql: &str, params: &[&dyn ToSql]) -> Result<Statement<'_>>
[src]
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", "")?; // execute a statement without bind parameters conn.execute("insert into emp(empno, ename) values (113, 'John')", &[])?; // execute a statement with binding parameters by position conn.execute("insert into emp(empno, ename) values (:1, :2)", &[&114, &"Smith"])?;
pub fn execute_named(
&self,
sql: &str,
params: &[(&str, &dyn ToSql)]
) -> Result<Statement<'_>>
[src]
&self,
sql: &str,
params: &[(&str, &dyn 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", "")?; // execute a statement with binding parameters by name conn.execute_named("insert into emp(empno, ename) values (:id, :name)", &[("id", &114), ("name", &"Smith")])?;
pub fn commit(&self) -> Result<()>
[src]
Commits the current active transaction
pub fn rollback(&self) -> Result<()>
[src]
Rolls back the current active transaction
pub fn autocommit(&self) -> bool
[src]
Gets autocommit mode. It is false by default.
pub fn set_autocommit(&mut self, autocommit: bool)
[src]
Enables or disables autocommit mode. It is disabled by default.
pub fn break_execution(&self) -> Result<()>
[src]
Cancels execution of running statements in the connection
pub fn object_type(&self, name: &str) -> Result<ObjectType>
[src]
Gets an object type information from name
let conn = Connection::connect("scott", "tiger", "")?; let objtype = conn.object_type("MDSYS.SDO_GEOMETRY");
Note that the object type is cached in the connection. However when "CREATE TYPE", "ALTER TYPE" or "DROP TYPE" is executed, the cache clears.
pub fn clear_object_type_cache(&self) -> Result<()>
[src]
Clear the object type cache in the connection.
See also object_type
.
pub fn object_type_cache_len(&self) -> usize
[src]
pub fn server_version(&self) -> Result<(Version, String)>
[src]
Gets information about the server version
NOTE: if you connect to Oracle Database 18 or higher with Oracle client libraries 12.2 or lower, it gets the base version (such as 18.0.0.0.0) instead of the full version (such as 18.3.0.0.0).
Examples
let conn = Connection::connect("scott", "tiger", "")?; let (version, banner) = conn.server_version()?; println!("Oracle Version: {}", version); println!("--- Version Banner ---"); println!("{}", banner); println!("---------------------");
pub fn change_password(
&self,
username: &str,
old_password: &str,
new_password: &str
) -> Result<()>
[src]
&self,
username: &str,
old_password: &str,
new_password: &str
) -> Result<()>
Changes the password for the specified user
pub fn ping(&self) -> Result<()>
[src]
Pings the connection to see if it is still alive.
It checks the connection by making a network round-trip between the client and the server.
See also Connection.status.
pub fn status(&self) -> Result<ConnStatus>
[src]
Gets the status of the connection.
It returns Ok(ConnStatus::Closed)
when the connection was closed
by Connection.close.
Otherwise see bellow.
Oracle client 12.2 and later:
It checks whether the underlying TCP socket has disconnected by the server. There is no guarantee that the server is alive and the network between the client and server has no trouble.
For example, it returns Ok(ConnStatus::NotConnected)
when the
database on the server-side OS stopped and the client received
a FIN or RST packet. However it returns Ok(ConnStatus::Normal)
when the server-side OS itself crashes or the network is in
trouble.
Oracle client 11.2 and 12.1:
It returns Ok(ConnStatus::Normal)
when the last network
round-trip between the client and server went through. Otherwise,
Ok(ConnStatus::NotConnected)
. There is no guarantee that the
next network round-trip will go through.
See also Connection.ping.
pub fn stmt_cache_size(&self) -> Result<u32>
[src]
Gets the statement cache size
pub fn set_stmt_cache_size(&self, size: u32) -> Result<()>
[src]
Sets the statement cache size
pub fn call_timeout(&self) -> Result<Option<Duration>>
[src]
Gets the current call timeout used for round-trips to
the database made with this connection. None
means that no timeouts
will take place.
pub fn set_call_timeout(&self, dur: Option<Duration>) -> Result<()>
[src]
Sets the call timeout to be used for round-trips to the database made with this connection. None means that no timeouts will take place.
The call timeout value applies to each database round-trip individually, not to the sum of all round-trips. Time spent processing in rust-oracle before or after the completion of each round-trip is not counted.
-
If the time from the start of any one round-trip to the completion of that same round-trip exceeds call timeout, then the operation is halted and an exception occurs.
-
In the case where an rust-oracle operation requires more than one round-trip and each round-trip takes less than call timeout, then no timeout will occur, even if the sum of all round-trip calls exceeds call timeout.
-
If no round-trip is required, the operation will never be interrupted.
After a timeout is triggered, rust-oracle attempts to clean up the
internal connection state. The cleanup is allowed to take another
duration
.
If the cleanup was successful, an exception DPI-1067 will be raised but the application can continue to use the connection.
For small values of call timeout, the connection cleanup may not complete successfully within the additional call timeout period. In this case an exception ORA-3114 is raised and the connection will no longer be usable. It should be closed.
pub fn current_schema(&self) -> Result<String>
[src]
Gets current schema associated with the connection
pub fn set_current_schema(&self, current_schema: &str) -> Result<()>
[src]
Sets current schema associated with the connection
pub fn edition(&self) -> Result<String>
[src]
Gets edition associated with the connection
pub fn external_name(&self) -> Result<String>
[src]
Gets external name associated with the connection
pub fn set_external_name(&self, external_name: &str) -> Result<()>
[src]
Sets external name associated with the connection
pub fn internal_name(&self) -> Result<String>
[src]
Gets internal name associated with the connection
pub fn set_internal_name(&self, internal_name: &str) -> Result<()>
[src]
Sets internal name associated with the connection
pub fn set_module(&self, module: &str) -> Result<()>
[src]
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<()>
[src]
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<()>
[src]
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 set_client_identifier(&self, client_identifier: &str) -> Result<()>
[src]
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<()>
[src]
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 startup_database(&self, modes: &[StartupMode]) -> Result<()>
[src]
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 = Connector::new("sys", "change_on_install", "") .privilege(Privilege::Sysdba) .prelim_auth(true) .connect()?; // start the instance conn.startup_database(&[])?; conn.close()?; // connect again without prelim_auth let conn = Connector::new("sys", "change_on_install", "") .privilege(Privilege::Sysdba) .connect()?; // mount and open a database conn.execute("alter database mount", &[])?; conn.execute("alter database open", &[])?;
Start up a database in restricted mode
... conn.startup_database(&[StartupMode::Restrict])?; ...
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])?; ...
pub fn shutdown_database(&self, mode: ShutdownMode) -> Result<()>
[src]
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 = Connector::new("sys", "change_on_install", "") .privilege(Privilege::Sysdba) .connect()?; // begin 'shutdown immediate' conn.shutdown_database(ShutdownMode::Immediate)?; // close and dismount the database conn.execute("alter database close normal", &[])?; conn.execute("alter database dismount", &[])?; // finish shutdown conn.shutdown_database(ShutdownMode::Final)?;
Same with shutdown abort
on sqlplus.
// connect as sysdba let conn = Connector::new("sys", "change_on_install", "") .privilege(Privilege::Sysdba).connect()?; // 'shutdown abort' conn.shutdown_database(ShutdownMode::Abort)?; // The database is aborted here.
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for Connection
impl Send for Connection
impl Sync for Connection
impl Unpin for Connection
impl UnwindSafe for Connection
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,