rhei-core 2.0.0

//! [`OltpEngine`] trait — transactional SQL execution.
//!
//! The production implementation lives in `rhei-oltp-rusqlite` and wraps
//! Rusqlite via a per-connection OS thread + crossbeam channel pattern.

use arrow::record_batch::RecordBatch;

/// Abstraction over the OLTP (transactional) engine.
///
/// Currently backed by Rusqlite (`rhei-oltp-rusqlite`). The trait is designed
/// so that alternative OLTP backends can be plugged in without changing the
/// rest of the codebase.
///
/// # Contract for implementors
///
/// - `execute_batch` must be atomic: if any statement fails the entire batch
///   is rolled back and no partial writes are visible.
/// - All methods must be `Send` and callable from async contexts.
pub trait OltpEngine: Send + Sync {
    /// Engine-specific error type returned by all fallible methods.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Execute a SELECT query and return results as Arrow [`RecordBatch`]es.
    ///
    /// `params` are JSON-typed positional parameters bound to `?` placeholders
    /// in the SQL string.
    ///
    /// # Errors
    ///
    /// Returns `Err(Self::Error)` on SQL parse failure, a missing table, or
    /// parameter binding failure.
    fn query(
        &self,
        sql: &str,
        params: &[serde_json::Value],
    ) -> impl std::future::Future<Output = Result<Vec<RecordBatch>, Self::Error>> + Send;

    /// Execute an INSERT, UPDATE, DELETE, or DDL statement.
    ///
    /// Returns the number of rows affected. `params` are JSON-typed positional
    /// parameters bound to `?` placeholders.
    ///
    /// # Errors
    ///
    /// Returns `Err(Self::Error)` on SQL parse failure, constraint violation,
    /// or parameter binding failure.
    fn execute(
        &self,
        sql: &str,
        params: &[serde_json::Value],
    ) -> impl std::future::Future<Output = Result<u64, Self::Error>> + Send;

    /// Execute a batch of statements atomically inside a single transaction.
    ///
    /// Each element of `statements` is a `(sql, params)` pair. If any
    /// statement fails the whole transaction is rolled back and an error is
    /// returned. On success every statement has been committed.
    ///
    /// # Errors
    ///
    /// Returns `Err(Self::Error)` on the first failing statement; all prior
    /// changes within the transaction are rolled back.
    fn execute_batch(
        &self,
        statements: &[(String, Vec<serde_json::Value>)],
    ) -> impl std::future::Future<Output = Result<(), Self::Error>> + Send;

    /// Return `true` if `table_name` exists in the OLTP catalog.
    ///
    /// # Errors
    ///
    /// Returns `Err(Self::Error)` if the catalog query fails.
    fn table_exists(
        &self,
        table_name: &str,
    ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send;
}