Skip to main content

Crate velr

Crate velr 

Source
Expand description

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:

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.

§Schema migration and introspection

This runtime’s current on-disk schema is version 5. Supported older databases can be opened without automatic migration. Reads remain available on those databases, but writes and SHOW CURRENT GRAPH SHAPE require schema version 5 and return a query error until the user explicitly migrates.

Use Velr::schema_version, Velr::current_schema_version, and Velr::needs_migration to inspect the connection state. Use Velr::migrate or execute MIGRATE DATABASE from maintenance code when upgrading is intended.

SHOW CURRENT GRAPH SHAPE exposes Velr’s observed graph schema: labels, relationship types, properties, observed value types, and counts. Use YIELD to compose it with WHERE and RETURN, or YIELD * to inspect the full row shape.

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.
MigrationReport
Report returned by Velr::migrate.
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.
MigrationStatus
Status returned by Velr::migrate.

Type Aliases§

Result
Convenience result type used throughout the public API.