Crate sibyl

Expand description

Sibyl is an OCI-based interface between Rust applications and Oracle databases. Sibyl supports both sync (blocking) and async (nonblocking) API.

Blocking Mode Example

fn main() -> sibyl::Result<()> {
    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)?;

    let stmt = session.prepare("
        SELECT c.country_name, Median(e.salary)
          FROM hr.employees e
          JOIN hr.departments d ON d.department_id = e.department_id
          JOIN hr.locations l   ON l.location_id = d.location_id
          JOIN hr.countries c   ON c.country_id = l.country_id
          JOIN hr.regions r     ON r.region_id = c.region_id
         WHERE r.region_name = :REGION_NAME
      GROUP BY c.country_name
    ")?;

    let rows = stmt.query("Europe")?;

    while let Some(row) = rows.next()? {
        let country_name : &str = row.get(0)?;
        let median_salary : u16 = row.get(1)?;
        println!("{:25}: {:>5}", country_name, median_salary);
    }
    Ok(())
}

Nonblocking Mode Example

fn main() -> sibyl::Result<()> {
  block_on(async {
    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?;

    let stmt = session.prepare("
        SELECT c.country_name, Median(e.salary)
          FROM hr.employees e
          JOIN hr.departments d ON d.department_id = e.department_id
          JOIN hr.locations l   ON l.location_id = d.location_id
          JOIN hr.countries c   ON c.country_id = l.country_id
          JOIN hr.regions r     ON r.region_id = c.region_id
         WHERE r.region_name = :REGION_NAME
      GROUP BY c.country_name
    ").await?;

    let rows = stmt.query("Europe").await?;

    while let Some(row) = rows.next().await? {
        let country_name : &str = row.get(0)?;
        let median_salary : u16 = row.get(1)?;
        println!("{:25}: {:>5}", country_name, median_salary);
    }
    Ok(())
  })
}

Note that block_on in the example is an internal abstraction over block_on of different async executors. It is intended only to help running Sibyl’s own tests and examples.

Features

Sibyl has 2 main features - blocking and nonblocking. They are exclusive and one must be explicitly selected as neither is the default.

Sibyl compiled with a nonblocking feature needs to integrate with the async executor that the application uses. At the moment Sybil supports Tokio, Actix, async-std, and async-global-executor. One (and only one) of those must be selected together with a nonblocking feature:

Feature	async Runtime
`tokio`	Tokio
`actix`	Actix
`async-std`	async-std
`async-global`	async-global-executor

Thus, for example, when Sibyl is used as a dependency, it might be included as:

[dependencies]
sibyl = { version = "0.6", features = ["blocking"] }

Or, when Sibyl is used in nonblocking mode as:

[dependencies]
sibyl = { version = "0.6", features = ["nonblocking", "tokio"] }

Structs

ConnectionPoolblocking

A shared pool of physical connections.

Cursor

REF CURSORs or implicit results (from DBMS_SQL.RETURN_RESULT) of an executed PL/SQL statement.

Date

Represents Oracle DATE

DateTime

Represents datetime data types.

Environment

Represents an OCI environment.

Interval

Represents interval data types

LOB

LOB locator.

Number

Represents OTS types NUMBER, NUMERIC, INT, SHORTINT, REAL, DOUBLE PRECISION, FLOAT and DECIMAL.

Nvl

A Nullable Value.

Raw

Represents RAW and LONG RAW data types.

Row

A row in the returned result set

RowID

Represents ROWID

Rows

Result set of a query

Session

Represents a user session

SessionPool

Session pool creates and maintains a group of stateless sessions to the database.

Statement

Represents a prepared for execution SQL or PL/SQL statement

Varchar

Represents Oracle character types - VARCHAR, LONG, etc.

Enums

Cache

LOB cache control flags

CharSetForm

Character set form

ColumnType

Column data type.

Error

Represents possible errors returned from Sibyl

SessionPoolGetMode

Represents the behavior of the session pool when all sessions in the pool are found to be busy and the number of sessions has reached the maximum or the pool must create new connections.

Statics

NUM_ACTIVE_ASYNC_DROPSnonblocking

Counter that keeps the number of active async drops.

Traits

FromSql

A trait for types which values can be created from the returned Oracle data.

Integer

Marker trait for integer numbers

Position

Allows column or output variable identification by either its numeric position or its name.

ToSql

A trait for types that can be used as SQL arguments

Functions

client_version

Returns the 5 digit tuple with the Oracle database version number of the client library at run time.

env

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

Type Definitions

BFile

A locator to a large binary file.

BLOB

A binary large object locator.

CLOB

A character large object locator.

IntervalDS

Represents INTERVAL DAY TO SECOND data type. It stores a period of time in terms of days, hours, minutes, and seconds.

IntervalYM

Represents INTERVAL YEAR TO MONTH data type. It stores a period of time in terms of years and months.

Result

A specialized Result type for Sibyl.

Timestamp

Represents the TIMESTAMP data type. It stores year, month, day, hour, minute, second and fractional seconds.

TimestampLTZ

Represents the TIMESTAMP WITH LOCAL TIME ZONE data type. It’s a variant of TIMESTAMP that is normalized to the database time zone.

TimestampTZ

Represents the TIMESTAMP WITH TIME ZONE data type. It’s a variant of TIMESTAMP that includes of a time zone region name or time zone offset in its value.