dirsql 0.3.88__tar.gz → 0.3.90__tar.gz

{dirsql-0.3.88 → dirsql-0.3.90}/Cargo.lock

@@ -500,7 +500,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.88"
+version = "0.3.90"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.88 → dirsql-0.3.90}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.88
+Version: 0.3.90
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index
 Author: Kevin Scott

{dirsql-0.3.88/packages/python → dirsql-0.3.90}/docs/howto/extract-from-contents.md

@@ -23,7 +23,7 @@ glob    = "books/*.json"
 on-file = "jq -c '[{title, author, year}]' {path}"
 ```
 
-`{path}` is the matched file, relative to the index root — one of the
+`{path}` is the matched file's absolute path — one of the
 placeholders defined by the
 [command hook contract](../reference/hooks.md#on-file), which also covers
 the argv splitting, working directory, stdout protocol, and timeout shared

{dirsql-0.3.88/packages/rust → dirsql-0.3.90}/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
 

{dirsql-0.3.88/packages/rust → dirsql-0.3.90}/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.

{dirsql-0.3.88/packages/rust → dirsql-0.3.90}/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

{dirsql-0.3.88/packages/rust → dirsql-0.3.90}/docs/reference/hooks.md

@@ -101,8 +101,8 @@ row-mapping rules.
 
 | Placeholder | Value |
 |---|---|
-| `{path}` | The matched file's path **relative to the index root**. `on-file = "extract.py {path}"` |
-| `{root}` | The index root directory. |
+| `{path}` | The matched file's **absolute** path. `on-file = "extract.py {path}"` — self-sufficient from any working directory, so the command resolves it even when the config lives outside the index. |
+| `{root}` | The index root directory. Derive a root-relative path with `relpath({path}, {root})`. |
 
 ### `pre-query`
 

{dirsql-0.3.88 → dirsql-0.3.90}/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

{dirsql-0.3.88 → dirsql-0.3.90}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.3.88"
+version = "0.3.90"
 # abi3 note: the `abi3-py311` pyo3 feature (below) builds ONE stable-ABI
 # `cp311-abi3` wheel per platform that loads on every CPython >= 3.11
 # (matching `pyproject.toml`'s `requires-python = ">=3.11"`), instead of

{dirsql-0.3.88/packages/rust → dirsql-0.3.90/packages/python}/docs/howto/extract-from-contents.md

@@ -23,7 +23,7 @@ glob    = "books/*.json"
 on-file = "jq -c '[{title, author, year}]' {path}"
 ```
 
