feat(sdk:go): Phase 11.11c — cross-pool sibling shape via path registry (SQLR-22)

[joaoh82]

Summary

• Closes the last open item from Phase 11's SDK arc. Pre-11.11c the Go SDK took a real engine Connection::open for every sql.Open(…) call — which deadlocked against itself on flock(LOCK_EX) whenever two *sql.DB instances pointed at the same file, or a single pool grew past one connection.
• New process-level path registry keyed by canonical absolute path. The first opener pays for a real sqlrite_open; subsequent openers mint sibling handles off it via the FFI's sqlrite_connect_sibling (shipped in 11.8), sharing Arc<Mutex<Database>> underneath. Refcounted: the last sibling out fires sqlrite_close on the primary.
• Three new tests cover cross-*sql.DB state sharing, BEGIN CONCURRENT across separate pools with a real Busy + retry (final value 0 + 1 + 100 = 101), and the refcount-to-zero roundtrip.

The headline cross-pool demo

db1, _ := sql.Open("sqlrite", "accounts.sqlrite")
db2, _ := sql.Open("sqlrite", "accounts.sqlrite") // sibling, shares state with db1

db1.Exec("PRAGMA journal_mode = mvcc")

ctx := context.Background()
a, _ := db1.Conn(ctx); defer a.Close()
b, _ := db2.Conn(ctx); defer b.Close()

a.ExecContext(ctx, "BEGIN CONCURRENT")
b.ExecContext(ctx, "BEGIN CONCURRENT")
a.ExecContext(ctx, "UPDATE accounts SET balance = balance + 50 WHERE id = 1")
b.ExecContext(ctx, "UPDATE accounts SET balance = balance + 100 WHERE id = 1")
a.ExecContext(ctx, "COMMIT")                  // wins
_, err := b.ExecContext(ctx, "COMMIT")        // → wrapped sqlrite.ErrBusy
errors.Is(err, sqlrite.ErrBusy)               // true

Architecture

sql.Open("sqlrite", "accounts.sqlrite")   ─┐
sql.Open("sqlrite", "accounts.sqlrite")   ─┼──> canonicalPath → registryMu
sql.Open("sqlrite", "./accounts.sqlrite") ─┘                       │
                                                                   ▼
                            ┌──────────────────────────────────────┐
                            │ pathRegistry["/abs/accounts.sqlrite"]│
                            │   primary: *SqlriteConnection (hidden│
                            │            ─ owned by registry)      │
                            │   refcount: N (outstanding siblings) │
                            └──────────────────────────────────────┘
                                          │ connect_sibling
                                          ▼
                            ┌──────────────────────────────────────┐
                            │  Each *conn owns its own sibling     │
                            │  handle. Close() drops refcount;     │
                            │  hitting 0 closes the primary +      │
                            │  removes the entry.                  │
                            └──────────────────────────────────────┘

Scope decisions (v0)

Open mode	Registry path
File-backed read-write	✅ Routes through registry
:memory:	❌ Bypasses — isolated by design (matches SQLite)
Read-only (sqlrite.OpenReadOnly)	❌ Bypasses — shared flock(LOCK_SH) already coexists with other readers
Symlinks	Not resolved. Lexical key only (filepath.Abs + filepath.Clean). Callers needing symlink-equality pass os.EvalSymlinks-canonicalized paths

Where this fits in the Phase 11 SDK arc

SDK	Sibling API	Status
C FFI	sqlrite_connect_sibling	✅ 11.8
Python	conn.connect()	✅ 11.8
Node.js	db.connect()	✅ 11.8
Go	path registry + sqlrite_connect_sibling	✅ 11.11c (this PR)
WASM	(deferred — single-threaded runtime)	—

Docs

• sdk/go/README.md — new "Multi-handle reads + writes" section with the cross-pool runnable example + BEGIN CONCURRENT retry-loop demo + caveats.
• docs/concurrent-writes.md — SDK propagation table updated; the "still constructs its own backing DB" note replaced with the registry's actual behaviour.
• docs/_index.md — Phase 11 summary blurb refreshed to reflect end-to-end completion.
• docs/roadmap.md — Phase 11.11c promoted to ✅ shipped; active-frontier blurb refreshed.
• docs/design-decisions.md — new §12i covering the registry rationale, lock order, scope decisions, symlink caveat.

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
• 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
• cd sdk/go && go test -count=1 -timeout 120s ./... — all existing + 3 new tests pass in ~1s
• CI green

What's left of Phase 11

This wraps the SDK arc. The only remaining items are deferred-by-design or foundation work:

• Phase 11.10 — Indexes under MVCC (deferred-by-design; Turso punted on the same problem).
• Checkpoint-drain follow-up — the parked half of 11.9. Enables set_journal_mode(Mvcc → Wal) once MvStore is drainable.

🤖 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 1:40pm