dirsql 0.3.111 → 0.3.113

package/docs/howto/columns-from-paths.md

@@ -33,7 +33,7 @@ Pass the config with [`-c`](../reference/cli.md#flags) (`dirsql` does not
 auto-load a `.dirsql.toml` from the current directory):
 
 ```bash
-dirsql -c ./.dirsql.toml query "SELECT year, month, basename FROM photos ORDER BY year, month"
+dirsql query "SELECT year, month, basename FROM photos ORDER BY year, month" -c ./.dirsql.toml
 ```
 
 ```json
@@ -43,7 +43,7 @@ dirsql -c ./.dirsql.toml query "SELECT year, month, basename FROM photos ORDER B
 Captures are real SQL columns, so aggregation works:
 
 ```bash
-dirsql -c ./.dirsql.toml query "SELECT year, COUNT(*) AS photos FROM photos GROUP BY year"
+dirsql query "SELECT year, COUNT(*) AS photos FROM photos GROUP BY year" -c ./.dirsql.toml
 ```
 
 ```json

package/docs/howto/define-tables.md

@@ -31,7 +31,7 @@ auto-load a `.dirsql.toml` from the current directory. Each matched file is
 one row:
 
 ```bash
-dirsql -c ./.dirsql.toml query "SELECT path, size FROM posts ORDER BY path"
+dirsql query "SELECT path, size FROM posts ORDER BY path" -c ./.dirsql.toml
 ```
 
 ```json

package/docs/howto/extract-from-contents.md

@@ -35,7 +35,7 @@ Pass the config with [`-c`](../reference/cli.md#flags) (`dirsql` does not
 auto-load a `.dirsql.toml` from the current directory):
 
 ```bash
-dirsql -c ./.dirsql.toml query "SELECT title, author, year, path FROM books ORDER BY year"
+dirsql query "SELECT title, author, year, path FROM books ORDER BY year" -c ./.dirsql.toml
 ```
 
 ```json
@@ -60,7 +60,7 @@ on-file = "jq -c -s '.' {path}"
 ```
 
 ```bash
-dirsql -c ./.dirsql.toml query "SELECT event, user FROM events"
+dirsql query "SELECT event, user FROM events" -c ./.dirsql.toml
 ```
 
 ```json

package/docs/howto/load-extension.md

