sqlrite 0.3.0__tar.gz → 0.5.0__tar.gz

{sqlrite-0.3.0 → sqlrite-0.5.0}/Cargo.lock

@@ -3817,7 +3817,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ask"
-version = "0.3.0"
+version = "0.5.0"
 dependencies = [
  "serde",
  "serde_json",
@@ -3828,7 +3828,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.3.0"
+version = "0.5.0"
 dependencies = [
  "serde",
  "serde_json",
@@ -3840,7 +3840,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.3.0"
+version = "0.5.0"
 dependencies = [
  "clap",
  "env_logger",
@@ -3857,7 +3857,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.3.0"
+version = "0.5.0"
 dependencies = [
  "cbindgen",
  "serde",
@@ -3867,7 +3867,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-mcp"
-version = "0.3.0"
+version = "0.5.0"
 dependencies = [
  "clap",
  "libc",
@@ -3878,7 +3878,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.3.0"
+version = "0.5.0"
 dependencies = [
  "napi",
  "napi-build",
@@ -3888,7 +3888,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.3.0"
+version = "0.5.0"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.3.0 → sqlrite-0.5.0}/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.3.0"
+version = "0.5.0"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"
@@ -138,4 +138,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.3", path = "sqlrite-ask", optional = true }
+sqlrite-ask = { version = "0.5.0", path = "sqlrite-ask", optional = true }

{sqlrite-0.3.0 → sqlrite-0.5.0}/PKG-INFO

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

{sqlrite-0.3.0 → sqlrite-0.5.0}/desktop/package.json

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

{sqlrite-0.3.0 → sqlrite-0.5.0}/docs/file-format.md

@@ -4,7 +4,7 @@ A SQLRite database is a single file, by convention named `*.sqlrite`. The file i
 
 All multi-byte integers in this format are **little-endian**.
 
-The current on-disk format is **version 4** (Phase 7) by default, with **version 5** written on demand whenever an FTS index is attached to the database (Phase 8c). Decoders accept both v4 and v5; writers preserve the existing version on no-op resaves so a v4 database without FTS stays v4. Files produced by versions 1 – 3 are rejected on open.
+The current on-disk format is **version 4** (Phase 7) by default, with **version 5** written on demand whenever an FTS index is attached to the database (Phase 8c) and **version 6** written on demand whenever a save produces a non-empty freelist (SQLR-6). Decoders accept v4, v5, and v6; writers preserve the existing version on no-op resaves so a v4 database without FTS or freelist stays v4. Files produced by versions 1 – 3 are rejected on open.
 
 ## Page 0 — the database header
 
@@ -15,17 +15,18 @@ The first 4096 bytes of every file are the header page. Only the first 28 bytes
 │ offset │ length │ content                                         │
 ├────────┼────────┼─────────────────────────────────────────────────┤
 │     0  │   16   │ magic:  "SQLRiteFormat\0\0\0"                   │
-│    16  │    2   │ format version (u16 LE) = 4 or 5                │
+│    16  │    2   │ format version (u16 LE) = 4, 5, or 6            │
 │    18  │    2   │ page size      (u16 LE) = 4096                  │
 │    20  │    4   │ total page count (u32 LE), includes page 0      │
 │    24  │    4   │ root page of sqlrite_master (u32 LE)            │
-│    28  │ 4068   │ reserved / zero                                 │
+│    28  │    4   │ freelist head    (u32 LE; 0 = empty) — v6 only  │
+│    32  │ 4064   │ reserved / zero                                 │
 └────────┴────────┴─────────────────────────────────────────────────┘
 ```
 
 The magic string is 14 ASCII bytes (`SQLRiteFormat`) padded with two NUL bytes to fill 16 bytes. It's deliberately different from SQLite's `"SQLite format 3\0"` so the two formats can't be confused on inspection.
 
-`decode_header` in [`src/sql/pager/header.rs`](../src/sql/pager/header.rs) validates all three of (magic, format version, page size) on open. A wrong magic produces `not a SQLRite database`; a wrong version or page size produces `unsupported ...` errors. The decoder accepts both v4 and v5 (anything else is rejected); the parsed `format_version` is propagated through the in-memory `DbHeader` so the writer can preserve it on resave when no version-bumping feature has been added.
+`decode_header` in [`src/sql/pager/header.rs`](../src/sql/pager/header.rs) validates all three of (magic, format version, page size) on open. A wrong magic produces `not a SQLRite database`; a wrong version or page size produces `unsupported ...` errors. The decoder accepts v4, v5, and v6 (anything else is rejected); the parsed `format_version` is propagated through the in-memory `DbHeader` so the writer can preserve it on resave when no version-bumping feature has been added. `freelist_head` is read from bytes [28..32]: v4/v5 files leave that region zero so it always decodes as `0` (an empty freelist), and v6 files store the page number of the first freelist trunk there.
 
 ## Pages 1..page_count — payload pages
 
@@ -53,6 +54,7 @@ Every non-header page starts with a 7-byte header:
 | `2` | `TableLeaf` | Holds a slot directory and a set of cells representing rows of a table. Leaves for one table are linked by sibling `next_page` pointers. |
 | `3` | `Overflow` | Continuation page carrying the spilled body of a single oversized cell. |
 | `4` | `InteriorNode` | Interior B-Tree node. Holds a slot directory of divider cells routing to child pages plus a rightmost-child pointer in the payload header. |
+| `5` | `FreelistTrunk` | One link of the persisted free-page list (SQLR-6). Payload carries `count: u16` followed by `count × u32` free leaf-page numbers; `next_page` chains to the next trunk (0 = end). |
 
 Tag `1` is reserved (it was `SchemaRoot` in format v1; unused in v2). Any other tag on open is a corruption error.
 
@@ -307,6 +309,7 @@ These are not all enforced on open — we validate the header strictly and rely
 - **v3** (Phase 3e) — `sqlrite_master` gains a `type` column; secondary indexes persist as their own cell-based B-Trees whose leaves carry `KIND_INDEX` cells.
 - **v4** (Phase 7a) — value block dispatch gains the `0x04 Vector` tag for the new `VECTOR(N)` column type. Per the [Phase 7 plan's Q8](phase-7-plan.md#q8-file-format-version-bump), later Phase 7 sub-phases (JSON storage, HNSW indexes) added their own value/cell tags inside this same v4 envelope. The `CREATE TABLE` SQL stored in `sqlrite_master` carries vector columns as `VECTOR(N)` in the type position; on open, the engine re-parses that SQL and reconstructs `DataType::Vector(N)` from the `Custom` AST node sqlparser produces.
 - **v5** (Phase 8c, current for FTS-bearing files) — adds the `KIND_FTS_POSTING` cell tag for persisted FTS posting lists. Bumped **on demand** per the [Phase 8 plan's Q10](phase-8-plan.md#q10-file-format-version-bump-strategy): existing v4 databases without FTS keep writing v4 across non-FTS saves; the first save with at least one FTS index attached promotes the file to v5. Decoders accept both v4 and v5; opening a v4 file with a build that supports v5 is a no-op until the user creates an FTS index.
+- **v6** (SQLR-6, current for files with persisted free-page lists) — adds the `freelist_head` field at header bytes [28..32] and the `FreelistTrunk` page tag (`5`). Bumped **on demand**: a save that ends with an empty freelist preserves the existing version; the first save that produces a non-empty freelist promotes the file to v6. Decoders accept v4, v5, and v6; v6 is a strict superset, so opening a v4/v5 file with a v6-aware build is a no-op until the user creates a freelist (e.g., by dropping a table or index). VACUUM clears the freelist but doesn't downgrade.
 
 The page header (7 bytes) and chaining mechanism are stable across future phases. Phase 4's WAL introduces a sibling file (`.sqlrite-wal`) rather than changing the main file format.
 

{sqlrite-0.3.0 → sqlrite-0.5.0}/docs/pager.md

@@ -187,10 +187,37 @@ Without the diff, step 3's "re-serialize every table" would trigger a full file
 
 This only works because `save_database` iterates tables in sorted order — if the order were random, a table that didn't change might land at a different page number, appearing dirty. See [Design decisions §7](design-decisions.md#7-deterministic-page-number-ordering-when-saving).
 
+## Free-page list and VACUUM (SQLR-6)
+
+Save now uses a [`PageAllocator`](../src/sql/pager/allocator.rs) instead of a bare `next_free_page` counter. The allocator pulls pages from three sources, in preference order:
+
+1. **Per-table preferred pool** — every table/index/master is given the page numbers it occupied last save (collected by walking from its old `rootpage`). An unchanged table re-stages byte-identical pages at the same numbers, so the diff pager skips every write for it.
+2. **Global freelist** — pages from dropped tables/indexes that are recorded in the persisted freelist (rooted at `header.freelist_head`).
+3. **Extend** — `next_extend++`, monotonic past the high-water mark.
+
+After staging, pages that were live before this save but didn't get restaged this round (e.g., the leaves of a dropped table) move onto the new freelist. The freelist itself is encoded into a chain of `FreelistTrunk` pages — each trunk holds up to 1021 free leaf-page numbers plus a `next_page` pointer to the following trunk. Trunks consume some of the free pages they describe (a trunk page IS a free page borrowed for metadata), so a freelist of N pages takes `ceil(N / 1022)` trunks and persists `N − T` leaf entries.
+
+`VACUUM;` (a SQL statement) calls [`vacuum_database`](../src/sql/pager/mod.rs), which is `save_database` with empty per-table preferred pools and an empty initial freelist. Allocation falls through to extend on every page → contiguous layout from page 1, no freelist trunks, file truncates to the new high-water mark on the next checkpoint.
+
+Format-version side effect: a save that produces a non-empty freelist promotes the file from v4/v5 to v6 (mirrors Phase 8c's v4→v5 FTS rule). VACUUM clears the freelist but doesn't downgrade — v6 is a strict superset.
+
+### Auto-VACUUM trigger (SQLR-10)
+
+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).
+
+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:
+
+- skips databases under `MIN_PAGES_FOR_AUTO_VACUUM` (16 pages = 64 KiB) so tiny files don't churn,
+- counts both leaf and trunk pages in the freelist (trunks are reclaimable bytes too),
+- returns `true` iff `(leaves + trunks) / page_count > threshold`.
+
+Auto-VACUUM is also skipped mid-transaction (no save → freelist is stale and the compact would publish in-flight work) and on in-memory databases (no file). The path bypasses `executor::execute_vacuum` — that wrapper builds a user-facing status string and rejects in-transaction calls, both wrong for a silent maintenance hook — and calls `vacuum_database` directly.
+
 ## What it doesn't do (yet)
 
 - **No LRU eviction.** `on_disk` + `wal_cache` together grow with the page count. For a 1 GiB database, that's ~1 GiB of page cache. Bounded cache is future work.
-- **No free-page management.** When a table shrinks, the main file's tail pages are truncated at checkpoint, but there's no free-list to reuse pages inside a grown file.
 - **No per-statement granularity.** The whole database is re-serialized on every commit; the diff keeps the *written* set small but the CPU cost of reserialization is unchanged.
 - **No concurrent reader-and-writer.** Phase 4e graduated to shared/exclusive lock modes (multi-reader *or* single-writer), but POSIX flock can't give us both at once. True concurrent access would need a shared-memory coordination file with read marks — not on the roadmap.
 - **Savepoints / nested transactions.** Phase 4f added top-level `BEGIN` / `COMMIT` / `ROLLBACK` (snapshot-based rollback, auto-save suppressed inside a transaction), but nested `BEGIN` is rejected — real savepoints aren't on the roadmap.

{sqlrite-0.3.0 → sqlrite-0.5.0}/docs/supported-sql.md

@@ -17,6 +17,7 @@ If you're looking for _how_ to use SQLRite (REPL flow, meta-commands, history, e
 | [`ALTER TABLE`](#alter-table) | `RENAME TO`, `RENAME COLUMN`, `ADD COLUMN`, `DROP COLUMN` (one operation per statement) |
 | [`DROP TABLE`](#drop-table) / [`DROP INDEX`](#drop-index) | `IF EXISTS`; single target; auto-indexes refused for `DROP INDEX` |
 | [`BEGIN`](#transactions) / [`COMMIT`](#transactions) / [`ROLLBACK`](#transactions) | Snapshot-based; single-level; WAL-backed commit; auto-rollback on COMMIT disk failure |
+| [`VACUUM`](#vacuum) | Compacts the file: rewrites every live B-Tree contiguously from page 1 and clears the freelist. Bare `VACUUM;` only — no modifiers. |
 
 Statements the parser accepts (because sqlparser understands them in the SQLite dialect) but SQLRite doesn't execute yet return `SQL Statement not supported yet`. The [Not yet supported](#not-yet-supported) section below enumerates the common ones.
 
@@ -259,7 +260,7 @@ DROP TABLE [IF EXISTS] <table>;
 - Reserved-name rejection: `DROP TABLE sqlrite_master` errors with the same message `CREATE TABLE` uses.
 - All indexes attached to the table (auto, explicit, HNSW, FTS) disappear with the table — they live inside the `Table` struct and ride along.
 - Without `IF EXISTS`, dropping a table that doesn't exist errors. With it, that's a benign 0-tables-dropped no-op.
-- **Disk pages are orphaned, not freed.** SQLRite has no free-list yet — the file size doesn't shrink until a future `VACUUM`. The behavior is safe (orphan pages are unreachable from `sqlrite_master` after reopen) but means a write-heavy schema churn won't reclaim space until VACUUM lands.
+- **Disk pages move onto the freelist.** Pages the dropped table occupied are pushed onto a persisted free-page list (SQLR-6) so subsequent `CREATE TABLE` or inserts can reuse them. The file shrinks automatically when the freelist crosses 25% of `page_count` (SQLR-10 auto-VACUUM, default-on); embedders that need the prior "manual `VACUUM;` only" behavior can call `Connection::set_auto_vacuum_threshold(None)` at open time.
 
 ---
 
@@ -428,6 +429,42 @@ ROLLBACK;  -- nothing was actually deleted
 
 ---
 
+## `VACUUM`
+
+```sql
+VACUUM;
+```
+
+Compacts the database file: rewrites every live table, index, HNSW graph, FTS posting tree, and `sqlrite_master` itself contiguously from page 1, drops the freelist, and lets the next checkpoint truncate the tail.
+
+- **Bare `VACUUM;` only.** Modifiers — `VACUUM FULL`, `VACUUM REINDEX`, table targets, `TO ... PERCENT`, `BOOST` — are parsed (sqlparser supports them) but rejected at execution with `VACUUM modifiers (FULL, REINDEX, table targets, etc.) are not supported`.
+- **Refused inside a transaction.** `BEGIN; VACUUM;` errors with `VACUUM cannot run inside a transaction`. Use `COMMIT;` first, then `VACUUM;`.
+- **No-op on in-memory databases.** Returns a `VACUUM is a no-op for in-memory databases` status string and does nothing — there's no file to compact.
+- **Status string** carries pages and bytes reclaimed: `VACUUM completed. <N> pages reclaimed (<B> bytes).`
+- **Format-version side effect.** A v4/v5 file that has been promoted to v6 by an earlier drop stays at v6 after VACUUM (v6 is a strict superset; we don't downgrade). A file that's already at v4/v5 because no drop ever happened on it doesn't get bumped by VACUUM.
+
+When to run it: any time after a string of `DROP TABLE` / `DROP INDEX` / `ALTER TABLE DROP COLUMN` operations if you care about file size. SQLRite reuses freelist pages on subsequent inserts, so a write-heavy workload may not need VACUUM at all — its main use is reclaiming space when you don't expect to grow back.
+
+### Auto-VACUUM (SQLR-10)
+
+Manual `VACUUM;` is rarely needed in practice: by default, every page-releasing DDL (`DROP TABLE`, `DROP INDEX`, `ALTER TABLE DROP COLUMN`) checks the freelist after committing and runs `vacuum_database` automatically when the freelist exceeds **25%** of `page_count` (SQLite parity). The trigger:
+
+- skips databases under 16 pages (64 KiB) so tiny files don't churn,
+- skips inside an explicit transaction (the freelist isn't accurate until `COMMIT`),
+- skips on in-memory and read-only databases.
+
+The threshold is tunable per-connection from Rust:
+
+```rust
+let mut conn = Connection::open("db.sqlrite")?;
+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).
+
+---
+
 ## Read-only databases
 
 A REPL launched with `sqlrite --readonly foo.sqlrite` (or `sqlrite::open_database_read_only(path, name)` programmatically) takes a shared POSIX advisory lock instead of an exclusive one. In that mode:

{sqlrite-0.3.0 → sqlrite-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlrite"
-version = "0.3.0"
+version = "0.5.0"
 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.3.0 → sqlrite-0.5.0}/scripts/bump-version.sh

@@ -6,8 +6,8 @@
 #     scripts/bump-version.sh 0.2.0
 #
 # Rewrites the version field in every manifest that carries one
-# (eight Cargo.toml / pyproject.toml files, plus three JSON manifests
-# — eleven files total). Then you run `cargo build` yourself to
+# (nine Cargo.toml / pyproject.toml files, plus three JSON manifests
+# — twelve files total). Then you run `cargo build` yourself to
 # refresh Cargo.lock. Idempotent: running twice with the same version
 # is a no-op; running twice with different versions lands on the
 # second.
@@ -84,6 +84,25 @@ for file in "${TOML_FILES[@]}"; do
     fi
     sed "s/^version = \"[^\"]*\"/version = \"${VERSION}\"/" "$file" > "$file.tmp"
     mv "$file.tmp" "$file"
+
+    # Inter-workspace dep pins — lines like:
+    #   sqlrite-ask = { version = "0.3", path = "sqlrite-ask", ... }
+    #   sqlrite     = { package = "sqlrite-engine", path = "..", version = "0.3", ... }
+    #
+    # These carry BOTH version and path because crates.io publishing
+    # rejects path-only deps (see PR #58 retrospective). The version
+    # field has to track the workspace bump or `cargo build` fails to
+    # resolve a candidate (SQLR-9; failed run for v0.3.0 hit exactly
+    # this — `failed to select a version for the requirement
+    # sqlrite-ask = "^0.2"`).
+    #
+    # Detection: any line containing both `version = "..."` and
+    # `path = "..."`. The package-level `^version = "..."` line at
+    # the top of each manifest has no `path` on it and can't match.
+    # Both inline-table orderings (version-first and path-first) work
+    # because sed acts per-line, not per-token-order.
+    sed -E '/path *= *"[^"]*"/ s/version *= *"[^"]*"/version = "'"${VERSION}"'"/' "$file" > "$file.tmp"
+    mv "$file.tmp" "$file"
 done
 
 # ---------------------------------------------------------------------------
@@ -147,6 +166,22 @@ for file in "${JSON_FILES[@]}"; do
     fi
 done
 
+# Inter-workspace pin sweep — any surviving `version = "X"` on a TOML
+# line that also has `path = "..."` and isn't already at $VERSION is a
+# pin we missed. Catches future refactors that change pin shape (e.g.
+# someone splits a long dep line across multiple TOML lines, where the
+# single-line address would no longer match).
+for file in "${TOML_FILES[@]}"; do
+    bad="$(grep -nE 'path *= *"[^"]*"' "$file" \
+           | grep -E 'version *= *"[^"]*"' \
+           | grep -vE "version *= *\"${VERSION}\"" || true)"
+    if [[ -n "$bad" ]]; then
+        echo "  ✗ $file — inter-workspace pin not at ${VERSION}:" >&2
+        echo "$bad" | sed 's/^/      /' >&2
+        FAILURES=$((FAILURES + 1))
+    fi
+done
+
 if [[ $FAILURES -gt 0 ]]; then
     echo
     echo "error: $FAILURES file(s) did not update as expected." >&2
@@ -157,5 +192,5 @@ fi
 echo
 echo "Done. Next steps:"
 echo "  cargo build    # refresh Cargo.lock with the new versions"
-echo "  git diff       # inspect the ten-file bump"
+echo "  git diff       # inspect the twelve-file bump"
 echo "  git checkout . # or back out if it looks wrong"

{sqlrite-0.3.0 → sqlrite-0.5.0}/sdk/python/Cargo.toml

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

{sqlrite-0.3.0 → sqlrite-0.5.0}/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.3.0"
+version = "0.5.0"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.3.0 → sqlrite-0.5.0}/src/connection.rs

@@ -153,6 +153,30 @@ impl Connection {
         self.db.in_transaction()
     }
 
+    /// Returns the current auto-VACUUM threshold (SQLR-10). After a
+    /// page-releasing DDL (DROP TABLE / DROP INDEX / ALTER TABLE DROP
+    /// COLUMN) commits, the engine compacts the file in place if the
+    /// freelist exceeds this fraction of `page_count`. New connections
+    /// default to `Some(0.25)` (SQLite parity); `None` means the
+    /// trigger is disabled. See [`Connection::set_auto_vacuum_threshold`].
+    pub fn auto_vacuum_threshold(&self) -> Option<f32> {
+        self.db.auto_vacuum_threshold()
+    }
+
+    /// Sets the auto-VACUUM threshold (SQLR-10). `Some(t)` with `t` in
+    /// `0.0..=1.0` arms the trigger; `None` disables it. Values outside
+    /// `0.0..=1.0` (or NaN / infinite) return a typed error rather than
+    /// silently saturating. The setting is per-connection runtime
+    /// state — closing the connection drops it; new connections start
+    /// at the default `Some(0.25)`.
+    ///
+    /// Calling this on an in-memory or read-only database is allowed
+    /// (it just won't fire — there's nothing to compact / no writes
+    /// will reach the trigger).
+    pub fn set_auto_vacuum_threshold(&mut self, threshold: Option<f32>) -> Result<()> {
+        self.db.set_auto_vacuum_threshold(threshold)
+    }
+
     /// Returns `true` if the connection was opened read-only. Mutating
     /// statements on a read-only connection return a typed error.
     pub fn is_read_only(&self) -> bool {
@@ -634,6 +658,37 @@ mod tests {
         assert!(format!("{err}").contains("SELECT"));
     }
 
+    /// SQLR-10: fresh connections expose the SQLite-parity 25% default,
+    /// the setter validates its input, and `None` opts out cleanly.
+    #[test]
+    fn auto_vacuum_threshold_default_and_setter() {
+        let mut conn = Connection::open_in_memory().unwrap();
+        assert_eq!(
+            conn.auto_vacuum_threshold(),
+            Some(0.25),
+            "fresh connection should ship with the SQLite-parity default"
+        );
+
+        conn.set_auto_vacuum_threshold(None).unwrap();
+        assert_eq!(conn.auto_vacuum_threshold(), None);
+
+        conn.set_auto_vacuum_threshold(Some(0.5)).unwrap();
+        assert_eq!(conn.auto_vacuum_threshold(), Some(0.5));
+
+        // Out-of-range values must be rejected with a typed error and
+        // must not stomp the previously-set value.
+        let err = conn.set_auto_vacuum_threshold(Some(1.5)).unwrap_err();
+        assert!(
+            format!("{err}").contains("auto_vacuum_threshold"),
+            "expected typed range error, got: {err}"
+        );
+        assert_eq!(
+            conn.auto_vacuum_threshold(),
+            Some(0.5),
+            "rejected setter call must not mutate the threshold"
+        );
+    }
+
     #[test]
     fn index_out_of_bounds_errors_cleanly() {
         let mut conn = Connection::open_in_memory().unwrap();

{sqlrite-0.3.0 → sqlrite-0.5.0}/src/sql/db/database.rs

@@ -14,6 +14,13 @@ pub struct TxnSnapshot {
     pub(crate) tables: HashMap<String, Table>,
 }
 
+/// Default fraction of free pages that triggers an auto-VACUUM after
+/// a page-releasing DDL (DROP TABLE / DROP INDEX / ALTER TABLE DROP
+/// COLUMN). Matches SQLite's classic 25% heuristic. Override per
+/// connection with [`Database::set_auto_vacuum_threshold`] (or
+/// `Connection::set_auto_vacuum_threshold`); pass `None` to disable.
+pub const DEFAULT_AUTO_VACUUM_THRESHOLD: f32 = 0.25;
+
 /// The database is represented by this structure.assert_eq!
 #[derive(Debug)]
 pub struct Database {
@@ -36,6 +43,14 @@ pub struct Database {
     /// - nested `BEGIN` is rejected
     /// - `ROLLBACK` restores `tables` from the snapshot
     pub txn: Option<TxnSnapshot>,
+    /// Auto-VACUUM trigger (SQLR-10). After a page-releasing DDL
+    /// (DROP TABLE / DROP INDEX / ALTER TABLE DROP COLUMN) commits and
+    /// flushes, if the freelist exceeds this fraction of `page_count`
+    /// the engine quietly compacts the file. `None` disables the
+    /// trigger; defaults to `Some(DEFAULT_AUTO_VACUUM_THRESHOLD)`
+    /// (SQLite parity at 25%). Per-connection runtime state — not
+    /// persisted across reopens.
+    pub auto_vacuum_threshold: Option<f32>,
 }
 
 impl Database {
@@ -54,9 +69,34 @@ impl Database {
             source_path: None,
             pager: None,
             txn: None,
+            auto_vacuum_threshold: Some(DEFAULT_AUTO_VACUUM_THRESHOLD),
         }
     }
 
+    /// Returns the current auto-VACUUM threshold, or `None` if disabled.
+    /// See [`Database::set_auto_vacuum_threshold`] for semantics.
+    pub fn auto_vacuum_threshold(&self) -> Option<f32> {
+        self.auto_vacuum_threshold
+    }
+
+    /// Sets the auto-VACUUM threshold (SQLR-10). `Some(t)` with `t` in
+    /// `0.0..=1.0` arms the trigger: after a page-releasing DDL
+    /// commits, if the freelist exceeds `t * page_count` the engine
+    /// runs a full-file compact. `None` disables the trigger. Values
+    /// outside `0.0..=1.0` (or NaN / infinite) return a typed error
+    /// rather than silently saturating.
+    pub fn set_auto_vacuum_threshold(&mut self, threshold: Option<f32>) -> Result<()> {
+        if let Some(t) = threshold {
+            if !t.is_finite() || !(0.0..=1.0).contains(&t) {
+                return Err(SQLRiteError::General(format!(
+                    "auto_vacuum_threshold must be in 0.0..=1.0, got {t}"
+                )));
+            }
+        }
+        self.auto_vacuum_threshold = threshold;
+        Ok(())
+    }
+
     /// Returns true if the database contains a table with the specified key as a table name.
     ///
     pub fn contains_table(&self, table_name: String) -> bool {

{sqlrite-0.3.0 → sqlrite-0.5.0}/src/sql/executor.rs

@@ -717,6 +717,60 @@ pub fn execute_alter_table(alter: AlterTable, db: &mut Database) -> Result<Strin
     }
 }
 
+/// Executes `VACUUM;` (SQLR-6). Compacts the database file: rewrites
+/// every live table, index, and the catalog contiguously from page 1,
+/// drops the freelist, and truncates the tail at the next checkpoint.
+///
+/// Refuses to run inside a transaction (would publish in-flight writes
+/// out of band); refuses on read-only databases (handled upstream by
+/// the read-only mutation gate); and is a no-op on in-memory databases
+/// (no file to compact). Bare `VACUUM;` only — non-default options
+/// (`FULL`, `REINDEX`, table targets, etc.) are rejected.
+pub fn execute_vacuum(db: &mut Database) -> Result<String> {
+    if db.in_transaction() {
+        return Err(SQLRiteError::General(
+            "VACUUM cannot run inside a transaction".to_string(),
+        ));
+    }
+    let path = match db.source_path.clone() {
+        Some(p) => p,
+        None => {
+            return Ok("VACUUM is a no-op for in-memory databases".to_string());
+        }
+    };
+    // Checkpoint before AND after VACUUM so the main-file size we report
+    // reflects only what VACUUM actually reclaimed — without the leading
+    // checkpoint, `size_before` would be the stale main-file snapshot
+    // (typically 2 pages) while WAL holds the live bytes, making the
+    // bytes-reclaimed delta meaningless.
+    if let Some(pager) = db.pager.as_mut() {
+        let _ = pager.checkpoint();
+    }
+    let size_before = std::fs::metadata(&path).ok().map(|m| m.len()).unwrap_or(0);
+    let pages_before = db
+        .pager
+        .as_ref()
+        .map(|p| p.header().page_count)
+        .unwrap_or(0);
+    crate::sql::pager::vacuum_database(db, &path)?;
+    // Second checkpoint so the main file shrinks now — VACUUM's whole
+    // purpose is to reclaim bytes, so paying the I/O up front is fair.
+    if let Some(pager) = db.pager.as_mut() {
+        let _ = pager.checkpoint();
+    }
+    let size_after = std::fs::metadata(&path).ok().map(|m| m.len()).unwrap_or(0);
+    let pages_after = db
+        .pager
+        .as_ref()
+        .map(|p| p.header().page_count)
+        .unwrap_or(0);
+    let pages_reclaimed = pages_before.saturating_sub(pages_after);
+    let bytes_reclaimed = size_before.saturating_sub(size_after);
+    Ok(format!(
+        "VACUUM completed. {pages_reclaimed} pages reclaimed ({bytes_reclaimed} bytes)."
+    ))
+}
+
 /// Renames a table in `db.tables`. Updates `tb_name`, every secondary
 /// index's `table_name` field, and any auto-index whose name embedded
 /// the old table name. HNSW / FTS index entries don't carry a