Struct Pool

pub struct Pool { /* private fields */ }

Connection pool

Examples

Get connections in a pool

// Create a pool
let pool = PoolBuilder::new(username, password, connect_string)
    .max_connections(20)
    .build()?;

// Get connections from the pool.
let conn1 = pool.get()?;
let conn2 = pool.get()?;

assert_eq!(pool.open_count()?, 2); // Two connections are in the pool.
assert_eq!(pool.busy_count()?, 2); // Two connections are in use.

// Return the connections to the pool.
conn1.close()?;
conn2.close()?;

assert_eq!(pool.open_count()?, 2); // Two connections are in the pool.
assert_eq!(pool.busy_count()?, 0); // No connections are in use.

Use a heterogeneous pool to pool different users’ connections

// Create a pool
let pool = PoolBuilder::new(username, password, connect_string)
    .pool_type(PoolType::Heterogeneous)
    .max_connections(20)
    .build()?;

// Get a connection from the pool.
let conn1 = pool.get()?;
let conn1_user = conn1.query_row_as::<String>("select lower(user) from dual", &[])?;
assert_eq!(conn1_user, username);

// Get an another user's connection.
let opts = PoolOptions::new().username(another_username).password(another_password);
let conn2 = pool.get_with_options(&opts)?; // with connector to pass username and password
let conn2_user = conn2.query_row_as::<String>("select lower(user) from dual", &[])?;
assert_eq!(conn2_user, another_username);

Get connections with tags (NAME=VALUE pairs)

// Create a pool
let pool = PoolBuilder::new(username, password, connect_string)
    .max_connections(20)
    .build()?;

// Create Pool options to specify a tag.
let opts = PoolOptions::new().tag("LANG=FRENCH");

// Get a connection with tag "LANG=FRENCH".
// There are no connections with the tag at this point.
let conn = pool.get_with_options(&opts)?;
assert_eq!(conn.tag_found(), false, "conn.tag_found() (1)"); // new connection
// Change the nls_language for later.
if !conn.tag_found() {
  conn.execute("alter session set nls_language = FRENCH", &[])?;
}
// ...
// use the connection
// ...
// return it to the pool with new tag.
conn.close_with_mode(conn::CloseMode::Retag("LANG=FRENCH"))?;

// Get a connection with tag "LANG=FRENCH" again.
// There is one connection with the tag at this point.
let conn = pool.get_with_options(&opts)?;
assert_eq!(conn.tag_found(), true, "conn.tag_found() (2)");
assert_eq!(conn.tag(), "LANG=FRENCH", "conn.tag() (2)");
// Check whether this is the connection previously
let sql = "select value from nls_session_parameters where parameter = 'NLS_LANGUAGE'";
assert_eq!(conn.query_row_as::<String>(sql, &[])?, "FRENCH");
// ...
// The connection has been tagged already. There is no need to set a new tag.
conn.close()?;

Implementations

impl Pool

pub fn get(&self) -> Result<Connection>

Gets a connection from the pool with default parameters.

Use Pool::get_with_options to get a new one with additional parameters.

When the connection is dropped, it backs to the pool for subsequent calls to this function. The connection can be returned back to the pool earlier by calling Connection::close.

pub fn get_with_options(&self, options: &PoolOptions) -> Result<Connection>

Acquires a connection from the specified connection pool.

See also Pool::get.

pub fn close(&self, mode: &CloseMode) -> Result<()>

Closes the pool and makes it unusable for further activity.

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

Returns the number of connections in the pool that are busy.

Examples

let pool = PoolBuilder::new(username, password, connect_string)
    .max_connections(3)
    .build()?;
assert_eq!(pool.busy_count()?, 0);
let conn1 = pool.get()?;
let conn2 = pool.get()?;
assert_eq!(pool.busy_count()?, 2);
conn1.close()?;
conn2.close()?;
assert_eq!(pool.busy_count()?, 0);

pub fn get_mode(&self) -> Result<GetMode>

Returns the mode used for acquiring or getting connections from the pool.

See also PoolBuilder::get_mode and Pool::set_get_mode.

pub fn set_get_mode(&mut self, mode: &GetMode) -> Result<()>

Sets the mode used for acquiring or getting connections from the pool.

See also PoolBuilder::get_mode and Pool::get_mode.

pub fn max_lifetime_connection(&self) -> Result<Duration>

Returns the maximum lifetime a pooled connection may exist.

See also PoolBuilder::max_lifetime_connection and Pool::set_max_lifetime_connection.

pub fn set_max_lifetime_connection(&mut self, dur: Duration) -> Result<()>

Sets the maximum lifetime a pooled connection may exist.

See also PoolBuilder::max_lifetime_connection and Pool::max_lifetime_connection.

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

Returns the maximum connections per shard. This parameter is used for balancing shards.

See also PoolBuilder::max_connections_per_shard and Pool::set_max_connections_per_shard.

pub fn set_max_connections_per_shard( &mut self, max_connections: u32, ) -> Result<()>

Sets the maximum number of connections per shard.

See also PoolBuilder::max_connections_per_shard and Pool::max_connections_per_shard.

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

Returns the number of connections in the pool that are open.

pub fn ping_interval(&self) -> Result<Option<Duration>>

Returns the ping interval duration, which is used to check the healthiness of idle connections before getting checked out. A None value indicates this check is disabled.

See also PoolBuilder::ping_interval and Pool::set_ping_interval.

pub fn set_ping_interval(&mut self, interval: Option<Duration>) -> Result<()>

Sets the ping interval duration which is used to to check for healthiness of connections. If this time has passed since the last time the connection was checked out a ping will be performed. A None value will disable this check.

See also PoolBuilder::ping_interval and Pool::ping_interval.

pub fn reconfigure( &self, min_connections: u32, max_connections: u32, connection_increment: u32, ) -> Result<()>

Changes pool configuration corresponding to PoolBuilder::min_connections, PoolBuilder::max_connections and PoolBuilder::connection_increment to the specified values.

Connections will be created as needed if the value of min_connections is increased. Connections will be dropped from the pool as they are released back to the pool if min_connections is decreased.

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

Returns the default size of the statement cache for connections in the pool, in number of statements.

See also PoolBuilder::stmt_cache_size and Pool::set_stmt_cache_size.

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

Sets the default size of the statement cache for connections in the pool.

See also PoolBuilder::stmt_cache_size and Pool::stmt_cache_size.

pub fn timeout(&self) -> Result<Duration>

Returns the length of time after which idle connections in the pool are terminated. Note that termination only occurs when the pool is accessed. A value of Duration::ZERO means that no ide connections are terminated.

See also PoolBuilder::timeout and Pool::set_timeout.

pub fn set_timeout(&mut self, timeout: Duration) -> Result<()>

Sets the amount of time after which idle connections in the pool are terminated. Note that termination only occurs when the pool is accessed. A value of Duration::ZERO will result in no idle connections being terminated.

See also PoolBuilder::timeout and Pool::timeout.

Trait Implementations

impl Clone for Pool

fn clone(&self) -> Pool

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Pool

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.