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 overblock_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§
- Connection
Pool blocking
A shared pool of physical connections. REF CURSOR
s or implicit results (fromDBMS_SQL.RETURN_RESULT
) of an executed PL/SQL statement.- Represents Oracle DATE
- Represents datetime data types.
- Represents an OCI environment.
- Represents interval data types
- LOB locator.
- Represents OTS types NUMBER, NUMERIC, INT, SHORTINT, REAL, DOUBLE PRECISION, FLOAT and DECIMAL.
- A Nullable Value.
- Represents RAW and LONG RAW data types.
- A row in the returned result set
- Represents ROWID
- Result set of a query
- Represents a user session
- Session pool creates and maintains a group of stateless sessions to the database.
- Represents a prepared for execution SQL or PL/SQL statement
- Represents Oracle character types - VARCHAR, LONG, etc.
Enums§
- LOB cache control flags
- Character set form
- Column data type.
- Represents possible errors returned from Sibyl
- 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_
ACTIV E_ ASYN C_ DROPS nonblocking
Counter that keeps the number of active async drops.
Traits§
- A trait for types which values can be created from the returned Oracle data.
- Marker trait for integer numbers
- Allows column or output variable identification by either its numeric position or its name.
- A trait for types that can be used as SQL arguments
Functions§
- Returns the 5 digit tuple with the Oracle database version number of the client library at run time.
- Returns a new environment handle, which is then used by the OCI functions.
Type Aliases§
- A locator to a large binary file.
- A binary large object locator.
- A character large object locator.
- Represents
INTERVAL DAY TO SECOND
data type. It stores a period of time in terms of days, hours, minutes, and seconds. - Represents
INTERVAL YEAR TO MONTH
data type. It stores a period of time in terms of years and months. - A specialized
Result
type for Sibyl. - Represents the
TIMESTAMP
data type. It stores year, month, day, hour, minute, second and fractional seconds. - Represents the
TIMESTAMP WITH LOCAL TIME ZONE
data type. It’s a variant ofTIMESTAMP
that is normalized to the database time zone. - Represents the
TIMESTAMP WITH TIME ZONE
data type. It’s a variant ofTIMESTAMP
that includes of a time zone region name or time zone offset in its value.