dirsql 0.3.93 → 0.3.94

package/docs/howto/persist.md

@@ -1,23 +1,34 @@
 # Keep the index across restarts
 
 By default the database is ephemeral: rebuilt from your files on every
-startup and discarded on exit. [`persist`](../reference/config.md#dirsql-keys) keeps the
-SQLite index on disk instead, so a restart only re-parses files that
-actually changed — the difference between seconds and milliseconds on large
-trees, and between re-running and skipping expensive
+startup and discarded on exit. The [`--persist [PATH]`](../reference/cli.md#server-mode)
+flag keeps the SQLite index on disk instead, so a restart only re-parses
+files that actually changed — the difference between seconds and
+milliseconds on large trees, and between re-running and skipping expensive
 [`on-file`](./extract-from-contents.md) commands.
 
+Whether and where to cache is a machine-local operational choice — it
+belongs to the command you run, not to the shared `.dirsql.toml`. That is
+why it is a CLI flag, not a config key.
+
 ## 1. Turn it on
 
-```toml
-[dirsql]
-persist = true
+```bash
+dirsql --persist
 ```
 
 That's the whole change. On the next run the cache is written to
 `.dirsql/cache.db` under the root; runs after that start from it. To put
-the cache elsewhere (a CI cache dir, a tmpfs), set
-[`persist_path`](../reference/config.md#dirsql-keys).
+the cache elsewhere (a CI cache dir, a tmpfs), pass a path:
+
+```bash
+dirsql --persist /var/cache/dirsql.db
+```
+
+The same flag works on [`dirsql query`](../reference/cli.md#dirsql-query);
+put a bare `--persist` after the SQL there so it does not consume the query
+argument. Embedding `dirsql`? The SDK constructors expose the same switch —
+see [_Embedding `dirsql`?_](#embedding-dirsql) below.
 
 ## 2. Keep the cache out of git
 

package/docs/reference/cli.md

@@ -48,6 +48,7 @@ requests, closes open `/events` streams, and exits.
 | `-c, --config <path>` | `./.dirsql.toml` | Path to the [config file](./config.md). The index is rooted at the directory containing this file (unless the config sets `[dirsql].root`). When the file does not exist, the server runs in [zero-config mode](#zero-config-mode). |
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
+| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches at `<root>/.dirsql/cache.db`; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Global — also honored by [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--extension <path>` | none | Load a SQLite extension by literal path, overriding the config's `[[dirsql.extension]]` entries. Repeatable. Format: `<path>` or `<path>::<entrypoint>`. Internal plumbing for the pip/npm launchers, which resolve package-name extensions and pass the resolved paths here — not intended for direct use. When any `--extension` is present, the config file's own extension entries are not loaded. |
 | `--version` | | Print the version and exit. |
 | `--help` | | Print usage and exit. |
@@ -119,6 +120,10 @@ uses**, so behavior is identical to `POST /query` by construction:
 - **Config discovery** honors `--config` (default `./.dirsql.toml`),
   [zero-config mode](#zero-config-mode), and `--extension` overrides,
   exactly as server mode does.
+- **`--persist [<path>]`** is honored, so a repeated `dirsql query` reuses the
+  on-disk cache. Because its value is optional, place a bare `--persist` after
+  the SQL (`dirsql query "SELECT …" --persist`) or use the `=` form
+  (`--persist=/path`) so it does not swallow the SQL argument.
 - **Hooks** ([`pre-query`](./hooks.md#pre-query) /
   [`post-query`](./hooks.md#post-query)) and the
   [`[dirsql].hook-timeout`](./config.md#dirsql-keys) apply identically.

package/docs/reference/config.md

@@ -11,7 +11,7 @@ The [CLI](./cli.md) loads `./.dirsql.toml` by default (`--config <path>`
 overrides). The [SDKs](./sdk.md) load a config via the `config` constructor
 parameter.
 
-**Path resolution.** Relative paths in the config (`root`, `persist_path`,
+**Path resolution.** Relative paths in the config (`root`,
 `[[dirsql.extension]]` `path`) resolve against the config file's parent
 directory. The scan root defaults to that same directory when `root` is not
 set.
@@ -22,8 +22,6 @@ set.
 |---|---|---|---|
 | `root` | string | config file's parent directory | Directory to index. Relative values resolve against the config file's parent. An explicit `root` passed to an SDK constructor overrides this (a warning is emitted on stderr). |
 | `ignore` | array of strings | `[]` | Glob patterns matched against root-relative paths. Matched files are skipped entirely — excluded from the initial scan and from watch events. |
-| `persist` | boolean | `false` | Keep the SQLite index on disk between runs. When `false`, the index is ephemeral: rebuilt from your files on every startup and discarded on exit. |
-| `persist_path` | string | `<root>/.dirsql/cache.db` | Location of the on-disk cache. Relative values resolve against the config file's parent. Ignored unless `persist = true`. |
 | `pre-query` | string | none | Server-wide command hook: the raw `POST /query` request body is passed to this command as `{args}`, and the plain-text SQL it prints is executed instead of parsing the body as `{"sql": …}`. CLI server only; the SDKs ignore it. Must be non-empty. See [Command hooks](./hooks.md#pre-query). |
 | `post-query` | string | none | Server-wide command hook: each successful `POST /query` result set is handed to this command (as a JSON array on stdin, and as `{args}` up to 96 KiB), and the JSON body it prints is returned instead of the bare row array. CLI server only; the SDKs ignore it. Must be non-empty. See [Command hooks](./hooks.md#post-query). |
 | `hook-timeout` | integer (seconds) | `30` | One global per-run timeout for every command hook — `on-file`, `pre-query`, and `post-query` alike. Positive whole seconds; zero and negative values are a config error. See [Command hooks](./hooks.md#timeout). |
@@ -38,11 +36,13 @@ directory.
 [dirsql]
 root = "../data"
 ignore = ["node_modules/**", ".git/**"]
-persist = true
-persist_path = ".dirsql/cache.db"   # the default; shown for illustration
 hook-timeout = 300
 ```
 
+Persistence is not a config key. Keep the SQLite index on disk between runs
+with the [`--persist [PATH]` CLI flag](./cli.md#server-mode) — a machine-local
+operational choice that belongs to the runner, not to shareable config.
+
 ## `[[dirsql.extension]]`
 
 Each entry declares a SQLite extension to load at startup. Extensions are
@@ -150,7 +150,6 @@ SDKs raise/reject) when:
 ```toml
 [dirsql]
 ignore = ["node_modules/**", ".git/**", "dist/**"]
-persist = true
 pre-query = "uv run python to_sql.py {args}"
 post-query = "jq -c '{results: .}'"
 hook-timeout = 120

package/docs/reference/sdk.md

@@ -111,11 +111,10 @@ directory" error.
 - `persist` — Keep the SQLite index on disk between runs (default off:
   ephemeral, rebuilt every startup). The cache lives at
   `<root>/.dirsql/cache.db` by default; on restart, only files whose stat
-  changed are re-parsed. `persist = true` in the config also enables it.
-- `persist_path` / `persistPath` — Override the cache location. An
-  explicit value wins over the config's `persist_path`. Ignored when
-  persistence is off. (Config-file values resolve relative to the config's
-  parent directory; constructor values are used as given.)
+  changed are re-parsed. (The CLI exposes the same switch as the
+  [`--persist [PATH]`](./cli.md#server-mode) flag; it is not a config key.)
+- `persist_path` / `persistPath` — Override the cache location. Ignored when
+  persistence is off. Constructor values are used as given.
 - `extensions` — SQLite extensions to load at startup, before any table
   DDL (enable → load → disable, so SQL `load_extension()` is never
   exposed). Each entry pairs a shared-library `path` with an optional

package/package.json

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