Add pragmas, hard_reset, and vacuum for tuning disk-backed caches

src/sqlmem/engine.py

@@ -65,6 +65,7 @@ class CachingEngine:
         refresh_interval: int | None = None,
         fetch_batch: int | None = None,
         dialect: str | None = None,
+        pragmas: dict[str, str | int] | None = None,
         blocking_startup_refresh: bool = False,
     ) -> None:
         self._source_engine = source_engine
@@ -79,6 +80,7 @@ class CachingEngine:
             in_memory=use_memory,
             dialect=self._dialect,
             fetch_batch=fetch_batch if fetch_batch is not None else FETCH_BATCH_SIZE,
+            pragmas=pragmas,
         )
         self._registry = ColumnRegistry(self._cache.connection)
         self._stats = StatsCollector()
@@ -267,6 +269,28 @@ class CachingEngine:
         self._cache.reset()
         logger.info("Cache reset — all tables will be reloaded on next use.")
 
+    def hard_reset(self) -> None:
+        """Delete the on-disk cache file and reopen with current pragmas/page_size.
+
+        Disk mode only (falls back to :meth:`reset` in memory mode). Use when a
+        layout pragma — ``page_size`` or ``auto_vacuum`` — must change, since
+        those are baked into the file at creation and :meth:`reset` keeps it.
+        All tables reload on next use.
+        """
+        self._cache.hard_reset()
+        # hard_reset swaps the cache connection — re-point the registry at it.
+        self._registry.rebind(self._cache.connection)
+        logger.info("Cache hard reset — file recreated; all tables reload on next use.")
+
+    def vacuum(self, incremental: bool = True, pages: int = 10_000) -> None:
+        """Run maintenance VACUUM on the on-disk cache (incremental by default).
+
+        Incremental reclaims free pages left by delta ``INSERT OR REPLACE`` churn
+        cheaply (requires ``auto_vacuum=INCREMENTAL``); a full VACUUM rewrites the
+        whole file and should run only in a maintenance window.
+        """
+        self._cache.vacuum(incremental=incremental, pages=pages)
+
     def close(self) -> None:
         self._cache.close()
         logger.info("CachingEngine closed.")