lora-ruby 0.6.0 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3a9450cc524f6ddb0431cab4516dcf68c064a8b6a489e9a920284976b07c624
-  data.tar.gz: 132681134206f3fc223cb2238079f2bbc691b201eaeca4771950fdc59788f72d
+  metadata.gz: b8997fb6d383285f5875b2fcd1df32e6299ece787a9c3fdc5bf48327ec68c543
+  data.tar.gz: 2c319c8b8585c5a66c13ed5c37a3fc28a77e2bb5422d62011389d62358cbefbe
 SHA512:
-  metadata.gz: e08270ea4b1946e2d86bd44ffc40860c12e3c8b1814a8aff02762934c0b0a836a2a4acfc01b2953082f07b863ff21836eb9f2ffb20872c3a8dcf972afd25c3c2
-  data.tar.gz: 604298f36756dd70d2ccce2072396db1b508b39a2c1413f2d3a660648be4131e011934314c9d1f260baa7a88be5b012f34feb2cbf318a2261176cde0eb19d39b
+  metadata.gz: d4a50e3ac27b694e2a7de3350f28d0d511c7578f4f96091ae797accc6c2a34195b68419605c1be44e3615cb7841ae204b85d97c73eaaf27fa7b746a9b3766464
+  data.tar.gz: b08fa81cc99b67eb037ae3fc51d48019d58b7609a6c2f404e9b662c1319bbd13f75d394f02039b8aa3780f0e52de47116aa4954bea3e4a521d4f9c25b74e3764

data/README.md

@@ -1,6 +1,6 @@
 # lora-ruby
 
