sqlrite 0.9.0__tar.gz → 0.9.1__tar.gz

{sqlrite-0.9.0 → sqlrite-0.9.1}/Cargo.lock

@@ -4799,7 +4799,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ask"
-version = "0.9.0"
+version = "0.9.1"
 dependencies = [
  "serde",
  "serde_json",
@@ -4827,7 +4827,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.9.0"
+version = "0.9.1"
 dependencies = [
  "serde",
  "serde_json",
@@ -4839,7 +4839,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.9.0"
+version = "0.9.1"
 dependencies = [
  "clap",
  "env_logger",
@@ -4856,7 +4856,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.9.0"
+version = "0.9.1"
 dependencies = [
  "cbindgen",
  "serde",
@@ -4866,7 +4866,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-mcp"
-version = "0.9.0"
+version = "0.9.1"
 dependencies = [
  "clap",
  "libc",
@@ -4877,7 +4877,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.9.0"
+version = "0.9.1"
 dependencies = [
  "napi",
  "napi-build",
@@ -4887,7 +4887,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.9.0"
+version = "0.9.1"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.9.0 → sqlrite-0.9.1}/Cargo.toml

@@ -27,7 +27,7 @@ resolver = "3"
 # `package =` key so the import name stays `sqlrite` internally:
 #     sqlrite = { package = "sqlrite-engine", path = "…" }
 name = "sqlrite-engine"
-version = "0.9.0"
+version = "0.9.1"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"
@@ -141,4 +141,4 @@ fs2 = { version = "0.4", optional = true }
 # crate publishes to crates.io, and a path-only dep without a
 # version field fails the manifest verification step. See PR #58
 # retrospective in docs/roadmap.md.
-sqlrite-ask = { version = "0.9.0", path = "sqlrite-ask", optional = true }
+sqlrite-ask = { version = "0.9.1", path = "sqlrite-ask", optional = true }

{sqlrite-0.9.0 → sqlrite-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.9.0
+Version: 0.9.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{sqlrite-0.9.0 → sqlrite-0.9.1}/README.md

@@ -167,6 +167,7 @@ sqlrite> DELETE FROM users WHERE age < 30;
 | `UPDATE` | Multi-column `SET`; `WHERE`; UNIQUE + type enforcement; arithmetic in assignments (`SET age = age + 1`) |
 | `DELETE` | `WHERE` predicate or full-table delete |
 | `BEGIN` / `COMMIT` / `ROLLBACK` | Real transactions, snapshot-based; WAL-backed commit; single-level (no savepoints); auto-rollback if `COMMIT`'s disk write fails |
+| `PRAGMA auto_vacuum` | Read (`PRAGMA auto_vacuum;`) returns the trigger threshold as a single-row result set; set (`PRAGMA auto_vacuum = 0.5;` / `= OFF;` / `= NONE;`) tunes or disables auto-VACUUM at the SQL layer for SDK / FFI / MCP consumers |
 
 Expressions in `WHERE` and `UPDATE`'s `SET` RHS:
 
@@ -305,7 +306,7 @@ Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. T
 - [x] **7a — `VECTOR(N)` column type** *(v0.1.10)*: dense f32 vectors with bracket-array literal syntax (`[0.1, 0.2, ...]`); file format bumped to v4
 - [x] **7b — Distance functions** *(v0.1.11)*: `vec_distance_l2/cosine/dot` + `ORDER BY <expr> LIMIT k` so KNN queries work end-to-end
 - [x] **7c — Bounded-heap top-k optimization** *(v0.1.12)*
-- [x] **7d — HNSW ANN index** *(v0.1.13–15)*: `CREATE INDEX … USING hnsw (col)`; recall@10 ≥ 0.95 at default `M=16, ef_construction=200, ef_search=50`; persisted as a `KIND_HNSW` cell tree
+- [x] **7d — HNSW ANN index** *(v0.1.13–15, +SQLR-28)*: `CREATE INDEX … USING hnsw (col) [WITH (metric = '<l2|cosine|dot>')]`; recall@10 ≥ 0.95 at default `M=16, ef_construction=200, ef_search=50`; persisted as a `KIND_HNSW` cell tree, with the metric round-tripping through the synthesized `sqlrite_master` SQL
 - [x] **7e — JSON column type + path queries** *(v0.1.16)*: `JSON` / `JSONB` columns stored as canonical text; `json_extract` / `json_type` / `json_array_length` / `json_object_keys`; `$.key`, `[N]`, chained JSONPath subset
 - [x] **7g.1 — `sqlrite-ask` crate** *(v0.1.18)*: foundational natural-language → SQL via the [Anthropic API](https://docs.anthropic.com/) (Sonnet 4.6 by default), prompt-cached schema dump, sync `ureq` HTTP.
 - [x] **7g.2 — REPL `.ask` + dep-direction flip** *(v0.1.19)*: `.ask <question>` meta-command with `Run? [Y/n]` confirmation. The wiring required dropping the engine dep from `sqlrite-ask` (cargo cycle) — `sqlrite-ask` is now pure over `&str` schemas; the `Connection`/`Database` integration moved to the engine's new `ask` feature. Public surface for callers: `use sqlrite::{Connection, ConnectionAskExt}`.

{sqlrite-0.9.0 → sqlrite-0.9.1}/desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlrite-desktop-frontend",
   "private": true,
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "scripts": {
     "dev": "vite",

{sqlrite-0.9.0 → sqlrite-0.9.1}/docs/architecture.md

@@ -104,6 +104,7 @@ The engine never depends on the SDK crates; the SDK crates each depend on the en
 | [`src/sql/hnsw.rs`](../src/sql/hnsw.rs) | Standalone HNSW algorithm — insert / search / layer assignment / beam search. Phase 7d.1. |
 | [`src/sql/fts/`](../src/sql/fts/) | Full-text search — standalone tokenizer, BM25 scorer, and in-memory `PostingList` inverted index. Wired into the executor via the `fts_match` / `bm25_score` scalar functions and the `try_fts_probe` optimizer hook. Phase 8a-8b; persistence in 8c. See [`docs/fts.md`](fts.md). |
 | [`src/sql/json.rs`](../src/sql/json.rs) | JSON column type + path-extraction functions (`json_extract`, `json_type`, `json_array_length`, `json_object_keys`). Phase 7e. |
+| [`src/sql/pragma.rs`](../src/sql/pragma.rs) | `PRAGMA` dispatcher (SQLR-13). `try_parse_pragma` peeks at the SQL token stream before sqlparser sees it and routes any `PRAGMA …` shape to `execute_pragma`. First pragma wired up: `auto_vacuum` (read + set, with `OFF` / `NONE` to disable). Add new pragmas as a single arm in `execute_pragma`. |
 | [`src/sql/pager/`](../src/sql/pager/) | On-disk file format and I/O — see [file-format.md](file-format.md) and [pager.md](pager.md) for details. WAL + checkpointer + shared/exclusive lock modes (Phase 4a-4e) live here. |
 
 ## Flow of a SQL statement

{sqlrite-0.9.0 → sqlrite-0.9.1}/docs/benchmarks.md

@@ -90,7 +90,7 @@ A few methodology notes that change how you read the table.
 - `Statement::query_with_params(&[Value])` / `Statement::execute_with_params(&[Value])` — bind `?` placeholders at execute time without re-running sqlparser.
 - `Value::Vector(Vec<f32>)` as a first-class bind type — the 4 KB query vector for W10 is now bound directly instead of being re-lexed every iteration. The HNSW probe optimizer still recognizes the bound shape, so the algorithmic shortcut keeps firing.
 
-The bench harness `Driver::query_one` / `query_all` paths route through `prepare_cached` + the bound API. Every workload's `WorkloadId.version` was bumped `v1 → v2` in lockstep — old JSON envelopes keep the v1 tag and stay readable, but cross-version comparisons require an explicit acknowledgment in the comparison script. The next official pinned-host run will land the post-binding numbers; treat the v1 row above as "before" and watch this section for the "after" once republished.
+The bench harness `Driver::query_one` / `query_all` paths route through `prepare_cached` + the bound API. Every workload's `WorkloadId.version` was bumped `v1 → v2` in lockstep — old JSON envelopes keep the v1 tag and stay readable, but cross-version comparisons require an explicit acknowledgment in the comparison script. The headline table below carries the v2 numbers from the post-SQLR-23 republished run (SQLR-25); the retired v1 baseline lives in the historical section underneath.
 
 **Where DuckDB is misleading.** Per-PK-probe single-row OLTP queries (W9) are SQLite's home turf, not DuckDB's. The plan flags this as "apples-to-oranges"; we still publish the number because the directional comparison is informative.
 
@@ -100,29 +100,53 @@ The bench harness `Driver::query_one` / `query_all` paths route through `prepare
 
 ## Headline numbers
 
-Median latency from the first official pinned-host run — [`benchmarks/results/2026-05-07-apple-9ffd55a5.json`](../benchmarks/results/2026-05-07-apple-9ffd55a5.json), Apple M1 Pro / macOS 23.5.0, criterion defaults (3 s warm-up, 5 s measurement, 100 samples on light workloads / 10 samples on heavy ones — see the JSON envelope's per-sample `samples` field). Only medians here; the JSON carries 95 % CIs, mean, std-dev, ops/s.
+Median latency from the post-SQLR-23 pinned-host run — [`benchmarks/results/2026-05-08-apple-ac84d560.json`](../benchmarks/results/2026-05-08-apple-ac84d560.json), Apple M1 Pro / macOS 23.5.0, criterion defaults (3 s warm-up, 5 s measurement, 100 samples on light workloads / 10 samples on heavy ones — see the JSON envelope's per-sample `samples` field). Only medians here; the JSON carries 95 % CIs, mean, std-dev, ops/s.
 
 | Workload | SQLRite | SQLite (WAL+NORMAL) | DuckDB | Notes |
 |---|---|---|---|---|
-| **W1** read-by-PK | 9.87 µs | 2.05 µs | — | ~5× — parser tax |
-| **W2** range-100 | 23.99 ms | 60.50 µs | — | ~400× — full-scan vs index range probe |
-| **W2** range-1k | 24.92 ms | 585.21 µs | — | ~43× |
-| **W2** range-10k | 30.15 ms | 6.24 ms | — | ~5× — converges as scan dominates |
-| **W3** bulk insert (100k/txn) | 1.029 s | 166.43 ms | — | ~6.2× |
-| **W4** single-row insert | 6.76 ms | 9.78 µs | — | **~691× ⚠️** SQLR-18 |
-| **W5** mixed OLTP | 55.63 ms | 9.96 µs | — | **~5,580× ⚠️** SQLR-18 |
-| **W6** index lookup | 10.45 µs | 2.50 µs | — | ~4× — parser tax |
-| **W7** SUM (1M rows) | 109.47 ms | 31.14 ms | 468.74 µs | DuckDB ~66× faster than SQLite |
-| **W8** GROUP BY card-10 | 201.80 ms | 438.09 ms | 761.40 µs | DuckDB ~575× faster than SQLite |
-| **W8** GROUP BY card-1k | 1.372 s | 251.13 ms | 871.80 µs | DuckDB ~288× faster than SQLite |
-| **W8** GROUP BY card-100k | _skipped_ | 238.96 ms | 19.58 ms | **SQLRite skipped ⚠️** SQLR-19; DuckDB ~12× faster than SQLite |
-| **W9** INNER JOIN (10k×10k) | 34.25 s | 2.23 µs | 699.23 µs | **~15M× ⚠️** SQLR-20; DuckDB ~313× slower than SQLite (analytical-engine OLTP weakness) |
-| **W10** vector top-10 (brute-force, 10k×384) | 138.66 ms | — | — | parser cost dominates |
-| **W10** vector top-10 (HNSW) | 126.81 ms | — | — | masked by parser cost |
-| **W11** BM25 top-10 (1k docs) | 1.079 ms | 25.03 µs | — | ~43× |
-| **W12** hybrid (1k docs) | 713.53 µs | — | — | RAG headline |
-
-> The **canonical run** is [`benchmarks/results/2026-05-07-apple-9ffd55a5.json`](../benchmarks/results/2026-05-07-apple-9ffd55a5.json). The `dirty=true` flag in the commit metadata reflects the working-tree state when 9.6 PR was being authored (this doc + README updates uncommitted at run time); the **measurements themselves only depend on the bench binary**, which was built from the committed bench-9.5-duckdb tip. Subsequent official runs land alongside this file with their own date / host / commit.
+| **W1** read-by-PK | 3.92 µs | 2.09 µs | — | ~1.9× — gap closed by SQLR-23 (was ~4.8× in v1) |
+| **W2** range-100 | 24.27 ms | 66.62 µs | — | ~364× — full-scan vs index range probe |
+| **W2** range-1k | 26.64 ms | 649.30 µs | — | ~41× |
+| **W2** range-10k | 30.73 ms | 7.01 ms | — | ~4.4× — converges as scan dominates |
+| **W3** bulk insert (100k/txn) | 606.20 ms | 183.96 ms | — | ~3.3× — 100k INSERT plan parsed once, not per-row (was ~6.2× in v1) |
+| **W4** single-row insert | 6.57 ms | 11.35 µs | — | **~579× ⚠️** SQLR-18 |
+| **W5** mixed OLTP | 58.00 ms | 9.65 µs | — | **~6,010× ⚠️** SQLR-18 |
+| **W6** index lookup | 4.04 µs | 2.56 µs | — | ~1.6× — gap closed by SQLR-23 (was ~4.2× in v1) |
+| **W7** SUM (1M rows) | 103.62 ms | 31.57 ms | 478.78 µs | DuckDB ~66× faster than SQLite |
+| **W8** GROUP BY card-10 | 197.32 ms | 366.52 ms | 949.75 µs | DuckDB ~386× faster than SQLite |
+| **W8** GROUP BY card-1k | 1.380 s | 240.64 ms | 1.039 ms | DuckDB ~232× faster than SQLite |
+| **W8** GROUP BY card-100k | _skipped_ | 239.72 ms | 22.93 ms | **SQLRite skipped ⚠️** SQLR-19; DuckDB ~10× faster than SQLite |
+| **W9** INNER JOIN (10k×10k) | 30.30 s | 2.16 µs | 484.97 µs | **~14M× ⚠️** SQLR-20; DuckDB ~225× slower than SQLite (analytical-engine OLTP weakness) |
+| **W10** vector top-10 (brute-force, 10k×384) | 120.88 ms | — | — | compute-bound; modest ~13% drop vs v1 |
+| **W10** vector top-10 (HNSW) | **2.40 ms** | — | — | **~53× faster than v1** ⭐ — SQLR-23 + SQLR-28 unmasked the index; HNSW now ~50× faster than brute-force |
+| **W11** BM25 top-10 (1k docs) | 501.63 µs | 23.65 µs | — | ~21× — `fts_match` / `bm25_score` no longer re-parsed (was ~43× in v1) |
+| **W12** hybrid (1k docs) | 607.90 µs | — | — | RAG headline (~15% faster than v1) |
+
+> The **canonical v2 run** is [`benchmarks/results/2026-05-08-apple-ac84d560.json`](../benchmarks/results/2026-05-08-apple-ac84d560.json). It supersedes the v1 baseline (table below) end-to-end: every workload was rerun on the same canonical Apple M1 Pro host after [SQLR-23](https://github.com/joaoh82/rust_sqlite/pulls?q=SQLR-23) bumped `WorkloadId.version` from `v1 → v2` in lockstep (W10 → `v3` after [SQLR-28](https://github.com/joaoh82/rust_sqlite/pulls?q=SQLR-28) widened the HNSW probe to cosine + dot). The `dirty=true` flag reflects the working-tree state at run time (this doc update + the new envelope itself uncommitted); the **measurements themselves only depend on the bench binary**, which was built from the clean `ac84d560` tip. Subsequent official runs land alongside this file with their own date / host / commit.
+
+### Historical (v1, retired)
+
+The pre-SQLR-23 baseline from [`benchmarks/results/2026-05-07-apple-9ffd55a5.json`](../benchmarks/results/2026-05-07-apple-9ffd55a5.json), retained so the methodology shift is visible. The v1→v2 jump is not an algorithmic improvement — it's the bench-driver methodology change (per-iter `inline_params` → `prepare_cached` + bound `?` parameters; `Value::Vector` for HNSW-eligible KNN). Cross-version comparisons (`W1.v1` vs `W1.v2`) are flagged in the comparison script per Q8; the [`compare.py`](../benchmarks/scripts/compare.py) v1↔v2 report walks each one.
+
+| Workload | SQLRite (v1) | SQLite (v1) | DuckDB (v1) |
+|---|---|---|---|
+| **W1** read-by-PK | 9.87 µs | 2.05 µs | — |
+| **W2** range-100 | 23.99 ms | 60.50 µs | — |
+| **W2** range-1k | 24.92 ms | 585.21 µs | — |
+| **W2** range-10k | 30.15 ms | 6.24 ms | — |
+| **W3** bulk insert (100k/txn) | 1.029 s | 166.43 ms | — |
+| **W4** single-row insert | 6.76 ms | 9.78 µs | — |
+| **W5** mixed OLTP | 55.63 ms | 9.96 µs | — |
+| **W6** index lookup | 10.45 µs | 2.50 µs | — |
+| **W7** SUM (1M rows) | 109.47 ms | 31.14 ms | 468.74 µs |
+| **W8** GROUP BY card-10 | 201.80 ms | 438.09 ms | 761.40 µs |
+| **W8** GROUP BY card-1k | 1.372 s | 251.13 ms | 871.80 µs |
+| **W8** GROUP BY card-100k | _skipped_ | 238.96 ms | 19.58 ms |
+| **W9** INNER JOIN (10k×10k) | 34.25 s | 2.23 µs | 699.23 µs |
+| **W10** brute-force | 138.66 ms | — | — |
+| **W10** HNSW | 126.81 ms | — | — |
+| **W11** BM25 top-10 (1k docs) | 1.079 ms | 25.03 µs | — |
+| **W12** hybrid (1k docs) | 713.53 µs | — | — |
 
 ---
 

{sqlrite-0.9.0 → sqlrite-0.9.1}/docs/pager.md

@@ -205,7 +205,7 @@ Format-version side effect: a save that produces a non-empty freelist promotes t
 
 After SQLR-6, the file still required a manual `VACUUM;` to actually shrink — the freelist absorbed orphan pages but the high-water mark stayed put. SQLR-10 adds a heuristic that fires `vacuum_database` automatically after a page-releasing DDL (`DROP TABLE`, `DROP INDEX`, `ALTER TABLE DROP COLUMN`) when the freelist exceeds a configurable fraction of `page_count`.
 
-Configuration lives on `Database::auto_vacuum_threshold: Option<f32>` and is exposed at the connection level via `Connection::set_auto_vacuum_threshold` / `auto_vacuum_threshold`. Defaults: `Some(0.25)` (SQLite parity at 25%); pass `None` to opt out per connection. The threshold is per-`Connection` runtime state and is not persisted in the file header — every reopen starts at the default. A SQL-level `PRAGMA auto_vacuum` is tracked separately (out of scope for SQLR-10).
+Configuration lives on `Database::auto_vacuum_threshold: Option<f32>` and is exposed at the connection level via `Connection::set_auto_vacuum_threshold` / `auto_vacuum_threshold`, and via SQL through `PRAGMA auto_vacuum` (SQLR-13 — see [`src/sql/pragma.rs`](../src/sql/pragma.rs)). Defaults: `Some(0.25)` (SQLite parity at 25%); pass `None` (or `PRAGMA auto_vacuum = OFF`) to opt out per connection. The threshold is per-`Connection` runtime state and is not persisted in the file header — every reopen starts at the default.
 
 The trigger lives at the end of [`process_command_with_render`](../src/sql/mod.rs), immediately after the auto-save. Order matters: the freelist isn't accurate until the bottom-up rebuild runs during save, so we save first, then check the ratio. The check itself is `freelist::should_auto_vacuum(pager, threshold)`, which:
 

{sqlrite-0.9.0 → sqlrite-0.9.1}/docs/phase-7-plan.md

@@ -163,6 +163,7 @@ SELECT id, title FROM docs ORDER BY embedding <-> [0.1, ...] LIMIT 10;
 > - **✅ 7d.1 — Pure HNSW algorithm** *(~700 LOC, shipped in v0.1.13).* `src/sql/hnsw.rs` standalone module: insert + search + layer assignment + beam search per layer + L2/cosine/dot distance dispatch. No SQL integration yet — vectors are passed in via a `get_vec` closure so the algorithm doesn't depend on table types. Tests verify recall@k ≥ 0.95 vs brute-force on randomly-generated vector sets; deterministic via a fixed RNG seed.
 > - **✅ 7d.2 — SQL integration** *(~500 LOC).* `CREATE INDEX … USING hnsw (col)` parser + engine, INSERT wiring (also calls `hnsw.insert()` incrementally), query optimizer hook (recognizes `ORDER BY vec_distance_l2(col, literal) LIMIT k` and probes the HNSW instead of full-scanning). HNSW lives in memory only at this point; the **CREATE INDEX SQL persists in `sqlrite_master` and reopen rebuilds the graph from current rows** — partial persistence ahead of 7d.3. DELETE/UPDATE on HNSW-indexed tables refused with helpful error pointing at 7d.3.
 > - **✅ 7d.3 — Persistence** *(~600 LOC).* New `KIND_HNSW` cell tag and `HnswNodeCell` encoding (varint node_id + per-layer neighbor lists). Each HNSW index gets its own page tree parallel to secondary indexes. Open path loads cells directly into `HnswIndex::from_persisted_nodes` — no algorithm runs, exact bit-for-bit reproduction. Also unblocks DELETE / UPDATE on HNSW-indexed tables: those mark the index `needs_rebuild`, save rebuilds from current rows before staging. ~2× the original 300-LOC estimate because the cell encoding + tests + rebuild path together added more than expected.
+> - **✅ 7d.4 (SQLR-28) — Per-index distance metric.** Q2's "deferred per-index metric knob" lands as `CREATE INDEX … USING hnsw (col) WITH (metric = '<l2|cosine|dot>')`. The metric is stored on `HnswIndexEntry` and round-tripped via the synthesized CREATE INDEX SQL in `sqlrite_master` (no file-format bump — pre-SQLR-28 rows omit the WITH clause and decode as L2). The optimizer's `try_hnsw_probe` widens to all three `vec_distance_*` functions but only fires when the query function matches the index's metric; mismatches fall through to brute-force. Surfaced by the SQLR-23 v2 bench: W10 uses cosine, the optimizer was L2-only, and the HNSW variant had been silently brute-forcing the entire time. SQLR-25 (republish v2 numbers) was the gating consumer.
 >
 > Each 7d.x ships as its own PR + release wave. The user-facing value lands at 7d.2; 7d.3 closes the persistence loop. 7d.1 is foundational but ships a tested algorithmic primitive on its own — useful as documentation of the engine's "from scratch" theme.
 
@@ -368,12 +369,12 @@ Q1–Q10 were resolved by the project owner on 2026-04-26. Each question keeps i
 
 ### Q2. HNSW parameters: fixed defaults or per-index configurable?
 
-> **Decided: fixed defaults** (`M=16, ef_construction=200, ef_search=50`).
+> **Decided: fixed defaults** (`M=16, ef_construction=200, ef_search=50`) for the algorithmic knobs. **Distance metric** *did* land as a per-index `WITH (metric = '<l2|cosine|dot>')` clause in **SQLR-28 / sub-phase 7d.4** — see the 7d split note above. Was deferred from the original 7d.2 cut; surfaced as a gap by the SQLR-23 v2 bench, where W10's cosine query had been silently brute-forcing because the optimizer hook was L2-only.
 
 - **Fixed:** `M=16, ef_construction=200, ef_search=50`. Simpler API, less to test. Matches sqlite-vec's defaults.
 - **Configurable:** `CREATE INDEX … USING hnsw (col) WITH (m=32, ef_construction=400)`. Power-user knobs, more code, more test matrix.
 
-**Recommendation:** fixed defaults for MVP. Configurable can land as a follow-up if anyone actually asks.
+**Recommendation:** fixed defaults for MVP. Configurable can land as a follow-up if anyone actually asks. (`metric` already came back as a follow-up; `m` / `ef_*` haven't been requested yet.)
 
 ### Q3. JSON storage format
 

{sqlrite-0.9.0 → sqlrite-0.9.1}/docs/supported-sql.md

@@ -113,15 +113,18 @@ These are full-citizen indexes — they're visible via `.tables`-adjacent catalo
 ### HNSW indexes (Phase 7d)
 
 ```sql
-CREATE INDEX <name> ON <table> USING hnsw (<vector_column>);
+CREATE INDEX <name> ON <table> USING hnsw (<vector_column>)
+  [WITH (metric = '<l2|cosine|dot>')];
 ```
 
-Builds an [HNSW](https://arxiv.org/abs/1603.09320) approximate-nearest-neighbor index over a `VECTOR(N)` column. The query optimizer recognizes `ORDER BY vec_distance_l2(col, literal) LIMIT k` (or the cosine / dot variants) on an HNSW-indexed column and probes the graph instead of full-scanning. SQLR-23 — the second arg can be either an inline `[...]` literal *or* a bound `Value::Vector(...)` parameter via `Statement::query_with_params`; the optimizer recognizes both, so prepared-statement KNN queries still take the graph shortcut.
+Builds an [HNSW](https://arxiv.org/abs/1603.09320) approximate-nearest-neighbor index over a `VECTOR(N)` column. The query optimizer recognizes `ORDER BY vec_distance_l2(col, literal) LIMIT k` (or the cosine / dot variants) on an HNSW-indexed column **whose metric matches the query's distance function**, and probes the graph instead of full-scanning. SQLR-23 — the second arg can be either an inline `[...]` literal *or* a bound `Value::Vector(...)` parameter via `Statement::query_with_params`; the optimizer recognizes both, so prepared-statement KNN queries still take the graph shortcut.
 
-- Recall@10 ≥ 0.95 at default parameters (`M=16`, `ef_construction=200`, `ef_search=50`). Parameters aren't tunable from SQL yet — see Q2 of [`docs/phase-7-plan.md`](phase-7-plan.md).
-- The index is built incrementally on `INSERT`. `DELETE` / `UPDATE` mark the index `needs_rebuild`; the next save rebuilds from current rows.
-- Persisted as a `KIND_HNSW` cell tree alongside the regular page hierarchy — open path loads the graph bit-for-bit, no algorithm runs.
-- Without an HNSW index, the same `ORDER BY vec_distance_… LIMIT k` query still works — it just brute-force-scans every row (Phase 7c's bounded-heap top-k optimization keeps the memory footprint to O(k)).
+The `WITH (metric = '…')` clause picks the distance the graph is built for. Three values are recognized: `'l2'` (Euclidean — the default, also accepts `'euclidean'`), `'cosine'`, and `'dot'` (negated dot-product — also accepts `'inner_product'` / `'ip'`). Omitting the clause is equivalent to `metric = 'l2'`, so pre-SQLR-28 catalogs round-trip unchanged. **The metric is not a query-time choice** — the graph topology depends on the metric used during INSERT (neighbour pruning is metric-specific), so a query whose `vec_distance_*` function doesn't match the index's metric falls through to brute-force rather than getting a wrong answer back from the graph. If you need both L2 and cosine probes on the same column, create two indexes.
+
+- Recall@10 ≥ 0.95 at default parameters (`M=16`, `ef_construction=200`, `ef_search=50`). The `M` / `ef_*` knobs aren't tunable from SQL yet — see Q2 of [`docs/phase-7-plan.md`](phase-7-plan.md).
+- The index is built incrementally on `INSERT`. `DELETE` / `UPDATE` mark the index `needs_rebuild`; the next save rebuilds from current rows under the same metric.
+- Persisted as a `KIND_HNSW` cell tree alongside the regular page hierarchy — open path loads the graph bit-for-bit, no algorithm runs. The metric travels through the synthesized CREATE INDEX SQL in `sqlrite_master`; no file-format bump.
+- Without an HNSW index — or with a metric mismatch — the same `ORDER BY vec_distance_… LIMIT k` query still works; it just brute-force-scans every row (Phase 7c's bounded-heap top-k optimization keeps the memory footprint to O(k)).
 
 ### FTS indexes (Phase 8)
 
@@ -548,7 +551,16 @@ conn.set_auto_vacuum_threshold(Some(0.5))?; // fire only when freelist > 50%
 conn.set_auto_vacuum_threshold(None)?;       // disable entirely (manual VACUUM only)
 ```
 
-The setting is per-`Connection` runtime state — it's not persisted in the file header, so every reopen starts at the default `Some(0.25)`. A SQL-level `PRAGMA auto_vacuum` knob is on the roadmap but not yet implemented (SDK consumers currently configure it via the per-binding glue or fall back to the default).
+…or via SQL (SQLR-13), which is the path SDK / FFI / MCP consumers reach for since they can't call the Rust setter directly:
+
+```sql
+PRAGMA auto_vacuum;            -- read; renders a single-row result set
+PRAGMA auto_vacuum = 0.5;      -- arm the trigger at 50%
+PRAGMA auto_vacuum = 0;        -- arm at 0% (compact on any released page)
+PRAGMA auto_vacuum = OFF;      -- disable; equivalent: NONE, 'OFF', 'NONE'
+```
+
+Out-of-range values (anything outside `0.0..=1.0`, `NaN`, `±∞`) and unknown identifiers like `WAL` / `FULL` are rejected with a typed error — the trigger never silently saturates or falls back to a default. The setting is per-`Connection` runtime state — it's not persisted in the file header, so every reopen starts at the default `Some(0.25)`.
 
 ---
 
@@ -618,7 +630,7 @@ For context when you hit `NotImplemented`. See [Roadmap](roadmap.md) for when th
 
 ### Session / schema
 - Multiple attached databases (`ATTACH DATABASE`, `DETACH DATABASE`)
-- `PRAGMA` statements beyond what the parser accepts (none currently executed)
+- `PRAGMA` statements other than `auto_vacuum` (SQLR-13). The dispatcher is in place — adding a pragma is a single arm in `execute_pragma`. `journal_mode`, `synchronous`, `cache_size`, etc. are not yet wired up
 - `REPLACE INTO`, `INSERT OR IGNORE`, `INSERT OR REPLACE` (conflict-resolution clauses)
 
 ---

{sqlrite-0.9.0 → sqlrite-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlrite"
-version = "0.9.0"
+version = "0.9.1"
 description = "Python bindings for SQLRite — a small, embeddable SQLite clone written in Rust."
 authors = [{ name = "Joao Henrique Machado Silva", email = "joaoh82@gmail.com" }]
 license = { text = "MIT" }

{sqlrite-0.9.0 → sqlrite-0.9.1}/sdk/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sqlrite-python"
-version = "0.9.0"
+version = "0.9.1"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.9.0 → sqlrite-0.9.1}/sqlrite-ask/Cargo.toml

@@ -10,7 +10,7 @@
 # Published to crates.io as `sqlrite-ask`. Joins the lockstep release
 # wave (`sqlrite-ask-vX.Y.Z` tag) — see `docs/release-plan.md`.
 name = "sqlrite-ask"
-version = "0.9.0"
+version = "0.9.1"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.9.0 → sqlrite-0.9.1}/src/connection.rs

@@ -54,8 +54,8 @@ use std::collections::VecDeque;
 use std::path::Path;
 use std::sync::Arc;
 
+use crate::sql::dialect::SqlriteDialect;
 use sqlparser::ast::Statement as AstStatement;
-use sqlparser::dialect::SQLiteDialect;
 use sqlparser::parser::Parser;
 
 use crate::error::{Result, SQLRiteError};
@@ -320,7 +320,7 @@ struct CachedPlan {
 
 impl CachedPlan {
     fn compile(sql: &str) -> Result<Self> {
-        let dialect = SQLiteDialect {};
+        let dialect = SqlriteDialect::new();
         let mut ast = Parser::parse_sql(&dialect, sql).map_err(SQLRiteError::from)?;
         let Some(mut stmt) = ast.pop() else {
             return Err(SQLRiteError::General("no statement to prepare".to_string()));
@@ -1115,6 +1115,158 @@ mod tests {
         assert_eq!(rows[0].get::<i64>(0).unwrap(), 1);
     }
 
+    /// SQLR-28 — cosine probe: an HNSW index built `WITH (metric =
+    /// 'cosine')` must serve `ORDER BY vec_distance_cosine(col, [...])`
+    /// from the graph. Self-query: querying for one of the corpus's
+    /// own vectors must come back as the nearest under cosine
+    /// distance.
+    #[test]
+    fn cosine_self_query_through_hnsw_optimizer() {
+        let mut conn = Connection::open_in_memory().unwrap();
+        conn.execute("CREATE TABLE v (id INTEGER PRIMARY KEY, e VECTOR(4));")
+            .unwrap();
+        let corpus: [(i64, [f32; 4]); 5] = [
+            (1, [1.0, 0.0, 0.0, 0.0]),
+            (2, [0.0, 1.0, 0.0, 0.0]),
+            (3, [0.0, 0.0, 1.0, 0.0]),
+            (4, [0.0, 0.0, 0.0, 1.0]),
+            (5, [0.5, 0.5, 0.5, 0.5]),
+        ];
+        for (id, vec) in corpus {
+            conn.execute(&format!(
+                "INSERT INTO v (id, e) VALUES ({id}, [{}, {}, {}, {}]);",
+                vec[0], vec[1], vec[2], vec[3]
+            ))
+            .unwrap();
+        }
+        conn.execute("CREATE INDEX v_hnsw ON v USING hnsw (e) WITH (metric = 'cosine');")
+            .unwrap();
+
+        // Self-query for id=2's vector — expected nearest under cosine
+        // distance is id=2 itself (cos distance 0).
+        let rows = conn
+            .prepare("SELECT id FROM v ORDER BY vec_distance_cosine(e, [0.0, 1.0, 0.0, 0.0]) ASC LIMIT 1")
+            .unwrap()
+            .query_with_params(&[])
+            .unwrap()
+            .collect_all()
+            .unwrap();
+        assert_eq!(rows.len(), 1);
+        assert_eq!(rows[0].get::<i64>(0).unwrap(), 2);
+    }
+
+    /// SQLR-28 — dot probe: same shape as the cosine test, but the
+    /// index is built `WITH (metric = 'dot')` and the query uses
+    /// `vec_distance_dot`. Confirms the third metric variant lights up
+    /// the graph shortcut, not just l2 / cosine.
+    #[test]
+    fn dot_self_query_through_hnsw_optimizer() {
+        let mut conn = Connection::open_in_memory().unwrap();
+        conn.execute("CREATE TABLE v (id INTEGER PRIMARY KEY, e VECTOR(3));")
+            .unwrap();
+        // Data: distinguishable magnitudes so the dot metric resolves
+        // a clear winner. `vec_distance_dot(a, b) = -(a·b)` — smaller
+        // (more negative) is closer.
+        let corpus: [(i64, [f32; 3]); 4] = [
+            (1, [1.0, 0.0, 0.0]),
+            (2, [2.0, 0.0, 0.0]),
+            (3, [0.0, 1.0, 0.0]),
+            (4, [0.0, 0.0, 1.0]),
+        ];
+        for (id, vec) in corpus {
+            conn.execute(&format!(
+                "INSERT INTO v (id, e) VALUES ({id}, [{}, {}, {}]);",
+                vec[0], vec[1], vec[2]
+            ))
+            .unwrap();
+        }
+        conn.execute("CREATE INDEX v_hnsw ON v USING hnsw (e) WITH (metric = 'dot');")
+            .unwrap();
+
+        // Query [3, 0, 0]: dot products are 3, 6, 0, 0 → distances
+        // -3, -6, 0, 0. id=2 has the smallest (most negative) distance.
+        let rows = conn
+            .prepare("SELECT id FROM v ORDER BY vec_distance_dot(e, [3.0, 0.0, 0.0]) ASC LIMIT 1")
+            .unwrap()
+            .query_with_params(&[])
+            .unwrap()
+            .collect_all()
+            .unwrap();
+        assert_eq!(rows.len(), 1);
+        assert_eq!(rows[0].get::<i64>(0).unwrap(), 2);
+    }
+
+    /// SQLR-28 — metric mismatch must NOT take the graph shortcut.
+    /// An L2-built index queried with `vec_distance_cosine` falls
+    /// through to brute-force, which still returns the correct
+    /// answer. We confirm the answer is correct; the slow-path
+    /// behaviour itself is implicit (no error, no panic, no wrong
+    /// result), which is the user-visible contract that matters.
+    #[test]
+    fn metric_mismatch_falls_back_to_brute_force() {
+        let mut conn = Connection::open_in_memory().unwrap();
+        conn.execute("CREATE TABLE v (id INTEGER PRIMARY KEY, e VECTOR(2));")
+            .unwrap();
+        let half_sqrt2 = std::f32::consts::FRAC_1_SQRT_2;
+        let corpus: [(i64, [f32; 2]); 3] = [
+            (1, [1.0, 0.0]),
+            (2, [half_sqrt2, half_sqrt2]),
+            (3, [0.0, 1.0]),
+        ];
+        for (id, vec) in corpus {
+            conn.execute(&format!(
+                "INSERT INTO v (id, e) VALUES ({id}, [{}, {}]);",
+                vec[0], vec[1]
+            ))
+            .unwrap();
+        }
+        // Default L2 index — no WITH clause.
+        conn.execute("CREATE INDEX v_hnsw_l2 ON v USING hnsw (e);")
+            .unwrap();
+
+        // Query with cosine. Index can't help; brute-force still
+        // returns the correct nearest by cosine: id=1 (cos dist 0).
+        let rows = conn
+            .prepare("SELECT id FROM v ORDER BY vec_distance_cosine(e, [1.0, 0.0]) ASC LIMIT 1")
+            .unwrap()
+            .query_with_params(&[])
+            .unwrap()
+            .collect_all()
+            .unwrap();
+        assert_eq!(rows.len(), 1);
+        assert_eq!(rows[0].get::<i64>(0).unwrap(), 1);
+    }
+
+    /// SQLR-28 — a typo in the metric name must error at CREATE INDEX
+    /// time. Falling back to L2 silently is the bug we're fixing here,
+    /// not the behaviour to preserve.
+    #[test]
+    fn unknown_metric_name_is_rejected() {
+        let mut conn = Connection::open_in_memory().unwrap();
+        conn.execute("CREATE TABLE v (id INTEGER PRIMARY KEY, e VECTOR(2));")
+            .unwrap();
+        let err = conn
+            .execute("CREATE INDEX bad ON v USING hnsw (e) WITH (metric = 'cosin');")
+            .unwrap_err();
+        let msg = format!("{err}");
+        assert!(msg.contains("unknown HNSW metric"), "got: {msg}");
+    }
+
+    /// SQLR-28 — WITH options on a non-HNSW index must error rather
+    /// than be silently ignored. An option that has no effect on the
+    /// resulting index is a footgun.
+    #[test]
+    fn with_metric_on_btree_is_rejected() {
+        let mut conn = Connection::open_in_memory().unwrap();
+        conn.execute("CREATE TABLE t (a INTEGER PRIMARY KEY, b TEXT);")
+            .unwrap();
+        let err = conn
+            .execute("CREATE INDEX bad ON t (b) WITH (metric = 'cosine');")
+            .unwrap_err();
+        let msg = format!("{err}");
+        assert!(msg.contains("doesn't support any options"), "got: {msg}");
+    }
+
     #[test]
     fn prepare_cached_executes_the_same_as_prepare() {
         let mut conn = Connection::open_in_memory().unwrap();

{sqlrite-0.9.0 → sqlrite-0.9.1}/src/sql/db/database.rs

@@ -198,8 +198,8 @@ impl Database {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::sql::dialect::SqlriteDialect;
     use crate::sql::parser::create::CreateQuery;
-    use sqlparser::dialect::SQLiteDialect;
     use sqlparser::parser::Parser;
 
     #[test]
@@ -220,7 +220,7 @@ mod tests {
             last_name TEXT NOT NULl,
             email TEXT NOT NULL UNIQUE
         );";
-        let dialect = SQLiteDialect {};
+        let dialect = SqlriteDialect::new();
         let mut ast = Parser::parse_sql(&dialect, query_statement).unwrap();
         if ast.len() > 1 {
             panic!("Expected a single query statement, but there are more then 1.")
@@ -246,7 +246,7 @@ mod tests {
             last_name TEXT NOT NULl,
             email TEXT NOT NULL UNIQUE
         );";
-        let dialect = SQLiteDialect {};
+        let dialect = SqlriteDialect::new();
         let mut ast = Parser::parse_sql(&dialect, query_statement).unwrap();
         if ast.len() > 1 {
             panic!("Expected a single query statement, but there are more then 1.")

{sqlrite-0.9.0 → sqlrite-0.9.1}/src/sql/db/table.rs

@@ -1,7 +1,7 @@
 use crate::error::{Result, SQLRiteError};
 use crate::sql::db::secondary_index::{IndexOrigin, SecondaryIndex};
 use crate::sql::fts::PostingList;
-use crate::sql::hnsw::HnswIndex;
+use crate::sql::hnsw::{DistanceMetric, HnswIndex};
 use crate::sql::parser::create::{CreateQuery, ParsedColumn};
 use std::collections::{BTreeMap, HashMap};
 use std::fmt;
@@ -150,10 +150,11 @@ pub struct Table {
     pub primary_key: String,
 }
 
-/// One HNSW index attached to a table. Phase 7d.2 only supports L2
-/// distance; cosine and dot are 7d.x follow-ups (would require either
-/// distinct USING methods like `hnsw_cosine` or a `WITH (metric = …)`
-/// clause — see `docs/phase-7-plan.md` for the deferred decision).
+/// One HNSW index attached to a table. The distance metric is fixed
+/// at CREATE INDEX time via `USING hnsw (col) WITH (metric = '<m>')`
+/// (`l2` / `cosine` / `dot`); omitting the WITH clause defaults to L2,
+/// matching the pre-SQLR-28 behaviour for round-tripping older
+/// `sqlrite_master` rows that didn't carry a metric.
 #[derive(Debug, Clone)]
 pub struct HnswIndexEntry {
     /// User-supplied name from `CREATE INDEX <name> …`. Unique across
@@ -161,6 +162,13 @@ pub struct HnswIndexEntry {
     pub name: String,
     /// The VECTOR column this index covers.
     pub column_name: String,
+    /// Distance metric the graph was built for. The optimizer's HNSW
+    /// shortcut only fires when the query's `vec_distance_*` function
+    /// matches this metric — picking a non-matching distance falls
+    /// through to brute-force, since the graph topology is metric-
+    /// specific (an L2-pruned graph isn't a valid cosine search graph
+    /// in general, and vice versa).
+    pub metric: DistanceMetric,
     /// The graph itself.
     pub index: HnswIndex,
     /// Phase 7d.3 — true iff a DELETE or UPDATE-on-vector-col has
@@ -1628,7 +1636,7 @@ pub fn parse_vector_literal(s: &str) -> Result<Vec<f32>> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use sqlparser::dialect::SQLiteDialect;
+    use crate::sql::dialect::SqlriteDialect;
     use sqlparser::parser::Parser;
 
     #[test]
@@ -1766,7 +1774,7 @@ mod tests {
             active BOOL,
             score REAL
         );";
-        let dialect = SQLiteDialect {};
+        let dialect = SqlriteDialect::new();
         let mut ast = Parser::parse_sql(&dialect, query_statement).unwrap();
         if ast.len() > 1 {
             panic!("Expected a single query statement, but there are more then 1.")
@@ -1802,7 +1810,7 @@ mod tests {
             first_name TEXT NOT NULL,
             last_name TEXT NOT NULl
         );";
-        let dialect = SQLiteDialect {};
+        let dialect = SqlriteDialect::new();
         let mut ast = Parser::parse_sql(&dialect, query_statement).unwrap();
         if ast.len() > 1 {
             panic!("Expected a single query statement, but there are more then 1.")