sqlrite 0.4.0__tar.gz → 0.5.1__tar.gz

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

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

{sqlrite-0.4.0 → sqlrite-0.5.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.4.0"
+version = "0.5.1"
 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.1", path = "sqlrite-ask", optional = true }

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

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

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

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

{sqlrite-0.4.0 → sqlrite-0.5.1}/docs/file-format.md

@@ -139,6 +139,8 @@ body           variable        depends on kind_tag
 
 The shared prefix means `Cell::peek_rowid` works uniformly across all kinds — useful for binary search over a page's slot directory without decoding full bodies.
 
+**Decoder dispatch is per-B-tree, not per-cell.** Each B-Tree owns one cell kind on its leaves: table B-Trees carry `Local`/`Overflow` cells (decoded via `PagedEntry::decode`), secondary-index B-Trees carry `Index` cells (`IndexCell::decode`), HNSW carries `HNSW` cells (`HnswNodeCell::decode`), FTS carries `FTS Posting` cells (`FtsPostingCell::decode`), and every interior node — regardless of the leaf kind below it — carries `Interior` divider cells (`InteriorCell::decode`). Callers must dispatch on the *page's owning B-Tree*, not on the kind tag they happen to see; pointing the wrong decoder at a leaf yields an `Internal` error that names both the offending kind and the B-Tree it belongs to (SQLR-1).
+
 ### Local cell body
 
 ```

{sqlrite-0.4.0 → sqlrite-0.5.1}/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.1}/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.1}/pyproject.toml

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

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

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

{sqlrite-0.4.0 → sqlrite-0.5.1}/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.1}/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.1}/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.1}/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::*;