Crate velr 

Rust bindings for the Velr runtime.

This crate exposes a high-level API over the Velr runtime ABI (loaded via the runtime module), wrapping raw FFI pointers in RAII types with predictable lifetimes.

Threading model

Velr uses a connection-affine model:

1. Velr (the connection) is Send + !Sync.

   • ✅ You may move a connection to another thread. Example: spawn a worker thread and move the connection into it.
   • ❌ Wrapping a connection in Arc does not make it safe to share across threads; Velr is !Sync, so concurrent shared use is not supported.

2. In-flight / handle-based objects are !Send + !Sync (thread-affine): ExecTables, TableResult, RowIter, VelrTx, ExecTablesTx, VelrSavepoint, ExplainTrace.

   • ❌ You may not move these to another thread.
   • ❌ You may not share these across threads.

Practical implications:

• ✅ Many connections across many threads is fine (open one connection per thread).
• ✅ You can move a connection between threads (e.g., create in main, move into worker).
• ❌ You cannot run concurrent operations on the same connection across threads.

If you need parallelism, open multiple connections and/or use a pool.

Results and lifetimes

Queries can produce zero or more result tables:

• Velr::exec / VelrTx::exec stream tables via ExecTables / ExecTablesTx.
• Velr::exec_one / VelrTx::exec_one return a single TableResult.

Rows are processed via callbacks. Individual cell values are represented by CellRef, which may borrow bytes from buffers owned by the underlying row cursor. For Text/Json values, the borrowed bytes remain valid until the next call to RowIter::next on the same iterator (or until the iterator is dropped). In typical usage this means the borrows are scoped to the row callback invocation.

Errors

Most operations return Result<T>. On failure, you get an Error containing a numeric code (originating from the runtime ABI) and an optional message.

Structs

Error

Error returned by the Velr API.

ExecTables

Streaming result of an execution that may yield multiple tables.

ExecTablesTx

Streaming result of an execution within a transaction.

ExplainPlan

One explain plan plus all steps in it.

ExplainPlanMeta

Owned plan metadata returned from an ExplainTrace.

ExplainStatement

One explain statement plus its SQLite query-plan detail lines.

ExplainStatementMeta

Owned statement metadata returned from an ExplainTrace.

ExplainStep

One explain step plus all statements in it.

ExplainStepMeta

Owned step metadata returned from an ExplainTrace.

ExplainTrace

EXPLAIN / EXPLAIN ANALYZE trace handle.

RowIter

Iterator over rows of a table.

TableResult

A single result table produced by query execution.

Velr

VelrSavepoint

A scoped savepoint handle within a transaction (thread-affine).

VelrTx

A transaction handle (thread-affine).

Enums

CellRef

Borrowed view of a single cell value in a result row.

Type Aliases

Result

Convenience result type used throughout the public API.