dirsql 0.3.119 → 0.3.121

package/docs/howto/query-without-config.md

@@ -0,0 +1,69 @@
+# Query files without a config
+
+You have a directory and a question about the files in it. You want an answer
+now — not a `.dirsql.toml`, not a schema, not a setup step. Point `dirsql` at
+the directory and write a path where a table name goes.
+
+## 1. Run a query against the directory
+
+No config, no install ceremony — `uvx` (or `npx`) fetches and runs `dirsql`,
+rooted at the directory you run it from:
+
+```bash
+uvx dirsql query "SELECT basename, size FROM './' ORDER BY size DESC LIMIT 5"
+```
+
+```json
+[
+  {"basename":"video.mp4","size":84213770},
+  {"basename":"archive.zip","size":9123400},
+  {"basename":"notes.md","size":40213},
+  {"basename":"todo.md","size":1200},
+  {"basename":"README.md","size":840}
+]
+```
+
+`'./'` stands in for a table you never declared. `dirsql` scans the directory
+live and hands SQLite one row per file — this is a
+[path-table](../reference/path-tables.md). Because there is no `-c`, there are
+**no named tables** at all; the path *is* the query
+([configless mode](../reference/cli.md#configless-mode)).
+
+## 2. Ask about content, not just names
+
+Every file exposes the seven [stat columns](../reference/columns.md) (`path`,
+`basename`, `dir`, `ext`, `size`, `mtime`, `ctime`) plus a hidden `content`
+column. `content` is read only when you name it, so filtering on it is cheap
+until you actually ask:
+
+```bash
+uvx dirsql query "SELECT path FROM './docs/**/*.md' WHERE content LIKE '%deprecated%'"
+```
+
+The `./` prefix is required. A bare glob is rejected with a hint rather than
+silently guessed:
+
+```
+uvx dirsql query "SELECT * FROM '**/*.md'"
+-- no such table: **/*.md; did you mean './**/*.md'?
+```
+
+## 3. Graduate to a named table when it pays off
+
+A path-table re-scans the filesystem on every query — perfect for a one-off
+question over a few hundred files, wasteful for a large tree you query
+repeatedly. When that day comes, [declare a table](./define-tables.md): it is
+indexed once, kept fresh by the watcher, and can persist across restarts. The
+zero-config query is the floor; a named table is the escalation path — nothing
+you write here has to be thrown away to get there.
+
+## Notes
+
+- The same query works from the SDK: construct `DirSQL` with neither a
+  `config` nor `tables` and call `query("SELECT * FROM './'")`
+  ([SDK reference](../reference/sdk.md)).
+- Paths outside the root resolve too — `'/var/log/*.log'`, `'../notes'`,
+  `'~/notes/*.md'` — reporting absolute paths
+  ([path-tables reference](../reference/path-tables.md#paths-outside-the-index-root)).
+- `node_modules/` and `.git/` are skipped by default so a bare `'./'` does not
+  drown in machinery ([skip rules](../reference/path-tables.md#skip-rules)).

package/docs/reference/path-tables.md

@@ -120,10 +120,26 @@ A path-table is scanned when the statement runs, so it always reflects the
 filesystem as it is *now* — unlike declared tables, which are indexed on build
 and updated by the watcher. A file created a moment ago shows up immediately.
 
+The scan is live all the way down to `content`: a file's body is read when the
+query names the `content` column, not when the row is discovered. A file
+deleted *after* the scan finds it but *before* its `content` is read yields
+`NULL` content — the same NULL an unreadable or non-UTF-8 file gives — rather
+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.
 
+### 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
+[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.
+
 ## Skip rules
 
 A path-table scan applies the same [`ignore`](/reference/config) patterns your

package/package.json

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