dirsql 0.3.117 → 0.3.119

package/docs/getting-started.md

@@ -88,14 +88,15 @@ open a **second terminal** for the next step.
 
 ## 3. Query your files
 
-You gave `dirsql` no configuration, so it serves a single default table
-named `files` ([default mode](./reference/cli.md#default-mode)).
-Ask it how many rows it has:
+You gave `dirsql` no configuration, so no named tables exist. Query the
+filesystem directly with a [path-table](./reference/path-tables.md) — a
+quoted path where a table name goes. `'./'` means everything under the
+index root. Ask it how many files there are:
 
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \
-  -d '{"sql":"SELECT COUNT(*) AS files FROM files"}'
+  -d '{"sql":"SELECT COUNT(*) AS files FROM \'./\'"}'
 ```
 
 ```
@@ -109,7 +110,7 @@ through `jq` to pretty-print. Now select some columns:
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \
-  -d '{"sql":"SELECT path, size FROM files ORDER BY path"}' \
+  -d '{"sql":"SELECT path, size FROM \'./\' ORDER BY path"}' \
   | jq
 ```
 
@@ -185,8 +186,7 @@ Running at localhost:7117
 ```
 
 This time `dirsql` loaded your `.dirsql.toml` and served the `notes` table
-you defined instead of the default `files` table. Query it from the second
-terminal:
+you defined. Query it from the second terminal:
 
 ```bash
 curl -s http://localhost:7117/query \

package/docs/howto/define-tables.md

@@ -2,8 +2,8 @@
 
 Map a glob of files to a named SQL table so you query exactly the files you
 care about, with exactly the columns you care about — instead of the
-catch-all `files` table that [default mode](../reference/cli.md#default-mode)
-serves.
+ad-hoc [path-tables](../reference/path-tables.md)
+[configless mode](../reference/cli.md#configless-mode) leaves you with.
 
 ## 1. Create a config next to your files
 
@@ -39,8 +39,7 @@ dirsql query "SELECT path, size FROM posts ORDER BY path" -c ./.dirsql.toml
 ```
 
 Files that don't match the glob (a `README.txt` next to `posts/`, say) are
-simply not in the table. Passing a config with `-c` fully replaces the
-default `files` table — only the tables you define are served.
+simply not in the table. Only the tables you define are served.
 
 ## Multiple tables
 

package/docs/howto/react-to-changes.md

@@ -5,10 +5,21 @@ change — and [`GET /events`](../reference/http-api.md#get-events) pushes
 every row-level change to you as it happens. No polling, no diffing on your
 side.
 
+Row events are emitted for **named tables**, so this flow needs a config —
+[path-tables](../reference/path-tables.md) are scanned per query and are not
+watched. Define one next to your files:
+
+```toml
+# .dirsql.toml
+[[table]]
+ddl  = "CREATE TABLE files (path TEXT, basename TEXT, dir TEXT, ext TEXT, size INTEGER, mtime INTEGER, ctime INTEGER)"
+glob = "**/*"
+```
+
 ## 1. Open the stream
 
-With the server running (`npx dirsql` / `uvx dirsql`), subscribe from
-another terminal:
+With the server running (`npx dirsql -c ./.dirsql.toml` /
+`uvx dirsql -c ./.dirsql.toml`), subscribe from another terminal:
 
 ```bash
 curl -N http://localhost:7117/events

package/docs/howto/skip-files.md

@@ -45,7 +45,7 @@ dirsql query "SELECT path FROM notes ORDER BY path" -c ./.dirsql.toml
 ## Notes
 
 - `ignore` lives in a config file, so it needs one:
-  [default mode](../reference/cli.md#default-mode) indexes
+  [configless mode](../reference/cli.md#configless-mode) indexes
   everything with no ignores.
 - The top-level `.dirsql/` directory is always excluded, ignore list or
   not — it is reserved for `dirsql`'s own metadata

package/docs/howto/write-a-plugin.md

@@ -217,9 +217,8 @@ Discovery is deliberately narrow. Know exactly who does what:
   your config still takes ordering precedence
   ([composing configs](../reference/config.md#composing-multiple-configs)). When
   you pass no `-c` of your own, the launcher also keeps the
-  [baked-in default](../reference/cli.md#default-mode) `files` table (an
-  internal `--include-default`), so plugins **add** tables rather than
-  replacing the default. Discovery is **pip/uvx only** for now — the `npx`
+  shipped starter `files` table (an internal `--include-default`), so plugins
+  **add** tables rather than standing alone. Discovery is **pip/uvx only** for now — the `npx`
   launcher does not yet discover — and is switched off per invocation with
   [`--no-plugin` or `DIRSQL_NO_PLUGIN=1`](../reference/cli.md#plugins).
 - **The SDK never auto-discovers.** Pass a plugin's config explicitly (the

package/docs/reference/cli.md

@@ -45,7 +45,7 @@ requests, closes open `/events` streams, and exits.
 
 | Flag | Default | Description |
 |---|---|---|
-| `-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. |
+| `-c, --config <path>` | none | 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, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). 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). |
 | `--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). Also available on [`dirsql query`](#dirsql-query), passed after the subcommand. See [Keep the index across restarts](../howto/persist.md). |
@@ -61,25 +61,26 @@ requests, closes open `/events` streams, and exits.
   **30-second** timeout each, overridable with the config key
   [`[dirsql].hook-timeout`](./config.md#dirsql-keys).
 
-### Default mode
+### Configless mode
 
-With no `-c/--config`, the server serves the **baked-in default** — the
-shipped config compiled into the binary, indexing the invocation directory
-with a single table named `files`. This is a fixed default, *not* a
-`.dirsql.toml` read from disk: a `./.dirsql.toml` sitting in the current
-directory is **not** auto-loaded (pass it with `-c ./.dirsql.toml` to use
-it). The default `files` table:
+With no `-c/--config`, the server indexes the invocation directory but
+defines **no named tables**. Filesystem queries go through
+[path-tables](./path-tables.md): a quoted path in place of a table name,
+scanned live. A `./.dirsql.toml` sitting in the current directory is **not**
+auto-loaded (pass it with `-c ./.dirsql.toml` to use it).
 
-- Glob: `**/*` — every file under the root, at any depth, no ignores.
-- One row per file, with all seven
-  [stat columns](./columns.md): `path`, `basename`, `dir`, `ext`,
-  `size`, `mtime`, `ctime`.
+`'./'` is the whole root — every file at any depth, one row per file, with
+all seven [stat columns](./columns.md): `path`, `basename`, `dir`, `ext`,
+`size`, `mtime`, `ctime`.
 
 ```bash
 curl -s localhost:7117/query -H 'content-type: application/json' \
-  -d '{"sql":"SELECT basename, size FROM files ORDER BY size DESC LIMIT 5"}'
+  -d '{"sql":"SELECT basename, size FROM \'./\' ORDER BY size DESC LIMIT 5"}'
 ```
 
+Earlier versions served an implicit table named `files` here. It is gone; a
+`SELECT ... FROM files` with no config now fails and points at `FROM './'`.
+
 Passing a config with `-c` fully overrules this default. A `-c` naming a file
 that does not exist is an error (not a fallback to the default); a config that
 exists but fails to load degrades the server (see below).
@@ -111,8 +112,8 @@ non-zero exit with the diagnostic on stderr.
 Run a SQL query from the shell:
 
 ```bash
-# No -c: the baked-in default `files` table.
-dirsql query "SELECT basename, size FROM files ORDER BY size DESC LIMIT 5"
+# No -c: query the filesystem with a path-table.
+dirsql query "SELECT basename, size FROM './' ORDER BY size DESC LIMIT 5"
 # [{"basename":"model.bin","size":104857600}, …]
 
 # A config table (`posts`) needs its config passed explicitly, AFTER the subcommand.
@@ -135,7 +136,7 @@ response body), and exits `0`.
 uses**, so behavior is identical to `POST /query` by construction:
 
 - **Config discovery** honors `--config` passed after the subcommand (with none
-  given, the [baked-in default](#default-mode)), and `--extension` overrides,
+  given, [no named tables](#configless-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
@@ -163,8 +164,8 @@ stderr, with exit code `1`.
 
 ## `dirsql init`
 
-Writes a starter `.dirsql.toml` — the same table the [baked-in
-default](#default-mode) serves — as a scaffold to edit:
+Writes a starter `.dirsql.toml` defining a catch-all `files` table, as a
+scaffold to edit:
 
 ```bash
 dirsql init
@@ -205,7 +206,7 @@ installed in the same environment as `dirsql` (`pip install …`, or
 loads its fragment — its tables are queryable with zero config edits.
 Installed = active: there is no enable step and no naming convention. The
 fragment is composed *after* your own `-c` configs (so your config takes
-precedence in ordering), and the baked-in `files` table is preserved.
+precedence in ordering), and the shipped starter `files` table is preserved.
 
 Discovery is **launcher-only** — the standalone `cargo`-installed binary does no
 discovery, and the SDKs never auto-discover (pass a plugin's config explicitly

package/docs/reference/config.md

@@ -8,7 +8,7 @@ all-defaults one. Unknown keys are a parse error at every level (top level,
 fails loudly, naming the offending key, rather than silently no-opping.
 
 The [CLI](./cli.md) loads a config only when you pass it with `-c/--config`;
-with none given it serves the [baked-in default](./cli.md#default-mode) (a
+with none given [no named tables](./cli.md#configless-mode) are defined (a
 `./.dirsql.toml` on disk is **not** auto-loaded). The [SDKs](./sdk.md) load a
 config via the `config` constructor parameter.
 
@@ -110,8 +110,8 @@ callback.
 
 ```toml
 [[table]]
-ddl  = "CREATE TABLE comments (thread_id TEXT, basename TEXT, mtime INTEGER)"
-glob = "_comments/{thread_id}/*.jsonl"
+ddl  = "CREATE TABLE comments (path TEXT, basename TEXT, mtime INTEGER)"
+glob = "_comments/*/*.jsonl"
 
 [[table]]
 ddl     = "CREATE TABLE papers (paper_id TEXT, title TEXT)"
@@ -161,8 +161,8 @@ The configs load and merge in **argv order**:
   error**, naming the table.
 
 The index [root](./cli.md#flags) is the invocation directory regardless of where
-any config lives. With no `-c`, the [baked-in default](./cli.md#default-mode) is
-served (no `./.dirsql.toml` auto-discovery); a single `-c` behaves exactly as
+any config lives. With no `-c`, [no named tables](./cli.md#configless-mode) are
+defined (no `./.dirsql.toml` auto-discovery); a single `-c` behaves exactly as
 before.
 
 ## Parse errors
@@ -193,8 +193,8 @@ path       = "sqlite_vec"            # Python module name; on Node use the
 entrypoint = "sqlite3_vec_init"
 
 [[table]]
-ddl  = "CREATE TABLE comments (thread_id TEXT, basename TEXT, mtime INTEGER)"
-glob = "_comments/{thread_id}/*.jsonl"
+ddl  = "CREATE TABLE comments (path TEXT, basename TEXT, mtime INTEGER)"
+glob = "_comments/*/*.jsonl"
 
 [[table]]
 ddl  = "CREATE TABLE documents (path TEXT, basename TEXT, size INTEGER)"

package/docs/reference/path-tables.md

@@ -32,26 +32,61 @@ Two consequences follow directly:
 
 ## Writing the path
 
-The path is relative to the **index root** — the directory dirsql is indexing,
-not your shell's working directory.
+A `./` path is relative to the **index root** — the directory dirsql is
+indexing, not your shell's working directory.
+
+**Directories are recursive by default.** Naming a directory scans everything
+beneath it; the non-recursive form is spelled explicitly with `*`.
 
 | You write | dirsql scans |
 | --- | --- |
 | `'./'` | every file under the index root, recursively |
+| `'./docs'` | every file under `docs/`, recursively |
+| `'./*'` | files directly inside the index root, and no deeper |
 | `'./docs/*.md'` | markdown files directly inside `docs/` |
 | `'./docs/**/*.md'` | markdown files at any depth under `docs/` |
+| `'./notes/today.md'` | exactly that one file — one file is one row |
+
+A path containing `*`, `?` or `[` is a glob and is used exactly as written: `*`
+matches within a single directory, `**` crosses directories.
+
+A path naming a single file yields exactly one row. dirsql never splits a file
+into rows on its own — that is what a table's `on_file` hook is for.
 
-The `./` is required. A bare glob is rejected with a hint rather than silently
-accepted:
+The `./` is required for index-relative paths. A bare glob is rejected with a
+hint rather than silently accepted:
 
 ```
 SELECT * FROM '**/*.md';
 -- no such table: **/*.md; did you mean './**/*.md'?
 ```
 
-Absolute (`/var/log/*.log`), parent-relative (`../notes`) and home-relative
-(`~/notes`) path-tables are recognized but not yet resolved; they report that
-they are unsupported rather than returning wrong rows.
+### Paths outside the index root
+
+Three other prefixes resolve, with their usual shell meanings:
+
+| You write | dirsql scans |
+| --- | --- |
+| `'/var/log/*.log'` | an absolute path |
+| `'../notes'` | relative to the index root's parent |
+| `'~/notes/*.md'` | relative to your home directory |
+
+`..` is folded out textually, not followed through symlinks, so the directory
+scanned is a function of the string you wrote.
+
+**These report absolute `path` values.** A `./` path-table reports paths
+relative to the index root, matching every other dirsql table; a `/`, `../` or
+`~/` path-table has no meaningful relative base — the root it scans is derived
+from the pattern, not named by you — so it reports the full path instead. The
+value you get back is one you can paste into another command:
+
+```sql
+SELECT path FROM '/var/log/*.log';
+-- /var/log/syslog
+```
+
+On a system with no home directory, a `~/` path-table reports that it cannot
+resolve rather than guessing.
 
 ## Columns
 
@@ -60,7 +95,7 @@ table:
 
 | Column | Type | Meaning |
 | --- | --- | --- |
-| `path` | TEXT | path relative to the index root |
+| `path` | TEXT | path relative to the index root (absolute for `/`, `../`, `~/` tables) |
 | `basename` | TEXT | filename with extension |
 | `dir` | TEXT | parent directory, relative to the index root |
 | `ext` | TEXT | extension without the dot |
@@ -89,6 +124,26 @@ 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.
 
+## Skip rules
+
+A path-table scan applies the same [`ignore`](/reference/config) patterns your
+declared tables use, plus two built-in defaults so a zero-config
+`SELECT * FROM './'` does not drown in machinery:
+
+- `node_modules/**`
+- `.git/**`
+
+Skip rules are judged on the part of the path *below* what you named outright,
+so pointing at a skipped directory still scans it:
+
+```sql
+SELECT path FROM './';                     -- no node_modules rows
+SELECT path FROM './node_modules/*/package.json';  -- scans it anyway
+```
+
+Dotfiles are ordinary files: `'./'` and `'./*'` include them. Add an `ignore`
+pattern if you would rather not see them.
+
 ## Joining against declared tables
 
 Path-tables are ordinary SQLite tables once resolved, so they join freely:

package/docs/reference/sdk.md

@@ -97,10 +97,12 @@ 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
+Constructing with **neither a `config` nor programmatic `tables`** defines
+**no named tables** — the same as the CLI with no
+[`-c`](./cli.md#configless-mode). Query the filesystem with a
+[path-table](./path-tables.md) (`SELECT * FROM './'`); a `SELECT ... FROM
+files` in that state fails with a hint pointing at that form. 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

package/package.json

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