feat(repl): Phase 11.11a REPL .spawn for interactive BEGIN CONCURRENT demos (SQLR-22)

[joaoh82]

Summary

• Lifts the REPL from a single Database to Vec<Connection> so users can mint sibling handles in-session and step through cross-handle MVCC scenarios.
• New meta-commands .spawn / .use NAME / .conns drive the multi-handle UX; the prompt always shows the active handle (sqlrite[A]> , sqlrite[B]> ).
• New Connection::execute_with_render lets the REPL keep the prettytable output for SELECT while routing every line through Connection so BEGIN CONCURRENT / COMMIT / ROLLBACK hit the per-connection MVCC state.

Worked demo

sqlrite[A]> PRAGMA journal_mode = mvcc;
sqlrite[A]> CREATE TABLE t (id INTEGER PRIMARY KEY, v INTEGER);
sqlrite[A]> INSERT INTO t (id, v) VALUES (1, 0);
sqlrite[A]> .spawn          -- switches to B
sqlrite[B]> .use A
sqlrite[A]> BEGIN CONCURRENT;
sqlrite[A]> UPDATE t SET v = 100 WHERE id = 1;
sqlrite[A]> .conns
2 handle(s):
  * A (BEGIN CONCURRENT)
    B
sqlrite[A]> .use B
sqlrite[B]> BEGIN CONCURRENT;
sqlrite[B]> UPDATE t SET v = 200 WHERE id = 1;
sqlrite[B]> COMMIT;
sqlrite[B]> .use A
sqlrite[A]> COMMIT;
An error occured: Busy: write-write conflict on t/1: another transaction
committed this row at ts=3 (after our begin_ts=1); transaction rolled
back, retry with a fresh BEGIN CONCURRENT
sqlrite[A]> .use B
sqlrite[B]> SELECT * FROM t;
+----+-----+
| id | v   |
+----+-----+
| 1  | 200 |
+----+-----+

Changes

• src/repl/mod.rs: new ReplState struct holds Vec<Connection>, parallel Vec<String> of stable letter names, and the active index. Methods: spawn_sibling, use_handle, handles_summary, lock_active, active_conn_mut, collapse_to_active. A next_handle_name(usize) -> String helper produces the A, …, Z, AA, AB sequence.
• src/meta_command/mod.rs: new MetaCommand::Spawn / Use(String) / Conns variants + parser + handlers. .open now calls state.collapse_to_active() before swapping the underlying Database so siblings can't be left pointing at the stale one.
• src/main.rs: REPL loop migrated from &mut Database to &mut ReplState. SQL dispatch routes through Connection::execute_with_render. Prompt shows the active handle name.
• src/connection.rs: new execute_with_render, execute_dispatch_with_render, execute_in_concurrent_tx_with_render — render-aware twins of the existing dispatch tree. concurrent_tx_is_open() promoted to pub so .conns can render the per-handle tx flag.

Why this is split from "Phase 11.11"

The original plan-doc 11.11 bundled the REPL .spawn work with a heavier "N concurrent writers" benchmark workload (extends the benchmarks/ harness, links SQLite + DuckDB drivers, criterion-driven). Splitting keeps each PR reviewable. The bench workload becomes Phase 11.11b in the roadmap.

Test plan

• cargo build --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --all-targets
• cargo test --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks — 615/615 (was 607, +8 new in meta_command::tests)
• cargo fmt --all -- --check
• cargo clippy --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --all-targets
• cargo doc --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --no-deps
• Smoke-tested the BEGIN CONCURRENT cross-handle demo end-to-end
• CI green

Docs updated

• docs/roadmap.md — Phase 11.11a promoted to shipped, 11.11b carved out for the bench workload.
• docs/usage.md — new "Multi-handle mode" section with the worked demo above.
• docs/smoke-test.md — prompt example refreshed (sqlrite[A]>), command count bumped 5 → 9.
• docs/design-decisions.md — new §12h on the migration rationale (Vec<Connection> over HashMap, .open collapse semantics, execute_with_render design).

🤖 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 9:28am