Crate oracle_rs

Crate oracle_rs 

Source
Expand description

§oracle-rs

A pure Rust driver for Oracle databases. No OCI or ODPI-C dependencies required.

This crate implements the Oracle TNS (Transparent Network Substrate) protocol entirely in Rust, enabling Oracle database connectivity without installing any Oracle client libraries.

§Features

  • Pure Rust - No Oracle client libraries required
  • Async/await - Built on Tokio for modern async applications
  • TLS/SSL - Secure connections with certificate and wallet support
  • Statement Caching - LRU cache for prepared statements
  • Comprehensive Type Support - Including LOBs, JSON, VECTORs, and more

§Quick Start

use oracle_rs::{Config, Connection};

#[tokio::main]
async fn main() -> oracle_rs::Result<()> {
    // Connect to Oracle
    let config = Config::new("localhost", 1521, "FREEPDB1", "user", "password");
    let conn = Connection::connect_with_config(config).await?;

    // Execute a query
    let result = conn.query("SELECT id, name FROM users", &[]).await?;

    for row in &result.rows {
        let id = row.get_i64(0).unwrap_or(0);
        let name = row.get_string(1).unwrap_or("");
        println!("User {}: {}", id, name);
    }

    Ok(())
}

§Connection Options

§Basic Connection

use oracle_rs::{Config, Connection};

let config = Config::new("hostname", 1521, "service_name", "username", "password");
let conn = Connection::connect_with_config(config).await?;

§TLS/SSL Connection

use oracle_rs::{Config, Connection};

let config = Config::new("hostname", 2484, "service_name", "username", "password")
    .with_tls()?;

let conn = Connection::connect_with_config(config).await?;

§Oracle Wallet

use oracle_rs::{Config, Connection};

let config = Config::new("hostname", 2484, "service_name", "username", "password")
    .with_wallet("/path/to/wallet", Some("wallet_password"))?;

let conn = Connection::connect_with_config(config).await?;

§Query Execution

§SELECT Queries

use oracle_rs::{Connection, Value};

// Simple query
let result = conn.query("SELECT * FROM employees", &[]).await?;

// With bind parameters
let result = conn.query(
    "SELECT * FROM employees WHERE department_id = :1 AND salary > :2",
    &[10.into(), 50000.0.into()]
).await?;

// Access rows
for row in &result.rows {
    let name = row.get_by_name("employee_name").and_then(|v| v.as_str()).unwrap_or("");
    let salary = row.get_by_name("salary").and_then(|v| v.as_f64()).unwrap_or(0.0);
}

§DML Operations

use oracle_rs::{Connection, Value};

// INSERT
let result = conn.execute(
    "INSERT INTO users (id, name) VALUES (:1, :2)",
    &[1.into(), "Alice".into()]
).await?;
println!("Rows inserted: {}", result.rows_affected);

// Commit the transaction
conn.commit().await?;

§Batch Operations

use oracle_rs::{Connection, BatchBuilder, Value};

let batch = BatchBuilder::new("INSERT INTO users (id, name) VALUES (:1, :2)")
    .add_row(vec![1.into(), "Alice".into()])
    .add_row(vec![2.into(), "Bob".into()])
    .add_row(vec![3.into(), "Charlie".into()])
    .build();

let result = conn.execute_batch(&batch).await?;
conn.commit().await?;

§Transactions

use oracle_rs::{Connection, Value};

// Auto-commit is off by default
conn.execute("INSERT INTO accounts (id, balance) VALUES (:1, :2)", &[1.into(), 100.0.into()]).await?;
conn.execute("UPDATE accounts SET balance = balance - :1 WHERE id = :2", &[50.0.into(), 1.into()]).await?;

// Commit the transaction
conn.commit().await?;

// Or rollback on error
// conn.rollback().await?;

// Savepoints
conn.savepoint("before_update").await?;
conn.execute("UPDATE accounts SET balance = 0 WHERE id = :1", &[1.into()]).await?;
conn.rollback_to_savepoint("before_update").await?;  // Undo the update

§Data Types

Oracle TypeRust Type
NUMBERi8, i16, i32, i64, f32, f64, String
VARCHAR2, CHARString, &str
DATEchrono::NaiveDateTime
TIMESTAMPchrono::NaiveDateTime
TIMESTAMP WITH TIME ZONEchrono::DateTime<FixedOffset>
RAWVec<u8>, &[u8]
CLOB, NCLOBString
BLOBVec<u8>
BOOLEANbool
JSONserde_json::Value
VECTORVec<f32>, Vec<f64>, Vec<i8>

§Connection Pooling

Use the companion deadpool-oracle crate for connection pooling.

§Minimum Oracle Version

Oracle Database 12c Release 1 (12.1) or later. Some features require newer versions:

  • Native BOOLEAN: Oracle 23c (emulated on earlier versions)
  • JSON type: Oracle 21c
  • VECTOR type: Oracle 23ai

Re-exports§

pub use batch::BatchBinds;
pub use batch::BatchBuilder;
pub use batch::BatchError;
pub use batch::BatchOptions;
pub use batch::BatchResult;
pub use capabilities::Capabilities;
pub use config::Config;
pub use config::TlsMode;
pub use connection::Connection;
pub use connection::ConnectionState;
pub use connection::PlsqlResult;
pub use connection::QueryOptions;
pub use connection::QueryResult;
pub use connection::ServerInfo;
pub use transport::Protocol;
pub use transport::TlsConfig;
pub use constants::FetchOrientation;
pub use cursor::ScrollableCursor;
pub use cursor::ScrollableCursorOptions;
pub use cursor::ScrollMode;
pub use cursor::ScrollResult;
pub use dbobject::CollectionType;
pub use dbobject::DbObject;
pub use dbobject::DbObjectAttr;
pub use dbobject::DbObjectType;
pub use drcp::DrcpOptions;
pub use drcp::DrcpSession;
pub use drcp::ReleaseMode;
pub use drcp::SessionPurity;
pub use error::Error;
pub use error::Result;
pub use implicit::ImplicitResult;
pub use implicit::ImplicitResults;
pub use row::Row;
pub use row::Value;
pub use row::RowDataDecoder;
pub use statement::Statement;
pub use statement::StatementType;
pub use statement::ColumnInfo;
pub use statement::BindInfo;
pub use statement::BindParam;
pub use statement_cache::StatementCache;
pub use constants::BindDirection;
pub use constants::OracleType;
pub use types::LobData;
pub use types::LobLocator;
pub use types::LobValue;
pub use types::OracleVector;
pub use types::OsonDecoder;
pub use types::OsonEncoder;
pub use types::RefCursor;
pub use types::SparseVector;
pub use types::VectorData;
pub use types::VectorFormat;
pub use serde_json;

Modules§

batch
Batch execution support for Oracle connections
buffer
Buffer abstractions for TNS protocol encoding/decoding
capabilities
Connection capabilities negotiation
config
Connection configuration and connection string parsing
connection
Oracle database connection
constants
TNS protocol constants
crypto
Cryptographic utilities for Oracle authentication
cursor
Scrollable cursor support for Oracle connections
dbobject
Oracle database object type support
drcp
Database Resident Connection Pooling (DRCP) support
error
Error types for the Oracle driver
implicit
Implicit results support for Oracle PL/SQL procedures
messages
TNS protocol messages
packet
TNS packet encoding/decoding
row
Row data handling for Oracle query results
statement
SQL Statement handling
statement_cache
Statement caching for improved performance
transport
Transport layer for Oracle connections
types
Oracle data type encoding and decoding