@@ -27,7 +27,7 @@ The extension's functions are callable (pass the config with
 [`-c`](../reference/cli.md#flags) so its `[[dirsql.extension]]` entry loads):
 
 ```bash
-dirsql -c ./.dirsql.toml query "SELECT vec_version() AS vec_version"
+dirsql query "SELECT vec_version() AS vec_version" -c ./.dirsql.toml
 ```
 
 ```json

package/docs/howto/search-by-meaning.md

@@ -108,7 +108,7 @@ scan runs `embed.py` once per note, then the query argument goes straight to
 `.dirsql.toml` from the current directory:
 
 ```bash
-uvx --with sqlite-vec dirsql -c ./.dirsql.toml query '{"q": "how do I cook pasta?"}'
+uvx --with sqlite-vec dirsql query '{"q": "how do I cook pasta?"}' -c ./.dirsql.toml
 ```
 
 ```json
@@ -116,7 +116,7 @@ uvx --with sqlite-vec dirsql -c ./.dirsql.toml query '{"q": "how do I cook pasta
 ```
 
 ```bash
-uvx --with sqlite-vec dirsql -c ./.dirsql.toml query '{"q": "reviewing code on github"}'
+uvx --with sqlite-vec dirsql query '{"q": "reviewing code on github"}' -c ./.dirsql.toml
 ```
 
 ```json

package/docs/howto/skip-files.md

@@ -35,7 +35,7 @@ Pass the config with [`-c`](../reference/cli.md#flags) (`dirsql` does not
 auto-load a `.dirsql.toml` from the current directory):
 
 ```bash
-dirsql -c ./.dirsql.toml query "SELECT path FROM notes ORDER BY path"
+dirsql query "SELECT path FROM notes ORDER BY path" -c ./.dirsql.toml
 ```
 
 ```json

package/docs/reference/cli.md

@@ -48,7 +48,7 @@ requests, closes open `/events` streams, and exits.
 | `-c, --config <path>` | baked-in default | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index is always rooted at the **invocation directory** (the current working directory), regardless of where a config lives — so `--config /elsewhere/.dirsql.toml` still indexes the directory you ran `dirsql` from. With none given, the [baked-in default](#default-mode) `files` table is served — a `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode), not a silent fallback to the default. |
 | `--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). |
+| `--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). Also available on [`dirsql query`](#dirsql-query), passed after the subcommand. 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. |
@@ -115,10 +115,18 @@ Run a SQL query from the shell:
 dirsql query "SELECT basename, size FROM files ORDER BY size DESC LIMIT 5"
 # [{"basename":"model.bin","size":104857600}, …]
 
-# A config table (`posts`) needs its config passed explicitly.
-dirsql -c ./.dirsql.toml query "SELECT COUNT(*) AS n FROM posts" | jq '.[0].n'
+# A config table (`posts`) needs its config passed explicitly, AFTER the subcommand.
+dirsql query "SELECT COUNT(*) AS n FROM posts" -c ./.dirsql.toml | jq '.[0].n'
 ```
 
+::: warning Config flags are subcommand-local
+Pass `-c`/`--config`, `--persist`, and `--extension` **after** `query`
+(`dirsql query "<sql>" -c <cfg>`). A config flag placed *before* the subcommand
+is a hard error — `error: the subcommand 'query' cannot be used with
+'--config <CONFIG>'` — never silently dropped. (In server mode, with no
+subcommand, the same flags are passed directly: `dirsql -c <cfg>`.)
+:::
+
 The subcommand builds the index, runs the SQL, prints the result rows as a
 JSON array on stdout (byte-identical to the [`POST /query`](./http-api.md)
 response body), and exits `0`.
@@ -126,9 +134,9 @@ response body), and exits `0`.
 `dirsql query` is a thin adapter over the **same query pipeline the server
 uses**, so behavior is identical to `POST /query` by construction:
 
-- **Config discovery** honors `--config` (with none given, the
-  [baked-in default](#default-mode)), and `--extension` overrides, exactly as
-  server mode does.
+- **Config discovery** honors `--config` passed after the subcommand (with none
+  given, the [baked-in default](#default-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

package/docs/reference/sdk.md

@@ -88,7 +88,7 @@ DirSQL::builder()
     .poll_interval(duration)        // optional; watch-loop cadence, default 200ms
     .build()                        // -> Result<DirSQL>  (synchronous scan)
 // Shortcuts: DirSQL::new(root, tables), DirSQL::with_ignore(root, tables, ignore),
-//            DirSQL::from_config(root), DirSQL::from_config_path(path)
+//            DirSQL::from_config_path(path)  // reads an explicit config file
 ```
 
 :::
@@ -97,6 +97,15 @@ Creates a SQLite index over a directory. The index root is the explicit
 `root` when given, else the **process cwd** — the `config` file's location
 never sets the root.
 
+Constructing with **neither a `config` nor programmatic `tables`** serves the
+**baked-in default** `files` table (one row per file, over the root) — the
+same shipped default the CLI serves with no [`-c`](./cli.md#default-mode), not
+an empty index. There is no implicit `<root>/.dirsql.toml` discovery: to read a
+config on disk, pass its path via `config` (Rust: `.config(path)` /
+`DirSQL::from_config_path(path)`). The root-joining `DirSQL::from_config(root)`
+shortcut was removed in #603 — use
+`DirSQL::from_config_path(root.join(".dirsql.toml"))`.
+
 **Parameters:**
 
 - `root` — Directory to index. When omitted, the index roots at the process
@@ -294,7 +303,7 @@ let sync: DirSQL = db.sync()?;            // unwrap the inner sync handle
 ```
 
 Shortcuts mirror `DirSQL`: `AsyncDirSQL::new`, `with_ignore`,
-`from_config`, `from_config_path`. Unlike the Python/TypeScript SDKs,
+`from_config_path`. Unlike the Python/TypeScript SDKs,
 methods called before `ready().await` completes return a "not ready" error
 rather than waiting — an intentional, language-idiomatic difference.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.3.111",
+  "version": "0.3.113",
   "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.111",
-    "@dirsql/lib-linux-arm64-gnu": "0.3.111",
-    "@dirsql/lib-darwin-x64": "0.3.111",
-    "@dirsql/lib-darwin-arm64": "0.3.111",
-    "@dirsql/lib-win32-x64-msvc": "0.3.111",
-    "@dirsql/cli-linux-x64-gnu": "0.3.111",
-    "@dirsql/cli-linux-arm64-gnu": "0.3.111",
-    "@dirsql/cli-darwin-x64": "0.3.111",
-    "@dirsql/cli-darwin-arm64": "0.3.111",
-    "@dirsql/cli-win32-x64-msvc": "0.3.111"
+    "@dirsql/lib-linux-x64-gnu": "0.3.113",
+    "@dirsql/lib-linux-arm64-gnu": "0.3.113",
+    "@dirsql/lib-darwin-x64": "0.3.113",
+    "@dirsql/lib-darwin-arm64": "0.3.113",
+    "@dirsql/lib-win32-x64-msvc": "0.3.113",
+    "@dirsql/cli-linux-x64-gnu": "0.3.113",
+    "@dirsql/cli-linux-arm64-gnu": "0.3.113",
+    "@dirsql/cli-darwin-x64": "0.3.113",
+    "@dirsql/cli-darwin-arm64": "0.3.113",
+    "@dirsql/cli-win32-x64-msvc": "0.3.113"
   }
 }