sqlrite 0.4.0__tar.gz → 0.5.0__tar.gz

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

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

{sqlrite-0.4.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.4.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.4.0", path = "sqlrite-ask", optional = true }
+sqlrite-ask = { version = "0.5.0", path = "sqlrite-ask", optional = true }

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

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

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

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

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

@@ -201,6 +201,20 @@ After staging, pages that were live before this save but didn't get restaged thi
 
 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.

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

@@ -260,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 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 doesn't shrink until [`VACUUM;`](#vacuum) compacts it.
+- **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.
 
 ---
 
@@ -445,6 +445,24 @@ Compacts the database file: rewrites every live table, index, HNSW graph, FTS po
 
 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

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlrite"
-version = "0.4.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.4.0 → sqlrite-0.5.0}/sdk/python/Cargo.toml

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

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

{sqlrite-0.4.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.4.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.4.0 → sqlrite-0.5.0}/src/sql/mod.rs

@@ -10,7 +10,7 @@ use parser::create::CreateQuery;
 use parser::insert::InsertQuery;
 use parser::select::SelectQuery;
 
-use sqlparser::ast::{ObjectType, Statement};
+use sqlparser::ast::{AlterTableOperation, ObjectType, Statement};
 use sqlparser::dialect::SQLiteDialect;
 use sqlparser::parser::{Parser, ParserError};
 
@@ -176,6 +176,22 @@ pub fn process_command_with_render(query: &str, db: &mut Database) -> Result<Com
     );
     let is_vacuum = matches!(&query, Statement::Vacuum(_));
 
+    // SQLR-10: statements that release pages onto the freelist.
+    // After the auto-save flushes them, we'll consult
+    // `db.auto_vacuum_threshold` and possibly compact in place.
+    // ALTER TABLE here matches only DROP COLUMN — RENAME / ADD COLUMN
+    // don't grow the freelist, so they shouldn't pay the trigger cost.
+    let releases_pages = match &query {
+        Statement::Drop { object_type, .. } => {
+            matches!(object_type, ObjectType::Table | ObjectType::Index)
+        }
+        Statement::AlterTable(alter) => alter
+            .operations
+            .iter()
+            .any(|op| matches!(op, AlterTableOperation::DropColumn { .. })),
+        _ => false,
+    };
+
     // Early-reject mutations on a read-only database before they touch
     // in-memory state. Phase 4e: without this, a user running INSERT
     // on a `--readonly` REPL would see the row appear in the printed
@@ -389,6 +405,30 @@ pub fn process_command_with_render(query: &str, db: &mut Database) -> Result<Com
         pager::save_database(db, &path)?;
     }
 