-`{path}` is the matched file, relative to the index root — one of the
+`{path}` is the matched file's absolute path — one of the
 placeholders defined by the
 [command hook contract](../reference/hooks.md#on-file), which also covers
 the argv splitting, working directory, stdout protocol, and timeout shared

{dirsql-0.3.88 → dirsql-0.3.90}/packages/python/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
 

{dirsql-0.3.88 → dirsql-0.3.90/packages/python}/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.

{dirsql-0.3.88 → dirsql-0.3.90/packages/python}/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

{dirsql-0.3.88 → dirsql-0.3.90}/packages/python/docs/reference/hooks.md

@@ -101,8 +101,8 @@ row-mapping rules.
 
 | Placeholder | Value |
 |---|---|
-| `{path}` | The matched file's path **relative to the index root**. `on-file = "extract.py {path}"` |
-| `{root}` | The index root directory. |
+| `{path}` | The matched file's **absolute** path. `on-file = "extract.py {path}"` — self-sufficient from any working directory, so the command resolves it even when the config lives outside the index. |
+| `{root}` | The index root directory. Derive a root-relative path with `relpath({path}, {root})`. |
 
 ### `pre-query`
 

{dirsql-0.3.88/packages/rust → dirsql-0.3.90/packages/python}/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

{dirsql-0.3.88 → dirsql-0.3.90}/packages/python/e2e-attestation.json

@@ -1,6 +1,6 @@
 {
   "command": "uv run python -m pytest tests/e2e/ -x -q",
-  "ran_at": 1783633566,
+  "ran_at": 1783637710,
   "exit_code": 0,
-  "commit": "8c54e97f3b78c679885b4a2fd7b7d0f8a543001b"
+  "commit": "c7c626ca03beb1b23e26ab96febf3c9df5d4a67f"
 }

{dirsql-0.3.88 → dirsql-0.3.90/packages/rust}/docs/howto/extract-from-contents.md

@@ -23,7 +23,7 @@ glob    = "books/*.json"
 on-file = "jq -c '[{title, author, year}]' {path}"
 ```
 
-`{path}` is the matched file, relative to the index root — one of the
+`{path}` is the matched file's absolute path — one of the
 placeholders defined by the
 [command hook contract](../reference/hooks.md#on-file), which also covers
 the argv splitting, working directory, stdout protocol, and timeout shared

{dirsql-0.3.88 → dirsql-0.3.90/packages/rust}/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
 

{dirsql-0.3.88/packages/python → dirsql-0.3.90/packages/rust}/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.

{dirsql-0.3.88/packages/python → dirsql-0.3.90/packages/rust}/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

{dirsql-0.3.88 → dirsql-0.3.90/packages/rust}/docs/reference/hooks.md

@@ -101,8 +101,8 @@ row-mapping rules.
 
 | Placeholder | Value |
 |---|---|
-| `{path}` | The matched file's path **relative to the index root**. `on-file = "extract.py {path}"` |
-| `{root}` | The index root directory. |
+| `{path}` | The matched file's **absolute** path. `on-file = "extract.py {path}"` — self-sufficient from any working directory, so the command resolves it even when the config lives outside the index. |
+| `{root}` | The index root directory. Derive a root-relative path with `relpath({path}, {root})`. |
 
 ### `pre-query`
 

{dirsql-0.3.88/packages/python → dirsql-0.3.90/packages/rust}/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

{dirsql-0.3.88 → dirsql-0.3.90}/packages/rust/src/bin/dirsql.rs

@@ -61,6 +61,28 @@ struct Cli {
     /// subcommand.
     #[arg(long = "extension", global = true)]
     extension: Vec<String>,
+
+    /// Keep the SQLite index on disk between runs so a restart only re-parses
+    /// files that actually changed. Bare `--persist` caches at the default
+    /// location (`<root>/.dirsql/cache.db`); `--persist <path>` caches there.
+    /// Off by default (ephemeral index). Used by server mode and `query`.
+    #[arg(long, num_args = 0..=1, global = true)]
+    persist: Option<Option<PathBuf>>,
+}
+
+impl Cli {
+    /// Apply the `--persist [PATH]` flag to a builder. Absent → no change;
+    /// bare `--persist` → persist at the default location; `--persist <path>`
+    /// → persist at `<path>`.
+    fn apply_persist(&self, mut builder: dirsql::DirSQLBuilder) -> dirsql::DirSQLBuilder {
+        if let Some(path) = &self.persist {
+            builder = builder.persist(true);
+            if let Some(path) = path {
+                builder = builder.persist_path(path);
+            }
+        }
+        builder
+    }
 }
 
 #[derive(Debug, Subcommand)]
@@ -216,7 +238,7 @@ fn load_state(cli: &Cli) -> AppState {
     if !config_path.exists() {
         // No config: serve a default `files` table so dirsql is queryable
         // out of the box. A config file, when present, fully overrules this.
-        return load_default_state(config_path);
+        return load_default_state(cli, config_path);
     }
 
     // Canonicalize so the root (derived from the config's parent) is
@@ -237,16 +259,14 @@ fn load_state(cli: &Cli) -> AppState {
     // resolved them (including package names the compiled binary can't
     // resolve), so suppress the config's extension loading and supply the
     // resolved literal paths instead.
-    let build = if cli.extension.is_empty() {
-        DirSQL::from_config_path(&resolved)
-    } else {
-        DirSQL::builder()
-            .config(&resolved)
+    let mut builder = DirSQL::builder().config(&resolved);
+    if !cli.extension.is_empty() {
+        builder = builder
             .extensions(parse_extension_specs(&cli.extension))
-            .suppress_config_extensions(true)
-            .build()
-    };
-    match build {
+            .suppress_config_extensions(true);
+    }
+    builder = cli.apply_persist(builder);
+    match builder.build() {
         Ok(db) => AppState::Ready(db),
         Err(err) => AppState::Unavailable(format!("failed to load config: {err}")),
     }
@@ -324,7 +344,7 @@ fn load_post_query(cli: &Cli) -> Option<PostQuery> {
 /// table — one row per file, columns drawn entirely from filesystem facts —
 /// so `SELECT * FROM files` works immediately. A config file, when present,
 /// fully overrules this default.
-fn load_default_state(config_path: &Path) -> AppState {
+fn load_default_state(cli: &Cli, config_path: &Path) -> AppState {
     let dir = config_path
         .parent()
         .filter(|p| !p.as_os_str().is_empty())
@@ -340,7 +360,8 @@ fn load_default_state(config_path: &Path) -> AppState {
         }
     };
 
-    match DirSQL::new(root, vec![default_files_table()]) {
+    let builder = cli.apply_persist(DirSQL::builder().root(root).table(default_files_table()));
+    match builder.build() {
         Ok(db) => AppState::Ready(db),
         Err(err) => AppState::Unavailable(format!("failed to build default index: {err}")),
     }
@@ -406,6 +427,34 @@ mod tests {
         assert_eq!(query_body("   "), r#"{"sql":"   "}"#);
     }
 
+    #[test]
+    fn persist_flag_absent_is_none() {
+        let cli = Cli::parse_from(["dirsql"]);
+        assert_eq!(cli.persist, None);
+    }
+
+    #[test]
+    fn persist_flag_bare_enables_default_location() {
+        // Bare `--persist` (no value) → `Some(None)`: persist at the default
+        // `<root>/.dirsql/cache.db`, no override path.
+        let cli = Cli::parse_from(["dirsql", "--persist"]);
+        assert_eq!(cli.persist, Some(None));
+    }
+
+    #[test]
+    fn persist_flag_with_path_carries_the_value() {
+        let cli = Cli::parse_from(["dirsql", "--persist", "/var/cache/x.db"]);
+        assert_eq!(cli.persist, Some(Some(PathBuf::from("/var/cache/x.db"))));
+    }
+
+    #[test]
+    fn persist_flag_is_global_on_the_query_subcommand() {
+        // `--persist` is global, so it attaches to `query` too; the flag sits
+        // after the positional SQL to avoid the num_args(0..=1) greedy grab.
+        let cli = Cli::parse_from(["dirsql", "query", "SELECT 1", "--persist"]);
+        assert_eq!(cli.persist, Some(None));
+    }
+
     #[test]
     fn parse_extension_specs_handles_bare_path_and_entrypoint() {
         let specs = vec![