dirsql 0.4.16 → 0.4.17

package/docs/howto/persist.md

@@ -55,6 +55,19 @@ can't be trusted at all — the table/ignore configuration changed, or the
 automatically. You never need to delete it by hand; a full rebuild costs
 exactly what a non-persistent startup does.
 
+A run that changes nothing writes nothing: the cache file is read and left
+exactly as it was.
+
+This covers both kinds of table. Declared tables keep their indexed rows, and
+a [path-table](../reference/path-tables.md) parsed with `--on-file` keeps each
+file's parser output — so the second run over an unchanged tree spawns no
+parser process at all. A path-table's cached rows are keyed by the tree, the
+glob, the parser command and the `dirsql` version together, so changing any of
+them parses afresh rather than serving rows the current command never
+produced. A *stat* path-table caches nothing, because there is nothing to
+save: its columns are the metadata the scan already collected, and `content`
+is read live by design.
+
 Persistence is a startup-time optimization, not a change in meaning: the
 database remains a derived view of your files, and queries return the same
 rows either way ([how `dirsql` thinks](../explanation.md)).

package/docs/reference/path-tables.md

@@ -140,6 +140,12 @@ the table:
   scan continues. The schema is inferred from the files that did parse.
 - **The skip rules still apply.** A parsed scan honors the same `node_modules`
   /`.git`/`ignore` rules a stat scan does (see below).
+- **`--persist` skips the parser for unchanged files.** With a
+  [persistent cache](/howto/persist), each file's parser output is stored
+  against its stat metadata, so a later run over an unchanged tree serves the
+  rows from the cache and spawns no process. Change the file, the glob, the
+  parser command, or the dirsql version and that file (or that whole table) is
+  parsed again.
 
 `--on-file` applies to **every** path-table in the query and may be given **at
 most once**. For different parsers per file set, define named tables in a
@@ -160,15 +166,17 @@ deleted *after* the scan finds it but *before* its `content` is read yields
 than failing the query. This is an accepted consequence of reading live, not a
 bug to design around.
 
-Path-tables are per-connection and are never written to a persistent cache, so
-they cannot leak into `sqlite_master` or survive a restart. The reserved
-top-level `.dirsql/` directory is excluded from the scan, as everywhere else.
+The table itself is per-connection: it lives in `temp`, so it cannot leak into
+`sqlite_master` or survive a restart. Under `--persist` a *parsed* table's rows
+outlive the connection in the cache (above), but the table is still minted
+fresh each run and the scan still decides what exists. The reserved top-level
+`.dirsql/` directory is excluded from the scan, as everywhere else.
 
 ### When to promote to a declared table
 
-Every query re-scans the filesystem: a path-table has no index, no watcher, and
-no persistent cache. That is the right trade for a hundreds-of-files, run-it-once
-question. When the same tree is queried repeatedly, or is large, declare a
+Every query re-scans the filesystem: a path-table has no index and no watcher.
+That is the right trade for a hundreds-of-files, run-it-once question. When the
+same tree is queried repeatedly, or is large, declare a
 [table](/reference/config) for it instead — a declared table is indexed on
 build, kept fresh by the watcher, and (with `--persist`) survives restarts, so
 its rows are read from SQLite rather than re-walked each time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -213,10 +213,10 @@
     ]
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.4.16",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.16",
-    "@dirsql/lib-darwin-x64": "0.4.16",
-    "@dirsql/lib-darwin-arm64": "0.4.16",
-    "@dirsql/lib-win32-x64-msvc": "0.4.16"
+    "@dirsql/lib-linux-x64-gnu": "0.4.17",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.17",
+    "@dirsql/lib-darwin-x64": "0.4.17",
+    "@dirsql/lib-darwin-arm64": "0.4.17",
+    "@dirsql/lib-win32-x64-msvc": "0.4.17"
   }
 }