-Ruby bindings for the [Lora](../../README.md) graph engine.
+Ruby bindings for the [Lora](../../../README.md) graph engine.
 Ships a native extension built with [Magnus](https://github.com/matsadler/magnus)
 on top of [`rb-sys`](https://github.com/oxidize-rb/rb-sys) so the Rust
 engine runs in-process — no separate server, no socket hop.
@@ -81,6 +81,8 @@ LoraRuby::Database.new(database_name = nil, options = nil)     # -> Database
 LoraRuby::Database.open_wal(wal_dir, options = nil)            # -> Database
 
 db.execute(query, params = nil)       # -> { "columns" => [...], "rows" => [...] }
+db.explain(query, params = nil)       # -> plan Hash; never executes
+db.profile(query, params = nil)       # -> { "plan" => ..., "metrics" => ... }; PROFILE executes writes
 db.clear                              # -> nil
 db.node_count                         # -> Integer
 db.relationship_count                 # -> Integer
@@ -102,6 +104,37 @@ Hash keys on the output are always **strings**, matching the `lora-node`,
 symbol or string keys — both work for param names and for tagged
 constructor Hashes like `point`/`date`/...
 
+### Explain & Profile
+
+`db.explain` and `db.profile` are first-class methods alongside
+`db.execute`. They are intentionally *separate calls*, not a flag on
+`execute`, so plan inspection and runtime metrics must be requested
+explicitly.
+
+```ruby
+plan = db.explain(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { "name" => "Alice" }
+)
+plan["shape"]           # => "readOnly"
+plan["tree"]["operator"]
+
+profile = db.profile(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { "name" => "Alice" }
+)
+profile["metrics"]["total_elapsed_ns"]
+profile["metrics"]["per_operator"]   # per-step inclusive timing
+```
+
+`explain` never invokes the executor — calling it on a mutating query
+(`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile` executes the query for real.** Mutating queries are
+> persisted exactly as in `execute`. Use `explain` to inspect a
+> mutating plan without running it.
+
 ## Typed value model
 
 Identical contract to the other bindings:
@@ -174,9 +207,8 @@ db = LoraRuby::Database.open_wal(
 ## Concurrency (GVL release)
 
 `Database#execute` calls `rb_thread_call_without_gvl`, so other Ruby
-threads run while the engine is busy. Concurrent queries against the
-same `Database` serialise on an internal `Mutex`; parallel queries
-against **different** `Database` instances have no shared state.
+threads run while the engine is busy. Auto-commit reads can overlap on engine
+snapshots; write commits and explicit read-write transactions serialize.
 
 The engine has no cancellation hook, so we pass a `NULL` unblock
 function. A thread interrupted mid-query (`Thread#kill`) will observe
@@ -186,7 +218,7 @@ if you rely on cooperative cancellation.
 ## Local development
 
 ```bash
-cd crates/lora-ruby
+cd crates/bindings/lora-ruby
 bundle install
 bundle exec rake compile        # cargo build → lib/lora_ruby/lora_ruby.<ext>
 bundle exec rake test           # minitest
@@ -201,7 +233,7 @@ precompiled platform gem.
 
 ```
 lora-database (Rust, embedded)
-   └── crates/lora-ruby/                (gem root + cargo crate)
+   └── crates/bindings/lora-ruby/                (gem root + cargo crate)
           ├── Cargo.toml                 Rust workspace member
           ├── extconf.rb                 rb-sys / mkmf entry point
           ├── src/lib.rs                 <- Magnus / rb-sys bindings

data/extconf.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # rb-sys provides a drop-in replacement for `create_makefile` that shells
-# out to cargo to build the `cdylib` declared in ../../Cargo.toml. The
+# out to cargo to build the `cdylib` declared in ../../../Cargo.toml. The
 # path it writes the native library to is determined by the argument —
 # `lora_ruby/lora_ruby` places the final artefact at
 # `lib/lora_ruby/lora_ruby.{so,bundle,dll}`, which is what

data/lib/lora_ruby/version.rb

@@ -10,5 +10,5 @@ module LoraRuby
   # Guard against redefinition so re-requiring this file (or loading
   # both paths) doesn't emit a "warning: already initialized constant"
   # when the native extension loads second with the identical value.
-  VERSION = "0.6.0" unless const_defined?(:VERSION)
+  VERSION = "0.8.4" unless const_defined?(:VERSION)
 end

data/src/errors.rs

@@ -0,0 +1,74 @@
+//! Lookup helpers for the `LoraRuby::Error` exception hierarchy.
+//!
+//! The exception classes themselves are registered in `lib.rs::init` so
+//! Ruby owns their lifetime; these helpers re-find them by name when a
+//! method needs to raise. `unwrap_or_else(|_| ruby.exception_standard_error())`
+//! keeps us safe even if a constant is shadowed at runtime — we still
+//! raise *something* descended from `StandardError`.
+
+use lora_database::{LoraError, LoraErrorCode};
+use magnus::{prelude::*, Error as MagnusError, ExceptionClass, RModule, Ruby};
+
+pub(crate) fn lora_module(ruby: &Ruby) -> RModule {
+    ruby.class_object()
+        .const_get::<_, RModule>("LoraRuby")
+        .expect("LoraRuby module is defined by `init` before any method runs")
+}
+
+pub(crate) fn lora_error_class(ruby: &Ruby, name: &str) -> ExceptionClass {
+    // `const_get::<_, ExceptionClass>` converts the stored RClass into
+    // an ExceptionClass — this is the sound path, because our subclasses
+    // of StandardError retain the exception-class trait on the Ruby
+    // side even though `define_class` typed them as RClass.
+    lora_module(ruby)
+        .const_get::<_, ExceptionClass>(name)
+        .unwrap_or_else(|_| ruby.exception_standard_error())
+}
+
+/// Raise a `LoraRuby::QueryError`, prefixing the message with the
+/// precise wire code from [`LoraErrorCode`] so Ruby callers can route
+/// past the exception class via `e.message.split(': ', 2)`.
+pub(crate) fn query_error(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
+    let raw: String = msg.into();
+    let body = if has_code_prefix(&raw) {
+        raw
+    } else {
+        format!("{}: {raw}", LoraErrorCode::Internal.as_str())
+    };
+    MagnusError::new(lora_error_class(ruby, "QueryError"), body)
+}
+
+/// Raise a `LoraRuby::InvalidParamsError`, prefixed with
+/// `LORA_INVALID_PARAMS:` so callers can route uniformly with the
+/// other bindings.
+pub(crate) fn invalid_params(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
+    let raw: String = msg.into();
+    let body = if has_code_prefix(&raw) {
+        raw
+    } else {
+        format!("{}: {raw}", LoraErrorCode::InvalidParams.as_str())
+    };
+    MagnusError::new(lora_error_class(ruby, "InvalidParamsError"), body)
+}
+
+/// Build a `LoraRuby::QueryError` from any error convertible into
+/// [`LoraError`]. Accepts both the engine's typed `LoraError` and the
+/// binding-internal `anyhow::Error` (via `From<anyhow::Error>`), so
+/// query and admin paths share one helper.
+#[allow(dead_code)]
+pub(crate) fn query_error_from_anyhow(ruby: &Ruby, err: impl Into<LoraError>) -> MagnusError {
+    let lora = err.into();
+    let body = format!("{}: {}", lora.code().as_str(), lora.message());
+    MagnusError::new(lora_error_class(ruby, "QueryError"), body)
+}
+
+fn has_code_prefix(s: &str) -> bool {
+    // Detect `LORA_<UPPER_SNAKE>:` so callers that already produced a
+    // coded message (e.g. by passing through `query_error_from_anyhow`)
+    // are not double-prefixed.
+    let Some(colon) = s.find(':') else {
+        return false;
+    };
+    let head = &s[..colon];
+    head.starts_with("LORA_") && head.bytes().all(|b| b.is_ascii_uppercase() || b == b'_')
+}

data/src/from_ruby.rs

@@ -0,0 +1,419 @@
+//! Ruby → `LoraValue` conversion (params and snapshot-option JSON).
+//!
+//! Inverse of [`crate::to_ruby`]. Tagged hashes (`{"kind" => "date", …}`)
+//! become temporal/spatial values; plain hashes become `LoraValue::Map`.
+//! Symbol keys and string keys are accepted interchangeably.
+
+use std::collections::BTreeMap;
+
+use magnus::{
+    prelude::*, r_hash::ForEach, value::ReprValue, Error as MagnusError, Float, Integer, RArray,
+    RHash, RString, Ruby, Symbol, Value,
+};
+
+use lora_database::LoraValue;
+use lora_store::{
+    LoraBinary, LoraDate, LoraDateTime, LoraDuration, LoraLocalDateTime, LoraLocalTime, LoraPoint,
+    LoraTime, LoraVector, RawCoordinate, VectorCoordinateType,
+};
+
+use crate::errors::invalid_params;
+
+pub(crate) fn ruby_value_to_params(
+    ruby: &Ruby,
+    value: Value,
+) -> Result<BTreeMap<String, LoraValue>, MagnusError> {
+    let hash = RHash::try_convert(value)
+        .map_err(|_| invalid_params(ruby, "params must be a Hash keyed by parameter name"))?;
+    hash_to_string_map(ruby, hash)
+}
+
+fn hash_to_string_map(
+    ruby: &Ruby,
+    hash: RHash,
+) -> Result<BTreeMap<String, LoraValue>, MagnusError> {
+    let mut out = BTreeMap::new();
+    let mut inner_err: Option<MagnusError> = None;
+    hash.foreach(|k: Value, v: Value| {
+        let key = match coerce_key(ruby, k) {
+            Ok(s) => s,
+            Err(e) => {
+                inner_err = Some(e);
+                return Ok(ForEach::Stop);
+            }
+        };
+        match ruby_value_to_lora(ruby, v) {
+            Ok(lv) => {
+                out.insert(key, lv);
+                Ok(ForEach::Continue)
+            }
+            Err(e) => {
+                inner_err = Some(e);
+                Ok(ForEach::Stop)
+            }
+        }
+    })?;
+    if let Some(e) = inner_err {
+        return Err(e);
+    }
+    Ok(out)
+}
+
+fn coerce_key(ruby: &Ruby, v: Value) -> Result<String, MagnusError> {
+    // Accept both String and Symbol keys — idiomatic Ruby. Reject anything
+    // else loudly; silently stringifying would mask caller mistakes.
+    if let Ok(s) = RString::try_convert(v) {
+        return s.to_string();
+    }
+    if let Ok(s) = Symbol::try_convert(v) {
+        return Ok(s.name()?.into_owned());
+    }
+    Err(invalid_params(ruby, "param keys must be String or Symbol"))
+}
+
+pub(crate) fn ruby_optional_to_json(
+    ruby: &Ruby,
+    value: Value,
+) -> Result<Option<serde_json::Value>, MagnusError> {
+    if value.is_nil() {
+        Ok(None)
+    } else {
+        ruby_value_to_json(ruby, value).map(Some)
+    }
+}
+
+fn ruby_value_to_json(ruby: &Ruby, value: Value) -> Result<serde_json::Value, MagnusError> {
+    if value.is_nil() {
+        return Ok(serde_json::Value::Null);
+    }
+    if value.is_kind_of(ruby.class_true_class()) {
+        return Ok(serde_json::Value::Bool(true));
+    }
+    if value.is_kind_of(ruby.class_false_class()) {
+        return Ok(serde_json::Value::Bool(false));
+    }
+    if let Ok(i) = Integer::try_convert(value) {
+        let n = i
+            .to_i64()
+            .map_err(|_| invalid_params(ruby, "snapshot option integer does not fit in i64"))?;
+        return Ok(serde_json::Value::Number(n.into()));
+    }
+    if let Ok(f) = Float::try_convert(value) {
+        let Some(number) = serde_json::Number::from_f64(f.to_f64()) else {
+            return Err(invalid_params(ruby, "snapshot option float must be finite"));
+        };
+        return Ok(serde_json::Value::Number(number));
+    }
+    if let Ok(s) = RString::try_convert(value) {
+        return Ok(serde_json::Value::String(s.to_string()?));
+    }
+    if let Ok(sym) = Symbol::try_convert(value) {
+        return Ok(serde_json::Value::String(sym.name()?.into_owned()));
+    }
+    if let Ok(arr) = RArray::try_convert(value) {
+        let mut out = Vec::with_capacity(arr.len());
+        for item in arr.into_iter() {
+            out.push(ruby_value_to_json(ruby, item)?);
+        }
+        return Ok(serde_json::Value::Array(out));
+    }
+    if let Ok(hash) = RHash::try_convert(value) {
+        let mut out = serde_json::Map::new();
+        let mut error = None;
+        hash.foreach(|k: Value, v: Value| {
+            let key = match coerce_key(ruby, k) {
+                Ok(key) => key,
+                Err(e) => {
+                    error = Some(e);
+                    return Ok(ForEach::Stop);
+                }
+            };
+            let json = match ruby_value_to_json(ruby, v) {
+                Ok(json) => json,
+                Err(e) => {
+                    error = Some(e);
+                    return Ok(ForEach::Stop);
+                }
+            };
+            out.insert(key, json);
+            Ok(ForEach::Continue)
+        })?;
+        if let Some(error) = error {
+            return Err(error);
+        }
+        return Ok(serde_json::Value::Object(out));
+    }
+
+    let class_name = unsafe { value.classname() }.into_owned();
+    Err(invalid_params(
+        ruby,
+        format!("unsupported snapshot option type: {class_name}"),
+    ))
+}
+
+fn ruby_value_to_lora(ruby: &Ruby, v: Value) -> Result<LoraValue, MagnusError> {
+    if v.is_nil() {
+        return Ok(LoraValue::Null);
+    }
+    // Check true/false before Integer — Ruby's TrueClass / FalseClass are
+    // not Integer subclasses, but bool detection is cleaner first.
+    if v.is_kind_of(ruby.class_true_class()) {
+        return Ok(LoraValue::Bool(true));
+    }
+    if v.is_kind_of(ruby.class_false_class()) {
+        return Ok(LoraValue::Bool(false));
+    }
+    // Float MUST be checked before Integer — `Integer::try_convert`
+    // succeeds on Float because Ruby's `Float#to_int` (truncating
+    // coercion) makes `Float` implicitly convertible. Taking that path
+    // would turn `1.5` into `1` silently; callers never want that.
+    if let Ok(f) = Float::try_convert(v) {
+        return Ok(LoraValue::Float(f.to_f64()));
+    }
+    if let Ok(i) = Integer::try_convert(v) {
+        return match i.to_i64() {
+            Ok(n) => Ok(LoraValue::Int(n)),
+            Err(_) => Err(invalid_params(
+                ruby,
+                "integer parameter does not fit in i64",
+            )),
+        };
+    }
+    if let Ok(s) = RString::try_convert(v) {
+        return Ok(LoraValue::String(s.to_string()?));
+    }
+    if let Ok(sym) = Symbol::try_convert(v) {
+        // Symbols round-trip as strings — same approach as YAML/JSON
+        // mappings. Engine has no dedicated symbol value.
+        return Ok(LoraValue::String(sym.name()?.into_owned()));
+    }
+    if let Ok(arr) = RArray::try_convert(v) {
+        let mut out = Vec::with_capacity(arr.len());
+        for item in arr.into_iter() {
+            out.push(ruby_value_to_lora(ruby, item)?);
+        }
+        return Ok(LoraValue::List(out));
+    }
+    if let Ok(hash) = RHash::try_convert(v) {
+        return ruby_hash_to_cypher(ruby, hash);
+    }
+    let class_name = unsafe { v.classname() }.into_owned();
+    Err(invalid_params(
+        ruby,
+        format!("unsupported parameter type: {class_name}"),
+    ))
+}
+
+/// A Hash might be a tagged value (date / time / …/ point) or a plain
+/// map. Nodes / relationships / paths are opaque on the engine side and
+/// cannot be reconstructed as params — there's no `"kind" => "node"`
+/// tag handled here.
+fn ruby_hash_to_cypher(ruby: &Ruby, hash: RHash) -> Result<LoraValue, MagnusError> {
+    if let Some(kind) = lookup_kind(ruby, hash)? {
+        match kind.as_str() {
+            "date" => {
+                return parse_tagged(ruby, hash, "date", |iso| {
+                    LoraDate::parse(iso).map(LoraValue::Date)
+                });
+            }
+            "time" => {
+                return parse_tagged(ruby, hash, "time", |iso| {
+                    LoraTime::parse(iso).map(LoraValue::Time)
+                });
+            }
+            "localtime" => {
+                return parse_tagged(ruby, hash, "localtime", |iso| {
+                    LoraLocalTime::parse(iso).map(LoraValue::LocalTime)
+                });
+            }
+            "datetime" => {
+                return parse_tagged(ruby, hash, "datetime", |iso| {
+                    LoraDateTime::parse(iso).map(LoraValue::DateTime)
+                });
+            }
+            "localdatetime" => {
+                return parse_tagged(ruby, hash, "localdatetime", |iso| {
+                    LoraLocalDateTime::parse(iso).map(LoraValue::LocalDateTime)
+                });
+            }
+            "duration" => {
+                return parse_tagged(ruby, hash, "duration", |iso| {
+                    LoraDuration::parse(iso).map(LoraValue::Duration)
+                });
+            }
+            "point" => return build_point(ruby, hash),
+            "vector" => return build_vector(ruby, hash),
+            "binary" | "blob" => return build_binary(ruby, hash),
+            _ => { /* fall through to plain-map handling */ }
+        }
+    }
+
+    Ok(LoraValue::Map(hash_to_string_map(ruby, hash)?))
+}
+
+/// Look up `"kind"` (string) or `:kind` (symbol) under either key. Keeps
+/// constructor hashes usable with either Ruby idiom.
+fn lookup_kind(ruby: &Ruby, hash: RHash) -> Result<Option<String>, MagnusError> {
+    if let Some(v) = hash.get(ruby.str_new("kind")) {
+        return kind_as_string(v).map(Some);
+    }
+    if let Some(v) = hash.get(ruby.to_symbol("kind")) {
+        return kind_as_string(v).map(Some);
+    }
+    Ok(None)
+}
+
+fn kind_as_string(v: Value) -> Result<String, MagnusError> {
+    if let Ok(s) = RString::try_convert(v) {
+        return s.to_string();
+    }
+    if let Ok(s) = Symbol::try_convert(v) {
+        return Ok(s.name()?.into_owned());
+    }
+    // Anything else means "not a tagged constructor" — return empty so
+    // the caller falls through to plain-map handling instead of raising.
+    Ok(String::new())
+}
+
+fn parse_tagged(
+    ruby: &Ruby,
+    hash: RHash,
+    tag: &str,
+    parse: impl FnOnce(&str) -> Result<LoraValue, String>,
+) -> Result<LoraValue, MagnusError> {
+    let iso = read_string(ruby, hash, "iso")?
+        .ok_or_else(|| invalid_params(ruby, format!("{tag} value requires iso: String")))?;
+    parse(&iso).map_err(|e| invalid_params(ruby, format!("{tag}: {e}")))
+}
+
+fn build_point(ruby: &Ruby, hash: RHash) -> Result<LoraValue, MagnusError> {
+    let srid = read_u32(ruby, hash, "srid")?.unwrap_or(7203);
+    let x = read_f64(ruby, hash, "x")?.ok_or_else(|| invalid_params(ruby, "point.x required"))?;
+    let y = read_f64(ruby, hash, "y")?.ok_or_else(|| invalid_params(ruby, "point.y required"))?;
+    let z = read_f64(ruby, hash, "z")?;
+    Ok(LoraValue::Point(LoraPoint { x, y, z, srid }))
+}
+
+fn build_vector(ruby: &Ruby, hash: RHash) -> Result<LoraValue, MagnusError> {
+    let dimension = read_i64(ruby, hash, "dimension")?
+        .ok_or_else(|| invalid_params(ruby, "vector.dimension required"))?;
+    let coordinate_type_name = read_string(ruby, hash, "coordinateType")?
+        .ok_or_else(|| invalid_params(ruby, "vector.coordinateType required"))?;
+    let coordinate_type = VectorCoordinateType::parse(&coordinate_type_name).ok_or_else(|| {
+        invalid_params(
+            ruby,
+            format!("unknown vector coordinate type `{coordinate_type_name}`"),
+        )
+    })?;
+    let values_value = hash_get_either(ruby, hash, "values")
+        .ok_or_else(|| invalid_params(ruby, "vector.values required"))?;
+    let arr = RArray::try_convert(values_value)
+        .map_err(|_| invalid_params(ruby, "vector.values must be an Array"))?;
+
+    let mut raw = Vec::with_capacity(arr.len());
+    for item in arr.into_iter() {
+        if item.is_kind_of(ruby.class_true_class()) || item.is_kind_of(ruby.class_false_class()) {
+            return Err(invalid_params(
+                ruby,
+                "vector.values entries must be numeric",
+            ));
+        }
+        if let Ok(f) = Float::try_convert(item) {
+            let v = f.to_f64();
+            if !v.is_finite() {
+                return Err(invalid_params(
+                    ruby,
+                    "vector.values cannot be NaN or Infinity",
+                ));
+            }
+            raw.push(RawCoordinate::Float(v));
+            continue;
+        }
+        if let Ok(i) = Integer::try_convert(item) {
+            raw.push(RawCoordinate::Int(i.to_i64()?));
+            continue;
+        }
+        return Err(invalid_params(
+            ruby,
+            "vector.values entries must be numeric",
+        ));
+    }
+
+    let v = LoraVector::try_new(raw, dimension, coordinate_type)
+        .map_err(|e| invalid_params(ruby, e.to_string()))?;
+    Ok(LoraValue::Vector(v))
+}
+
+fn build_binary(ruby: &Ruby, hash: RHash) -> Result<LoraValue, MagnusError> {
+    let segments_value = hash_get_either(ruby, hash, "segments")
+        .ok_or_else(|| invalid_params(ruby, "binary.segments required"))?;
+    let arr = RArray::try_convert(segments_value)
+        .map_err(|_| invalid_params(ruby, "binary.segments must be an Array"))?;
+    let mut segments = Vec::with_capacity(arr.len());
+    for item in arr.into_iter() {
+        let segment = RString::try_convert(item)
+            .map_err(|_| invalid_params(ruby, "binary.segments entries must be Strings"))?;
+        segments.push(unsafe { segment.as_slice().to_vec() });
+    }
+    Ok(LoraValue::Binary(LoraBinary::from_segments(segments)))
+}
+
+fn read_i64(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<i64>, MagnusError> {
+    let Some(v) = hash_get_either(ruby, hash, key) else {
+        return Ok(None);
+    };
+    Ok(Some(Integer::try_convert(v)?.to_i64().map_err(|_| {
+        invalid_params(ruby, format!("{key} out of i64 range"))
+    })?))
+}
+
+// ---- Hash accessors that accept either string or symbol keys ------------
+
+pub(crate) fn hash_get_either(ruby: &Ruby, hash: RHash, key: &str) -> Option<Value> {
+    if let Some(v) = hash.get(ruby.str_new(key)) {
+        return Some(v);
+    }
+    hash.get(ruby.to_symbol(key))
+}
+
+pub(crate) fn hash_get_any(ruby: &Ruby, hash: RHash, keys: &[&str]) -> Option<Value> {
+    keys.iter().find_map(|key| hash_get_either(ruby, hash, key))
+}
+
+pub(crate) fn read_nonnegative_u64(ruby: &Ruby, value: Value) -> Result<u64, MagnusError> {
+    let n = Integer::try_convert(value)?.to_i64()?;
+    u64::try_from(n).map_err(|_| invalid_params(ruby, "option integer must be non-negative"))
+}
+
+fn read_string(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<String>, MagnusError> {
+    let Some(v) = hash_get_either(ruby, hash, key) else {
+        return Ok(None);
+    };
+    let s = RString::try_convert(v)?.to_string()?;
+    Ok(Some(s))
+}
+
+fn read_u32(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<u32>, MagnusError> {
+    let Some(v) = hash_get_either(ruby, hash, key) else {
+        return Ok(None);
+    };
+    let n = Integer::try_convert(v)?.to_i64()?;
+    u32::try_from(n)
+        .map(Some)
+        .map_err(|_| invalid_params(ruby, "srid out of u32 range"))
+}
+
+fn read_f64(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<f64>, MagnusError> {
+    let Some(v) = hash_get_either(ruby, hash, key) else {
+        return Ok(None);
+    };
+    // Accept either Float or Integer — `cartesian(1, 2)` passing ints
+    // shouldn't force the caller to call `.to_f` first.
+    if let Ok(f) = Float::try_convert(v) {
+        return Ok(Some(f.to_f64()));
+    }
+    if let Ok(i) = Integer::try_convert(v) {
+        return Ok(Some(i.to_i64()? as f64));
+    }
+    Ok(None)
+}

data/src/gvl.rs

@@ -0,0 +1,55 @@
+//! Global VM Lock release primitive.
+
+use std::ffi::c_void;
+use std::mem::MaybeUninit;
+
+/// Run `f` with Ruby's Global VM Lock released.
+///
+/// Semantics match `rb_thread_call_without_gvl` — other Ruby threads can
+/// progress while `f` runs. The closure MUST NOT touch Ruby state (no
+/// `Value`s, no allocations into the Ruby heap), which we arrange by
+/// keeping all such work on the calling thread. Everything inside
+/// `database_execute`'s closure is pure Rust on pre-extracted data, so
+/// this is sound.
+pub(crate) fn without_gvl<F, R>(f: F) -> R
+where
+    F: FnOnce() -> R,
+    F: Send,
+    R: Send,
+{
+    struct Data<F, R> {
+        func: Option<F>,
+        result: MaybeUninit<R>,
+    }
+
+    unsafe extern "C" fn trampoline<F, R>(data: *mut c_void) -> *mut c_void
+    where
+        F: FnOnce() -> R,
+    {
+        let data = &mut *(data as *mut Data<F, R>);
+        let f = data
+            .func
+            .take()
+            .expect("without_gvl: closure already taken");
+        data.result.write(f());
+        std::ptr::null_mut()
+    }
+
+    let mut data = Data::<F, R> {
+        func: Some(f),
+        result: MaybeUninit::uninit(),
+    };
+
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl(
+            Some(trampoline::<F, R>),
+            &mut data as *mut _ as *mut c_void,
+            // No unblock function — the engine doesn't implement
+            // cooperative cancellation, and a forced longjmp out of a
+            // mutex-holding section would be worse than waiting.
+            None,
+            std::ptr::null_mut(),
+        );
+        data.result.assume_init()
+    }
+}