Struct sibyl::Environment

pub struct Environment { /* private fields */ }

Represents an OCI environment.

Implementations

impl Environment

pub fn connect(
&self,
dbname: &str,
username: &str,
password: &str
) -> Result<Session<'_>>

Available on crate feature blocking only.

Creates and begins a session for the given server.

Parameters

• dbname - The TNS alias of the database to connect to.
• username - The user ID with which to start the sessions.
• password - The password for the corresponding username.

Example

let oracle = sibyl::env()?;
let dbname = std::env::var("DBNAME")?;
let dbuser = std::env::var("DBUSER")?;
let dbpass = std::env::var("DBPASS")?;

let session = oracle.connect(&dbname, &dbuser, &dbpass)?;

assert!(!session.is_async()?);
assert!(session.is_connected()?);
assert!(session.ping().is_ok());

let stmt = session.prepare("
    SELECT DISTINCT client_driver
      FROM v$session_connect_info
     WHERE sid = SYS_CONTEXT('USERENV', 'SID')
")?;
let row = stmt.query_single(())?.unwrap();
let client_driver : &str = row.get(0)?;
assert_eq!(client_driver, "sibyl");

pub fn create_session_pool(
&self,
dbname: &str,
username: &str,
password: &str,
min: usize,
inc: usize,
max: usize
) -> Result<SessionPool<'_>>

Available on crate feature blocking only.

Creates new session pool.

Parameters

• dbname - The TNS alias of the database to connect to.
• username - The username with which to start the sessions.
• password - The password for the corresponding username.
• min - The minimum number of sessions in the session pool. This number of sessions will be started during pool creation. After min sessions are started, sessions are opened only when necessary.
• inc - The next increment for sessions to be started if the current number of sessions is less than max. The valid values are 0 and higher.
• max - The maximum number of sessions that can be opened in the session pool. After this value is reached, no more sessions are opened. The valid values are 1 and higher.

Example

let oracle = sibyl::env()?;

let dbname = std::env::var("DBNAME")?;
let dbuser = std::env::var("DBUSER")?;
let dbpass = std::env::var("DBPASS")?;

// Create a session pool where each session will connect to the database
// `dbname` and authenticate itself as `dbuser` with password `dbpass`.
// Pool will have no open sessions initially. It will create 1 new session
// at a time, up to the maximum of 10 sessions, when they are requested
// and there are no idle sessions in the pool.
let pool = oracle.create_session_pool(&dbname, &dbuser, &dbpass, 0, 1, 10)?;

let session = pool.get_session()?;
let stmt = session.prepare("
    SELECT DISTINCT client_driver
      FROM v$session_connect_info
     WHERE sid = SYS_CONTEXT('USERENV', 'SID')
")?;
let row = stmt.query_single(())?.unwrap();
let client_driver : &str = row.get(0)?;
assert_eq!(client_driver, "sibyl");

pub fn create_connection_pool(
&self,
dbname: &str,
username: &str,
password: &str,
min: usize,
inc: usize,
max: usize
) -> Result<ConnectionPool<'_>>

Available on crate feature blocking only.

Creates new connection pool.

Parameters

• dbname - The TNS alias of the database to connect to.
• username - The username with which to start the sessions.
• password - The password for the corresponding username.
• min - The minimum number of connections to be opened when the pool is created. After the connection pool is created, connections are opened only when necessary. Generally, this parameter should be set to the number of concurrent statements that the application is planning or expecting to run.
• inc - incremental number of connections to be opened when all the connections are busy and a call needs a connection. This increment is used only when the total number of open connections is less than the maximum number of connections that can be opened in that pool.
• max - The maximum number of connections that can be opened to the database. When the maximum number of connections are open and all the connections are busy, if a call needs a connection, it waits until it gets one.

Example

let oracle = sibyl::env()?;

let dbname = std::env::var("DBNAME")?;
let dbuser = std::env::var("DBUSER")?;
let dbpass = std::env::var("DBPASS")?;

let pool = oracle.create_connection_pool(&dbname, &dbuser, &dbpass, 1, 1, 10)?;

let session = pool.get_session(&dbuser, &dbpass)?;
let stmt = session.prepare("
    SELECT DISTINCT client_driver
      FROM v$session_connect_info
     WHERE sid = SYS_CONTEXT('USERENV', 'SID')
")?;
let row = stmt.query_single(())?.unwrap();
let client_driver : &str = row.get(0)?;
assert_eq!(client_driver, "sibyl");

impl Environment

pub async fn connect(
&self,
dbname: &str,
username: &str,
password: &str
) -> Result<Session<'_>>

Available on crate feature nonblocking only.

Creates and begins a user session for a given server.

Parameters

• dbname - The TNS alias of the database to connect to.
• username - The userid with which to start the sessions.
• password - The password for the corresponding username.

Example

let oracle = sibyl::env()?;

let dbname = std::env::var("DBNAME").expect("database name");
let dbuser = std::env::var("DBUSER").expect("user name");
let dbpass = std::env::var("DBPASS").expect("password");

let session = oracle.connect(&dbname, &dbuser, &dbpass).await?;

session.ping().await?;

pub async fn create_session_pool(
&self,
dbname: &str,
username: &str,
password: &str,
min: usize,
inc: usize,
max: usize
) -> Result<SessionPool<'_>>

Available on crate feature nonblocking only.

Creates new session pool.

Parameters

• dbname - The TNS alias of the database to connect to.
• username - The username with which to start the sessions.
• password - The password for the corresponding username.
• min - The minimum number of sessions in the session pool. This number of sessions will be started during pool creation. After min sessions are started, sessions are opened only when necessary.
• inc - The next increment for sessions to be started if the current number of sessions is less than max. The valid values are 0 and higher.
• max - The maximum number of sessions that can be opened in the session pool. After this value is reached, no more sessions are opened. The valid values are 1 and higher.

Example

let oracle = sibyl::env()?;

let dbname = std::env::var("DBNAME").expect("database name");
let dbuser = std::env::var("DBUSER").expect("user name");
let dbpass = std::env::var("DBPASS").expect("password");

// Create a session pool where each session will connect to the database
// `dbname` and authenticate itself as `dbuser` with password `dbpass`.
// Pool will have no open sessions initially. It will create 1 new session
// at a time, up to the maximum of 10 sessions, when they are requested
// and there are no idle sessions in the pool.
let pool = oracle.create_session_pool(&dbname, &dbuser, &dbpass, 0, 1, 10).await?;

let session = pool.get_session().await?;
let stmt = session.prepare("
    SELECT DISTINCT client_driver
      FROM v$session_connect_info
     WHERE sid = SYS_CONTEXT('USERENV', 'SID')
").await?;
let row = stmt.query_single(()).await?.unwrap();
let client_driver : &str = row.get(0)?;
assert_eq!(client_driver, "sibyl");

impl Environment

pub fn new() -> Result<Self>

Returns a new environment handle, which is then used by the OCI functions.

Example

use sibyl::Environment;

let oracle = Environment::new()?;

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

Returns the maximum size (high watermark) for the client-side object cache as a percentage of the optimal size.

Example

let oracle = sibyl::env()?;

let max_size_percentage = oracle.max_cache_size()?;

assert_eq!(max_size_percentage, 10);

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

Sets the maximum size (high watermark) for the client-side object cache as a percentage of the optimal size. Usually, you can set this value at 10%, the default, of the optimal size. Setting this attribute to 0 results in a value of 10 being used. The object cache uses the maximum and optimal values for freeing unused memory in the object cache.

If the memory occupied by the objects currently in the cache reaches or exceeds the maximum cache size, the cache automatically begins to free (or ages out) unmarked objects that have a pin count of zero. The cache continues freeing such objects until memory usage in the cache reaches the optimal size, or until it runs out of objects eligible for freeing. Note that the cache can grow beyond the specified maximum cache size.

The maximum object cache size (in bytes) is computed by incrementing optimal_size by the max_size_percentage, using the following algorithm:

let maximum_cache_size = optimal_size + optimal_size * max_size_percentage / 100;

Parameters

• size - The maximum size for the client-side object cache as a oercentage of the cache optimal size.

Example

let oracle = sibyl::env()?;

oracle.set_cache_max_size(30)?;

let max_size_percentage = oracle.max_cache_size()?;
assert_eq!(max_size_percentage, 30);

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

Returns the optimal size for the client-side object cache in bytes.

Example

let oracle = sibyl::env()?;

let optimal_size = oracle.optimal_cache_size()?;

assert_eq!(optimal_size, 8*1024*1024);

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

Sets the optimal size for the client-side object cache in bytes. The default value is 8 megabytes (MB). Setting this attribute to 0 results in a value of 8 MB being used.

Parameters

• size - The optimal size of the client-side object cache in bytes

Example

let oracle = sibyl::env()?;

oracle.set_cache_opt_size(64*1024*1024)?;

let optimal_size = oracle.optimal_cache_size()?;
assert_eq!(optimal_size, 64*1024*1024);

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

Returns the name of the language used for the database sessions created in the current environment.

See Database Globalization Support Guide / Locale Data / Languages

Example

let oracle = sibyl::env()?;

let lang = oracle.nls_language()?;

assert_eq!(lang, "AMERICAN");

pub fn set_nls_language(&self, lang: &str) -> Result<()>

Sets the language used for the database sessions created in the current environment.

Parameters

• lang - The name of the language used for the database sessions

Example

let oracle = sibyl::env()?;

oracle.set_nls_language("ENGLISH")?;

let lang = oracle.nls_language()?;
assert_eq!(lang, "ENGLISH");
    

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

Returns the name of the territory used for the database sessions created in the current environment.

See Database Globalization Support Guide / Locale Data / Territories

Example

let oracle = sibyl::env()?;

let territory = oracle.nls_territory()?;

assert_eq!(territory, "AMERICA");

pub fn set_nls_territory(&self, territory: &str) -> Result<()>

Sets the name of the territory used for the database sessions created in the current environment.

Parameters

• territory - The name of the territory used for the database sessions

Example

let oracle = sibyl::env()?;
oracle.set_nls_territory("CANADA")?;
let territory = oracle.nls_territory()?;

assert_eq!(territory, "CANADA");