+    // SQLR-10 auto-VACUUM trigger. Runs *after* the auto-save above so
+    // the orphaned pages from the just-executed DROP/ALTER have actually
+    // landed on the freelist (the bottom-up rebuild populates it during
+    // save). Skipped mid-transaction (no commit yet → no save → freelist
+    // is stale), on in-memory DBs (nothing to compact), and when the
+    // user has explicitly disabled the trigger via
+    // `set_auto_vacuum_threshold(None)`. We deliberately bypass
+    // `executor::execute_vacuum` and call `pager::vacuum_database`
+    // directly: the executor wrapper builds a user-facing status string
+    // and rejects in-transaction calls — both wrong for this silent
+    // maintenance path.
+    if releases_pages && !db.in_transaction() {
+        if let (Some(threshold), Some(path)) = (db.auto_vacuum_threshold(), db.source_path.clone())
+        {
+            let should = match db.pager.as_ref() {
+                Some(p) => pager::freelist::should_auto_vacuum(p, threshold)?,
+                None => false,
+            };
+            if should {
+                pager::vacuum_database(db, &path)?;
+            }
+        }
+    }
+
     Ok(CommandOutput {
         status: message,
         rendered,

{sqlrite-0.4.0 → sqlrite-0.5.0}/src/sql/pager/freelist.rs

@@ -202,6 +202,39 @@ pub fn freelist_to_deque(leaves: Vec<u32>) -> VecDeque<u32> {
     VecDeque::from(sorted)
 }
 
+/// Auto-VACUUM (SQLR-10) does not fire on databases below this many
+/// pages. The 4 KiB page size makes 16 pages = 64 KiB — small enough
+/// that the cost of a full-file rewrite is negligible if the user
+/// genuinely wants it (manual `VACUUM;` still works), but large enough
+/// that single-table churn doesn't blow past the threshold and trigger
+/// a noisy compact every few statements.
+pub const MIN_PAGES_FOR_AUTO_VACUUM: u32 = 16;
+
+/// Returns `true` if the on-disk freelist (counting both leaf and
+/// trunk pages — they're all reclaimable bytes) exceeds `threshold`
+/// of `header.page_count`, i.e. the file is bloated enough to be
+/// worth compacting. Returns `false` for tiny databases (under
+/// [`MIN_PAGES_FOR_AUTO_VACUUM`]) and for empty freelists, both as
+/// fast paths to keep the auto-VACUUM hook cheap on the common case.
+///
+/// This is a read-only inspection of the pager's current header and
+/// freelist chain — it does not mutate any state. The caller is
+/// responsible for actually invoking
+/// [`crate::sql::pager::vacuum_database`] when this returns `true`.
+pub fn should_auto_vacuum(pager: &Pager, threshold: f32) -> Result<bool> {
+    let header = pager.header();
+    if header.page_count < MIN_PAGES_FOR_AUTO_VACUUM {
+        return Ok(false);
+    }
+    if header.freelist_head == 0 {
+        return Ok(false);
+    }
+    let (leaves, trunks) = read_freelist(pager, header.freelist_head)?;
+    let free_pages = leaves.len() + trunks.len();
+    let ratio = free_pages as f32 / header.page_count as f32;
+    Ok(ratio > threshold)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

{sqlrite-0.4.0 → sqlrite-0.5.0}/src/sql/pager/mod.rs

@@ -1896,6 +1896,7 @@ fn emit_interior(pager: &mut Pager, page_num: u32, interior: &InteriorPage) {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::sql::pager::freelist::MIN_PAGES_FOR_AUTO_VACUUM;
     use crate::sql::process_command;
 
     fn seed_db() -> Database {
@@ -3308,6 +3309,306 @@ mod tests {
         cleanup(&path);
     }
 
+    // ---- SQLR-10: auto-VACUUM trigger after page-releasing DDL ----
+
+    /// Builds a file-backed DB with one small "keep" table and one
+    /// large "bloat" table, sized so the post-drop freelist will
+    /// comfortably cross the default 25% threshold and the
+    /// `MIN_PAGES_FOR_AUTO_VACUUM` floor (16 pages). Used by the
+    /// auto-VACUUM happy-path tests.
+    fn auto_vacuum_setup(path: &std::path::Path) -> Database {
+        let mut db = Database::new("av".to_string());
+        db.source_path = Some(path.to_path_buf());
+        process_command(
+            "CREATE TABLE keep (id INTEGER PRIMARY KEY, n INTEGER);",
+            &mut db,
+        )
+        .unwrap();
+        process_command("INSERT INTO keep (n) VALUES (1);", &mut db).unwrap();
+        process_command(
+            "CREATE TABLE bloat (id INTEGER PRIMARY KEY, payload TEXT);",
+            &mut db,
+        )
+        .unwrap();
+        // Wrap the bulk insert in a transaction so we pay one save at
+        // COMMIT instead of 5000 round-trips through auto-save.
+        process_command("BEGIN;", &mut db).unwrap();
+        for i in 0..5000 {
+            process_command(
+                &format!("INSERT INTO bloat (payload) VALUES ('p-{i:08}');"),
+                &mut db,
+            )
+            .unwrap();
+        }
+        process_command("COMMIT;", &mut db).unwrap();
+        db
+    }
+
+    /// Default threshold (0.25) is engaged for fresh `Database`s and
+    /// fires when a `DROP TABLE` orphans enough pages — file shrinks
+    /// without anyone calling `VACUUM;`.
+    #[test]
+    fn auto_vacuum_default_threshold_triggers_on_drop_table() {
+        let path = tmp_path("av_default_drop_table");
+        let mut db = auto_vacuum_setup(&path);
+        // Sanity: setup respects the shipped default.
+        assert_eq!(db.auto_vacuum_threshold(), Some(0.25));
+
+        // Checkpoint before measuring `size_before` so the bloat actually
+        // lives in the main file and not just the WAL — otherwise
+        // `size_before` is the bare 2-page header and any post-vacuum
+        // checkpoint will look like the file *grew*.
+        if let Some(p) = db.pager.as_mut() {
+            let _ = p.checkpoint();
+        }
+        let pages_before = db.pager.as_ref().unwrap().header().page_count;
+        let size_before = std::fs::metadata(&path).unwrap().len();
+        assert!(
+            pages_before >= MIN_PAGES_FOR_AUTO_VACUUM,
+            "setup should produce >= MIN_PAGES_FOR_AUTO_VACUUM ({MIN_PAGES_FOR_AUTO_VACUUM}) \
+             pages so the floor doesn't suppress the trigger; got {pages_before}"
+        );
+
+        // Drop the bloat table — freelist should pass 25% of page_count
+        // and the auto-VACUUM hook should compact in place. Note: no
+        // explicit `VACUUM;` statement is issued.
+        process_command("DROP TABLE bloat;", &mut db).expect("drop");
+
+        let pages_after = db.pager.as_ref().unwrap().header().page_count;
+        let head_after = db.pager.as_ref().unwrap().header().freelist_head;
+        // Second checkpoint so the post-vacuum file shrinks on disk
+        // (auto-VACUUM stages the compact through WAL just like manual
+        // VACUUM does).
+        if let Some(p) = db.pager.as_mut() {
+            let _ = p.checkpoint();
+        }
+        let size_after = std::fs::metadata(&path).unwrap().len();
+
+        assert!(
+            pages_after < pages_before,
+            "auto-VACUUM must reduce page_count: was {pages_before}, now {pages_after}"
+        );
+        assert_eq!(head_after, 0, "auto-VACUUM must clear the freelist");
+        assert!(
+            size_after < size_before,
+            "auto-VACUUM must shrink the file on disk: was {size_before}, now {size_after}"
+        );
+
+        cleanup(&path);
+    }
+
+    /// Setting the threshold to `None` disables the trigger entirely:
+    /// the same workload that shrinks under the default leaves the file
+    /// at its high-water mark.
+    #[test]
+    fn auto_vacuum_disabled_keeps_file_at_hwm() {
+        let path = tmp_path("av_disabled");
+        let mut db = auto_vacuum_setup(&path);
+        db.set_auto_vacuum_threshold(None).expect("disable");
+        assert_eq!(db.auto_vacuum_threshold(), None);
+
+        let pages_before = db.pager.as_ref().unwrap().header().page_count;
+
+        process_command("DROP TABLE bloat;", &mut db).expect("drop");
+
+        let pages_after = db.pager.as_ref().unwrap().header().page_count;
+        let head_after = db.pager.as_ref().unwrap().header().freelist_head;
+        assert_eq!(
+            pages_after, pages_before,
+            "with auto-VACUUM disabled, drop must keep page_count at the HWM"
+        );
+        assert!(
+            head_after != 0,
+            "drop must still populate the freelist (manual VACUUM would be needed to reclaim)"
+        );
+
+        cleanup(&path);
+    }
+
+    /// `DROP INDEX` is the second of three page-releasing DDL paths
+    /// covered by SQLR-10. We bloat the freelist via a separate
+    /// `DROP TABLE` first (with auto-VACUUM disabled so it doesn't
+    /// compact early), then re-arm the trigger and drop a small index
+    /// — the cumulative freelist crosses 25% on the index drop and
+    /// auto-VACUUM fires.
+    ///
+    /// The detour around bloat is necessary because building a
+    /// secondary index on a 5000-row column would need multi-level
+    /// interior nodes, and the cell-decoder's interior-page support
+    /// is a separate work item from SQLR-10.
+    #[test]
+    fn auto_vacuum_triggers_on_drop_index() {
+        let path = tmp_path("av_drop_index");
+        let mut db = auto_vacuum_setup(&path);
+
+        // Phase 1: drop the bloat table with auto-VACUUM disabled so
+        // its pages land on the freelist without being reclaimed.
+        db.set_auto_vacuum_threshold(None).expect("disable");
+        process_command("DROP TABLE bloat;", &mut db).expect("drop bloat");
+        let pages_after_bloat_drop = db.pager.as_ref().unwrap().header().page_count;
+        let head_after_bloat_drop = db.pager.as_ref().unwrap().header().freelist_head;
+        assert!(
+            head_after_bloat_drop != 0,
+            "bloat drop must populate the freelist (else later index drop won't trip the threshold)"
+        );
+
+        // Phase 2: a small index on the surviving `keep` table. The
+        // index reuses one page from the freelist (which is fine —
+        // freelist still holds plenty more).
+        process_command("CREATE INDEX idx_keep_n ON keep (n);", &mut db).expect("create idx");
+
+        // Phase 3: re-arm the trigger and drop the index. The freelist
+        // is already heavily populated from phase 1; this drop just
+        // adds the index page on top, keeping the ratio well above
+        // 25%, so auto-VACUUM should fire.
+        db.set_auto_vacuum_threshold(Some(0.25)).expect("re-arm");
+        process_command("DROP INDEX idx_keep_n;", &mut db).expect("drop index");
+
+        let pages_after = db.pager.as_ref().unwrap().header().page_count;
+        let head_after = db.pager.as_ref().unwrap().header().freelist_head;
+        assert!(
+            pages_after < pages_after_bloat_drop,
+            "DROP INDEX should fire auto-VACUUM and reduce page_count: \
+             was {pages_after_bloat_drop}, now {pages_after}"
+        );
+        assert_eq!(
+            head_after, 0,
+            "auto-VACUUM after DROP INDEX must clear the freelist"
+        );
+
+        cleanup(&path);
+    }
+
+    /// `ALTER TABLE … DROP COLUMN` releases pages too — the third path
+    /// the SQLR-10 trigger covers.
+    #[test]
+    fn auto_vacuum_triggers_on_alter_drop_column() {
+        let path = tmp_path("av_alter_drop_col");
+        let mut db = auto_vacuum_setup(&path);
+        let pages_before = db.pager.as_ref().unwrap().header().page_count;
+
+        // Drop the wide `payload` column — this rewrites every row in
+        // `bloat` without the column, so the old leaf pages get freed.
+        process_command("ALTER TABLE bloat DROP COLUMN payload;", &mut db).expect("alter drop");
+
+        let pages_after = db.pager.as_ref().unwrap().header().page_count;
+        assert!(
+            pages_after < pages_before,
+            "ALTER TABLE DROP COLUMN should fire auto-VACUUM and reduce page_count: \
+             was {pages_before}, now {pages_after}"
+        );
+        assert_eq!(db.pager.as_ref().unwrap().header().freelist_head, 0);
+
+        cleanup(&path);
+    }
+
+    /// A high threshold (0.99) suppresses the trigger when the freelist
+    /// ratio is well below it — the file stays at HWM.
+    #[test]
+    fn auto_vacuum_skips_below_threshold() {
+        let path = tmp_path("av_below_threshold");
+        let mut db = auto_vacuum_setup(&path);
+        db.set_auto_vacuum_threshold(Some(0.99)).expect("set");
+
+        let pages_before = db.pager.as_ref().unwrap().header().page_count;
+
+        process_command("DROP TABLE bloat;", &mut db).expect("drop");
+
+        let pages_after = db.pager.as_ref().unwrap().header().page_count;
+        assert_eq!(
+            pages_after, pages_before,
+            "freelist ratio after a single drop is far below 0.99 — \
+             page_count must stay at the HWM"
+        );
+        assert!(
+            db.pager.as_ref().unwrap().header().freelist_head != 0,
+            "drop must still populate the freelist"
+        );
+
+        cleanup(&path);
+    }
+
+    /// Inside an explicit transaction, the page-releasing DDL doesn't
+    /// flush to disk yet — the freelist isn't accurate, so the trigger
+    /// must skip. The compact would also publish in-flight work out of
+    /// band, which is exactly what the manual `VACUUM;` rejection
+    /// inside a txn already prevents.
+    #[test]
+    fn auto_vacuum_skips_inside_transaction() {
+        let path = tmp_path("av_in_txn");
+        let mut db = auto_vacuum_setup(&path);
+        let pages_before = db.pager.as_ref().unwrap().header().page_count;
+
+        process_command("BEGIN;", &mut db).expect("begin");
+        process_command("DROP TABLE bloat;", &mut db).expect("drop in txn");
+        // Mid-transaction: no save has occurred, so the on-disk
+        // freelist_head must be unchanged and page_count must not have
+        // shifted from a sneaky compact.
+        let pages_mid = db.pager.as_ref().unwrap().header().page_count;
+        assert_eq!(
+            pages_mid, pages_before,
+            "auto-VACUUM must not fire mid-transaction"
+        );
+
+        process_command("ROLLBACK;", &mut db).expect("rollback");
+        cleanup(&path);
+    }
+
+    /// Tiny databases (under `MIN_PAGES_FOR_AUTO_VACUUM`) skip the
+    /// trigger even if the ratio would otherwise qualify — the cost of
+    /// rewriting a 64 KiB file isn't worth the few bytes reclaimed.
+    #[test]
+    fn auto_vacuum_skips_under_min_pages_floor() {
+        let path = tmp_path("av_under_floor");
+        let mut db = seed_db(); // small: just users + notes, ~5 pages
+        db.source_path = Some(path.clone());
+        save_database(&mut db, &path).expect("save");
+        // Confirm we're below the floor so the test is meaningful.
+        let pages_before = db.pager.as_ref().unwrap().header().page_count;
+        assert!(
+            pages_before < MIN_PAGES_FOR_AUTO_VACUUM,
+            "test setup is too large: floor would not apply (got {pages_before} pages, \
+             floor is {MIN_PAGES_FOR_AUTO_VACUUM})"
+        );
+
+        process_command("DROP TABLE users;", &mut db).expect("drop");
+
+        let pages_after = db.pager.as_ref().unwrap().header().page_count;
+        assert_eq!(
+            pages_after, pages_before,
+            "below MIN_PAGES_FOR_AUTO_VACUUM, drop must not trigger compaction"
+        );
+        assert!(
+            db.pager.as_ref().unwrap().header().freelist_head != 0,
+            "drop must still populate the freelist normally"
+        );
+
+        cleanup(&path);
+    }
+
+    /// Setter rejects NaN, infinities, and values outside `0.0..=1.0`
+    /// rather than silently saturating.
+    #[test]
+    fn set_auto_vacuum_threshold_rejects_out_of_range() {
+        let mut db = Database::new("t".to_string());
+        for bad in [-0.01_f32, 1.01, f32::NAN, f32::INFINITY, f32::NEG_INFINITY] {
+            let err = db.set_auto_vacuum_threshold(Some(bad)).unwrap_err();
+            assert!(
+                format!("{err}").contains("auto_vacuum_threshold"),
+                "expected a typed range error for {bad}, got: {err}"
+            );
+        }
+        // The default survives the rejected sets unchanged.
+        assert_eq!(db.auto_vacuum_threshold(), Some(0.25));
+        // And valid values land.
+        db.set_auto_vacuum_threshold(Some(0.0)).unwrap();
+        assert_eq!(db.auto_vacuum_threshold(), Some(0.0));
+        db.set_auto_vacuum_threshold(Some(1.0)).unwrap();
+        assert_eq!(db.auto_vacuum_threshold(), Some(1.0));
+        db.set_auto_vacuum_threshold(None).unwrap();
+        assert_eq!(db.auto_vacuum_threshold(), None);
+    }
+
     /// VACUUM modifiers (FULL, REINDEX, table targets, …) are rejected
     /// with NotImplemented — only bare `VACUUM;` is supported.
     #[test]