feat(sdk): Phase 11.7 SDK propagation of Busy / BusySnapshot (SQLR-22)

[joaoh82]

Summary

Surfaces retryable engine errors through the C FFI and every language SDK so Python / Node / Go callers can actually write BEGIN CONCURRENT retry loops with idiomatic per-language patterns. Picked ahead of plan-doc 11.5 (checkpoint integration) for the same reason 11.5 / 11.6 jumped the queue — durability already works through the legacy save_database mirror, but SDK users hitting BEGIN CONCURRENT had no way to distinguish retryable errors from real failures.

Plan-doc 11.8 ("SDK + REPL propagation") split into two: FFI/SDK error propagation ships here as roadmap 11.7; multi-handle SDK shape + REPL .spawn → roadmap 11.10.

What ships

C FFI (sqlrite-ffi/src/lib.rs)

• SqlriteStatus::Busy = 5 + SqlriteStatus::BusySnapshot = 6 codes
• SqlriteStatus::is_retryable() covers both
• New internal status_of_sqlrite mapper inspects the engine's SQLRiteError variant and routes to the dedicated codes; the generic status_of keeps mapping every error to Error for non-engine results
• sqlrite_execute switched to the engine-aware mapper
• Header regenerated via build.rs

Python SDK (sdk/python/src/lib.rs)

• sqlrite.BusyError and sqlrite.BusySnapshotError pyo3 exception classes, both inheriting from sqlrite.SQLRiteError
• New map_engine_err helper raises the matching exception based on the engine variant
• All engine-typed call sites (open / execute / prepare / query / rows.next) routed through it
• Existing except sqlrite.SQLRiteError blocks still catch both

while True:
    try:
        conn.execute("BEGIN CONCURRENT")
        conn.execute("UPDATE accounts SET balance = balance - 50 WHERE id = 1")
        conn.execute("COMMIT")
        break
    except sqlrite.BusyError:
        continue

Node.js SDK (sdk/nodejs/src/lib.rs)

• Exported ErrorKind string enum ('Busy' | 'BusySnapshot' | 'Other')
• Exported errorKind(message: string) classifier — regex-matches the engine's thiserror prefix ('Busy: ' / 'BusySnapshot: ')
• Longest-prefix-first ordering so BusySnapshot doesn't mis-classify as Busy

const { Database, errorKind, ErrorKind } = require('@joaoh82/sqlrite');
while (true) {
  try {
    db.exec('BEGIN CONCURRENT');
    db.exec("UPDATE t SET v = v + 1 WHERE id = 1");
    db.exec('COMMIT');
    break;
  } catch (err) {
    const kind = errorKind(err.message);
    if (kind === ErrorKind.Busy || kind === ErrorKind.BusySnapshot) continue;
    throw err;
  }
}

Go SDK (sdk/go/sqlrite.go)

• sqlrite.ErrBusy and sqlrite.ErrBusySnapshot sentinel errors
• sqlrite.IsRetryable(err error) bool helper covers both
• wrapErr recognises the new FFI status codes and wraps the engine message with fmt.Errorf("…: %w", ErrBusy) so errors.Is(err, sqlrite.ErrBusy) works through the cgo + database/sql driver chain

for {
    tx, err := db.Begin()
    if err != nil { return err }
    // ... do work, then:
    err = tx.Commit()
    if err == nil { break }
    if sqlrite.IsRetryable(err) { continue }
    return err
}

WASM SDK

Deliberately untouched. Browser is single-threaded; multi-handle Connection::connect concurrency isn't exposed through wasm-bindgen yet. Same 'Busy: ' message prefix will be the classifier hook when the multi-handle WASM work lands (11.10).

What this slice doesn't do

• Each SDK's connect() still builds an independent backing DB. End-to-end testing of cross-handle Busy requires the multi-handle SDK shape (planned as 11.10). This PR ships the plumbing — once that wiring lands, callers already have the retry idioms they need.
• The WAL log-record durability work (plan-doc 11.5 / roadmap 11.8) stays deferred.
• SDK READMEs aren't yet updated with retry examples; lands alongside the 11.11 doc sweep.

Test plan

• cargo build --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --all-targets — clean
• cargo test --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks — 652/652 (2 new FFI tests including a real cross-handle conflict via the FFI's Connection::connect)
• cargo test -p sqlrite-nodejs — 3 new classifier tests pass
• cargo build -p sqlrite-ffi -p sqlrite-python -p sqlrite-nodejs — all clean
• cargo clippy — no new warnings on changed files
• cargo fmt --all -- --check — clean
• cargo doc — no new warnings on changed files
• Python + Go SDK CI jobs will run the new SDK-side tests on the next CI cycle (sdk/python/tests/test_sqlrite.py + sdk/go/sqlrite_test.go)

New tests

• FFI (2): is_retryable_covers_busy_variants, begin_concurrent_busy_status_round_trip (exercises a real conflict over a shared backing DB via Connection::connect through the FFI handle).
• Node Rust-side (3): classify_recognises_busy_prefix, classify_recognises_busy_snapshot_prefix, classify_returns_other_for_generic_errors.
• Python (2): test_busy_error_class_exists_and_inherits_from_sqlrite_error, test_journal_mode_pragma_round_trips_through_python.
• Go (3): TestBusySentinelsAreDistinctErrors, TestIsRetryableCoversBothSentinels, TestJournalModeMvccRoundTripsThroughGoDriver.

Subtle issues hit + fixed

• napi-rs's #[napi(string_enum)] auto-derives Clone + Copy. My manual #[derive(Debug, Clone, Copy, …)] clashed with E0119 (conflicting implementations). Dropped Clone + Copy from the manual derive list.
• Python's SQLRiteError short name clashes between the engine enum and the pyo3 exception class (both called SQLRiteError). Used fully-qualified sqlrite::SQLRiteError::Busy(_) in match arms to disambiguate.

Roadmap renumbering

• plan-doc 11.5 (checkpoint) → roadmap 11.8
• plan-doc 11.7 (indexes) → roadmap 11.9
• multi-handle SDK + REPL .spawn (was plan-doc 11.8's other half) → roadmap 11.10
• plan-doc 11.9 (docs) → roadmap 11.11

Called out in the roadmap entries so plan-doc references remain readable.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
rust-sqlite	Ready	Preview, Comment	May 11, 2026 6:42am