Struct SqlEngine 

pub struct SqlEngine { /* private fields */ }

Implementations

impl SqlEngine

pub fn new<Pg>(pager: Arc<Pg>) -> Self

where Pg: Pager<Blob = EntryHandle> + Send + Sync + 'static,

Construct a new engine backed by the provided pager with insert buffering disabled.

Callers that intend to stream large amounts of literal INSERT ... VALUES input can enable batching later using SqlEngine::set_insert_buffering.

pub fn with_context( context: Arc<RuntimeContext<BoxedPager>>, default_nulls_first: bool, ) -> Self

pub fn set_insert_buffering(&self, enabled: bool) -> SqlResult<()>

Toggle literal INSERT buffering for the engine.

When enabled, consecutive INSERT ... VALUES statements that target the same table and column list are accumulated and flushed together, dramatically lowering planning and execution overhead for workloads that stream tens of thousands of literal inserts. Disabling buffering reverts to SQLite-style immediate execution and is appropriate for unit tests or workloads that rely on per-statement side effects (errors, triggers, constraint violations) happening synchronously.

Calling this method with false forces any pending batched rows to flush before returning, guaranteeing that subsequent reads observe the latest state.

pub fn session(&self) -> &RuntimeSession

Get a reference to the underlying session (for advanced use like error handling in test harnesses).

pub fn execute( &self, sql: &str, ) -> SqlResult<Vec<RuntimeStatementResult<BoxedPager>>>

Execute one or more SQL statements and return their raw RuntimeStatementResults.

This method is the general-purpose entry point for running SQL against the engine when you need to mix statement types (e.g. CREATE TABLE, INSERT, UPDATE, SELECT) or when you care about per-statement status information. Statements are executed in the order they appear in the input string, and the results vector mirrors that ordering.

For ad-hoc read queries where you only care about the resulting Arrow RecordBatches, prefer SqlEngine::sql, which enforces a single SELECT statement and collects its output for you. execute remains the right tool for schema migrations, transactional scripts, or workflows that need to inspect the specific runtime response for each statement.

pub fn flush_pending_inserts( &self, ) -> SqlResult<Vec<RuntimeStatementResult<BoxedPager>>>

Flush any buffered literal INSERT statements and return their per-statement results.

Workloads that stream many INSERT statements without interleaving reads can invoke this to force persistence without waiting for the next non-INSERT statement or the engine drop hook.

pub fn prepare(&self, sql: &str) -> SqlResult<PreparedStatement>

Prepare a single SQL statement for repeated execution.

Prepared statements currently support UPDATE queries with positional or named parameters. Callers must provide parameter bindings when executing the returned handle.

pub fn execute_prepared( &self, statement: &PreparedStatement, params: &[SqlParamValue], ) -> SqlResult<Vec<RuntimeStatementResult<BoxedPager>>>

Execute a previously prepared statement with the supplied parameters.

pub fn sql(&self, sql: &str) -> SqlResult<Vec<RecordBatch>>

Execute a single SELECT statement and return its results as Arrow RecordBatches.

The SQL passed to this method must contain exactly one statement, and that statement must be a SELECT. Statements that modify data (e.g. INSERT) should be executed up front using SqlEngine::execute before calling this helper.

Examples

use std::sync::Arc;

use arrow::array::StringArray;
use llkv_sql::SqlEngine;
use llkv_storage::pager::MemPager;

let engine = SqlEngine::new(Arc::new(MemPager::default()));
let _ = engine
    .execute(
        "CREATE TABLE users (id INT PRIMARY KEY, name TEXT);\n         \
         INSERT INTO users (id, name) VALUES (1, 'Ada');",
    )
    .unwrap();

let batches = engine.sql("SELECT id, name FROM users ORDER BY id;").unwrap();
assert_eq!(batches.len(), 1);

let batch = &batches[0];
assert_eq!(batch.num_rows(), 1);

let names = batch
    .column(1)
    .as_any()
    .downcast_ref::<StringArray>()
    .unwrap();
assert_eq!(names.value(0), "Ada");

Trait Implementations

impl Clone for SqlEngine

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Drop for SqlEngine

fn drop(&mut self)

Executes the destructor for this type.