dirsql 0.3.118__tar.gz → 0.3.119__tar.gz

{dirsql-0.3.118 → dirsql-0.3.119}/Cargo.lock

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

{dirsql-0.3.118 → dirsql-0.3.119}/PKG-INFO

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

{dirsql-0.3.118/packages/rust → dirsql-0.3.119}/docs/reference/cli.md

@@ -151,6 +151,25 @@ uses**, so behavior is identical to `POST /query` by construction:
   statements; dirsql separately never modifies the files it indexes — see
   [Read-only by design](../explanation#read-only-by-design).
 
+#### `--on-file <command>`
+
+Attach a parser to every [path-table](./path-tables.md#parsing-rows-with-on-file)
+in the query, so each matched file yields the rows the command prints (a JSON
+array of row objects) instead of the stat columns:
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+The command follows the [`on-file` hook contract](./hooks.md#on-file) — argv
+splitting, `{path}`/`{root}` placeholders, per-file failure isolation, and the
+timeout. The parser's output is the whole schema; the stat columns are not
+reachable on a parsed path-table. `--on-file` may be given **at most once** (a
+repeat is an error pointing at config files) and never touches config-declared
+tables. It is a `query`-only flag — server mode rejects it as an unknown
+argument.
+
 Errors print the same diagnostic the HTTP `{"error": …}` body carries —
 config failures, SQL errors, rejected reads, hook failures, timeouts — to
 stderr, with exit code `1`.

{dirsql-0.3.118 → dirsql-0.3.119}/docs/reference/path-tables.md

@@ -114,6 +114,39 @@ SELECT path FROM './docs/*.md' WHERE content LIKE '%deprecated%';
 A file that cannot be read, or is not valid UTF-8, yields `NULL` content rather
 than failing the query.
 
+## Parsing rows with `--on-file`
+
+By default a path-table's columns are the stat columns above — one row per
+file. When you want *one row per record inside* each file, attach a parser with
+the `dirsql query` flag [`--on-file`](/reference/cli):
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+The command runs once per matched file and prints a JSON array of row objects,
+exactly like a declared table's [`on-file` hook](/reference/hooks) — same argv
+splitting, same `{path}`/`{root}` placeholders, same timeout. Its output *is*
+the table:
+
+- **The parser supplies the whole schema.** Columns are inferred from the keys
+  across the emitted rows. The stat columns (`path`, `size`, …) are **not**
+  reachable on a parsed path-table — a parser that wants the path emits it (it
+  has `{path}`). The two modes stay cleanly separate.
+- **Failures are isolated per file.** A file whose parser fails (spawn, non-zero
+  exit, timeout, or no output) or whose output is not a JSON array of rows
+  contributes no rows; a one-line warning naming the file goes to stderr and the
+  scan continues. The schema is inferred from the files that did parse.
+- **The skip rules still apply.** A parsed scan honors the same `node_modules`
+  /`.git`/`ignore` rules a stat scan does (see below).
+
+`--on-file` applies to **every** path-table in the query and may be given **at
+most once**. For different parsers per file set, define named tables in a
+`.dirsql.toml` with their own `on-file` keys and pass it with `-c` — the flag
+never touches config-declared tables. It is a `query`-subcommand flag; server
+mode does not accept it.
+
 ## Freshness and scope
 
 A path-table is scanned when the statement runs, so it always reflects the

{dirsql-0.3.118 → dirsql-0.3.119}/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.118"
+version = "0.3.119"
 # 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.118 → dirsql-0.3.119}/packages/python/docs/reference/cli.md

@@ -151,6 +151,25 @@ uses**, so behavior is identical to `POST /query` by construction:
   statements; dirsql separately never modifies the files it indexes — see
   [Read-only by design](../explanation#read-only-by-design).
 
+#### `--on-file <command>`
+
+Attach a parser to every [path-table](./path-tables.md#parsing-rows-with-on-file)
+in the query, so each matched file yields the rows the command prints (a JSON
+array of row objects) instead of the stat columns:
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+The command follows the [`on-file` hook contract](./hooks.md#on-file) — argv
+splitting, `{path}`/`{root}` placeholders, per-file failure isolation, and the
+timeout. The parser's output is the whole schema; the stat columns are not
+reachable on a parsed path-table. `--on-file` may be given **at most once** (a
+repeat is an error pointing at config files) and never touches config-declared
+tables. It is a `query`-only flag — server mode rejects it as an unknown
+argument.
+
 Errors print the same diagnostic the HTTP `{"error": …}` body carries —
 config failures, SQL errors, rejected reads, hook failures, timeouts — to
 stderr, with exit code `1`.

{dirsql-0.3.118 → dirsql-0.3.119}/packages/python/docs/reference/path-tables.md

@@ -114,6 +114,39 @@ SELECT path FROM './docs/*.md' WHERE content LIKE '%deprecated%';
 A file that cannot be read, or is not valid UTF-8, yields `NULL` content rather
 than failing the query.
 
+## Parsing rows with `--on-file`
+
+By default a path-table's columns are the stat columns above — one row per
+file. When you want *one row per record inside* each file, attach a parser with
+the `dirsql query` flag [`--on-file`](/reference/cli):
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+The command runs once per matched file and prints a JSON array of row objects,
+exactly like a declared table's [`on-file` hook](/reference/hooks) — same argv
+splitting, same `{path}`/`{root}` placeholders, same timeout. Its output *is*
+the table:
+
+- **The parser supplies the whole schema.** Columns are inferred from the keys
+  across the emitted rows. The stat columns (`path`, `size`, …) are **not**
+  reachable on a parsed path-table — a parser that wants the path emits it (it
+  has `{path}`). The two modes stay cleanly separate.
+- **Failures are isolated per file.** A file whose parser fails (spawn, non-zero
+  exit, timeout, or no output) or whose output is not a JSON array of rows
+  contributes no rows; a one-line warning naming the file goes to stderr and the
+  scan continues. The schema is inferred from the files that did parse.
+- **The skip rules still apply.** A parsed scan honors the same `node_modules`
+  /`.git`/`ignore` rules a stat scan does (see below).
+
+`--on-file` applies to **every** path-table in the query and may be given **at
+most once**. For different parsers per file set, define named tables in a
+`.dirsql.toml` with their own `on-file` keys and pass it with `-c` — the flag
+never touches config-declared tables. It is a `query`-subcommand flag; server
+mode does not accept it.
+
 ## Freshness and scope
 
 A path-table is scanned when the statement runs, so it always reflects the

dirsql-0.3.119/packages/python/e2e-attestations/feat-631-on-file-flag.json

@@ -0,0 +1,7 @@
+{
+  "command": "UV_NO_SYNC=1 uv run python -m pytest tests/e2e/ -x -q",
+  "ran_at": 1784652812,
+  "exit_code": 0,
+  "commit": "c59b0667084ba1d9542031a60cd55ae0bc3c7db6",
+  "branch": "feat/631-on-file-flag"
+}

dirsql-0.3.119/packages/rust/changelog.d/2026-07-21-on-file-flag.md

@@ -0,0 +1,14 @@
+**Added**
+
+`dirsql query "<sql>" --on-file '<command>'` attaches a parser to every
+[path-table](https://thekevinscott.github.io/dirsql/reference/path-tables) in
+the query. With the flag set, a path-table's rows and schema come from the
+command's JSON output (the `on-file` hook contract — argv splitting,
+`{path}`/`{root}` placeholders, timeout) instead of the stat columns. The
+parser's output is the whole schema; stat columns are not reachable on a parsed
+path-table. Failures are isolated per file — a file whose parser fails or whose
+output does not parse contributes no rows and a stderr warning, and the scan
+continues. Parsed scans honor the same `node_modules`/`.git`/`ignore` skip
+rules stat scans do. The flag may be given at most once (a repeat errors,
+pointing at config files), applies only to path-tables (config `[[table]]`
+`on-file` hooks are untouched), and is `query`-only (server mode rejects it).

{dirsql-0.3.118 → dirsql-0.3.119/packages/rust}/docs/reference/cli.md

@@ -151,6 +151,25 @@ uses**, so behavior is identical to `POST /query` by construction:
   statements; dirsql separately never modifies the files it indexes — see
   [Read-only by design](../explanation#read-only-by-design).
 
+#### `--on-file <command>`
+
+Attach a parser to every [path-table](./path-tables.md#parsing-rows-with-on-file)
+in the query, so each matched file yields the rows the command prints (a JSON
+array of row objects) instead of the stat columns:
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+The command follows the [`on-file` hook contract](./hooks.md#on-file) — argv
+splitting, `{path}`/`{root}` placeholders, per-file failure isolation, and the
+timeout. The parser's output is the whole schema; the stat columns are not
+reachable on a parsed path-table. `--on-file` may be given **at most once** (a
+repeat is an error pointing at config files) and never touches config-declared
+tables. It is a `query`-only flag — server mode rejects it as an unknown
+argument.
+
 Errors print the same diagnostic the HTTP `{"error": …}` body carries —
 config failures, SQL errors, rejected reads, hook failures, timeouts — to
 stderr, with exit code `1`.

{dirsql-0.3.118 → dirsql-0.3.119}/packages/rust/docs/reference/path-tables.md

@@ -114,6 +114,39 @@ SELECT path FROM './docs/*.md' WHERE content LIKE '%deprecated%';
 A file that cannot be read, or is not valid UTF-8, yields `NULL` content rather
 than failing the query.
 
+## Parsing rows with `--on-file`
+
+By default a path-table's columns are the stat columns above — one row per
+file. When you want *one row per record inside* each file, attach a parser with
+the `dirsql query` flag [`--on-file`](/reference/cli):
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+The command runs once per matched file and prints a JSON array of row objects,
+exactly like a declared table's [`on-file` hook](/reference/hooks) — same argv
+splitting, same `{path}`/`{root}` placeholders, same timeout. Its output *is*
+the table:
+
+- **The parser supplies the whole schema.** Columns are inferred from the keys
+  across the emitted rows. The stat columns (`path`, `size`, …) are **not**
+  reachable on a parsed path-table — a parser that wants the path emits it (it
+  has `{path}`). The two modes stay cleanly separate.
+- **Failures are isolated per file.** A file whose parser fails (spawn, non-zero
+  exit, timeout, or no output) or whose output is not a JSON array of rows
+  contributes no rows; a one-line warning naming the file goes to stderr and the
+  scan continues. The schema is inferred from the files that did parse.
+- **The skip rules still apply.** A parsed scan honors the same `node_modules`
+  /`.git`/`ignore` rules a stat scan does (see below).
+
+`--on-file` applies to **every** path-table in the query and may be given **at
+most once**. For different parsers per file set, define named tables in a
+`.dirsql.toml` with their own `on-file` keys and pass it with `-c` — the flag
+never touches config-declared tables. It is a `query`-subcommand flag; server
+mode does not accept it.
+
 ## Freshness and scope
 
 A path-table is scanned when the statement runs, so it always reflects the

{dirsql-0.3.118 → dirsql-0.3.119}/packages/rust/src/bin/dirsql.rs

@@ -146,10 +146,42 @@ struct QueryArgs {
     /// The SQL to run (a single read-only statement).
     sql: String,
 
+    /// Attach a parser to every path-table in the query. The command follows
+    /// the `on-file` hook contract (`docs/reference/hooks.md`): argv splitting,
+    /// `{path}`/`{root}` placeholders, a JSON array of row objects on stdout,
+    /// per-file failure isolation, and the hook timeout. With it set, a
+    /// path-table's rows and schema come from the parser instead of the stat
+    /// columns. One `--on-file` max; for multiple tables use a config file.
+    #[arg(long = "on-file")]
+    on_file: Vec<String>,
+
     #[command(flatten)]
     common: ConfigArgs,
 }
 
+/// Reduce the repeatable `--on-file` occurrences to at most one parser command.
+///
+/// `clap` collects repeats into a `Vec` so the error can name config files
+/// (its default "cannot be used multiple times" cannot). Empty → no parser;
+/// exactly one → that command; more than one → an error pointing at config
+/// files, where per-table parsers belong. A whitespace-only command is rejected
+/// up front (the hook contract forbids an empty command).
+fn resolve_on_file(occurrences: &[String]) -> std::result::Result<Option<String>, String> {
+    match occurrences {
+        [] => Ok(None),
+        [command] if command.trim().is_empty() => {
+            Err("--on-file needs a non-empty command".to_string())
+        }
+        [command] => Ok(Some(command.clone())),
+        _ => Err(
+            "--on-file may be given at most once; it applies to every path-table in the \
+             query. For per-table parsers, define tables in a config file with an \
+             `on-file` key and pass it with -c."
+                .to_string(),
+        ),
+    }
+}
+
 #[derive(Debug, Args)]
 struct InitArgs {
     /// Directory the default `--output` path is resolved against (default:
@@ -185,7 +217,14 @@ async fn main() -> ExitCode {
 /// message — the same string the HTTP `{"error": …}` body carries — to
 /// stderr with a non-zero exit.
 async fn run_query(args: QueryArgs) -> ExitCode {
-    let state = load_state(&args.common);
+    let parser = match resolve_on_file(&args.on_file) {
+        Ok(parser) => parser,
+        Err(message) => {
+            eprintln!("dirsql query: {message}");
+            return ExitCode::from(1);
+        }
+    };
+    let state = load_state(&args.common, parser);
     let pre_query = load_pre_queries(&args.common);
     let post_query = load_post_queries(&args.common);
     // Same default the server binds with; the pipeline enforces it.
@@ -246,7 +285,9 @@ fn run_init(args: InitArgs) -> ExitCode {
 }
 
 async fn run_server(cli: Cli) -> ExitCode {
-    let state = load_state(&cli.common);
+    // The server has no `--on-file`: clap rejects it as an unknown flag before
+    // reaching here. Path-tables served over HTTP keep their stat columns.
+    let state = load_state(&cli.common, None);
     let mut server_config = ServerConfig::bind(cli.host.clone(), cli.port);
     for pre_query in load_pre_queries(&cli.common) {
         server_config = server_config.with_pre_query(pre_query);
@@ -278,12 +319,12 @@ async fn run_server(cli: Cli) -> ExitCode {
     ExitCode::SUCCESS
 }
 
-fn load_state(cfg: &ConfigArgs) -> AppState {
+fn load_state(cfg: &ConfigArgs, path_table_parser: Option<String>) -> AppState {
     // Neither a `-c` nor the launcher's `--include-default` -> index the
     // invocation directory with no named tables. A `./.dirsql.toml` on disk is
     // NOT consulted (#602); pass it explicitly with `-c` to use it.
     if cfg.config.is_empty() && !cfg.include_default {
-        return load_configless_state(cfg);
+        return load_configless_state(cfg, path_table_parser);
     }
 
     let mut builder = DirSQL::builder();
@@ -324,6 +365,12 @@ fn load_state(cfg: &ConfigArgs) -> AppState {
             .suppress_config_extensions(true);
     }
     builder = cfg.apply_persist(builder);
+    // `--on-file` touches path-tables only: config `[[table]]` definitions keep
+    // their own `on-file` hooks; a path-table named in the query gets this
+    // parser regardless of any `-c`.
+    if let Some(command) = path_table_parser {
+        builder = builder.path_table_parser(command);
+    }
     match builder.build() {
         Ok(db) => AppState::Ready(db),
         Err(err) => AppState::Unavailable(format!("failed to load config: {err}")),
@@ -420,7 +467,7 @@ fn load_post_queries(cfg: &ConfigArgs) -> Vec<PostQuery> {
 /// tables: filesystem queries go through path-tables (`SELECT * FROM './'`),
 /// and a `files` query fails with a hint pointing at that form (#636). A
 /// `./.dirsql.toml` in the cwd is not consulted (#602).
-fn load_configless_state(cfg: &ConfigArgs) -> AppState {
+fn load_configless_state(cfg: &ConfigArgs, path_table_parser: Option<String>) -> AppState {
     // Canonicalize for the same reason `load_state` does: `notify` misbehaves
     // when watching relative paths.
     let root = match PathBuf::from(".").canonicalize() {
@@ -430,7 +477,10 @@ fn load_configless_state(cfg: &ConfigArgs) -> AppState {
         }
     };
 
-    let builder = cfg.apply_persist(DirSQL::builder().root(root));
+    let mut builder = cfg.apply_persist(DirSQL::builder().root(root));
+    if let Some(command) = path_table_parser {
+        builder = builder.path_table_parser(command);
+    }
     match builder.build() {
         Ok(db) => AppState::Ready(db),
         Err(err) => AppState::Unavailable(format!("failed to build the index: {err}")),
@@ -606,6 +656,81 @@ mod tests {
         );
     }
 
+    /// The `on_file` occurrences parsed from a `query` invocation.
+    fn query_on_file(argv: &[&str]) -> Vec<String> {
+        match Cli::parse_from(argv).command {
+            Some(Command::Query(args)) => args.on_file,
+            other => panic!("expected a query subcommand, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn on_file_absent_leaves_no_occurrences() {
+        assert!(query_on_file(&["dirsql", "query", "SELECT 1"]).is_empty());
+    }
+
+    #[test]
+    fn on_file_parses_after_the_query_subcommand() {
+        assert_eq!(
+            query_on_file(&["dirsql", "query", "SELECT 1", "--on-file", "cat {path}"]),
+            vec!["cat {path}".to_string()]
+        );
+    }
+
+    #[test]
+    fn on_file_collects_every_repeat_for_the_arity_check() {
+        // clap collects repeats; `resolve_on_file` turns >1 into the pointed
+        // error rather than clap's generic "cannot be used multiple times".
+        assert_eq!(
+            query_on_file(&[
+                "dirsql",
+                "query",
+                "SELECT 1",
+                "--on-file",
+                "a",
+                "--on-file",
+                "b"
+            ]),
+            vec!["a".to_string(), "b".to_string()]
+        );
+    }
+
+    #[test]
+    fn on_file_is_rejected_before_a_query_subcommand() {
+        // Like the other subcommand-local flags, `--on-file` ahead of the
+        // subcommand is not a server flag: clap rejects it.
+        assert!(Cli::try_parse_from(["dirsql", "--on-file", "cat", "query", "SELECT 1"]).is_err());
+    }
+
+    #[test]
+    fn resolve_on_file_is_none_without_the_flag() {
+        assert_eq!(resolve_on_file(&[]), Ok(None));
+    }
+
+    #[test]
+    fn resolve_on_file_returns_the_single_command() {
+        assert_eq!(
+            resolve_on_file(&["cat {path}".to_string()]),
+            Ok(Some("cat {path}".to_string()))
+        );
+    }
+
+    #[test]
+    fn resolve_on_file_rejects_a_blank_command() {
+        let err = resolve_on_file(&["   ".to_string()]).unwrap_err();
+        assert!(err.contains("non-empty"), "got: {err}");
+    }
+
+    #[test]
+    fn resolve_on_file_rejects_a_repeat_and_points_at_config_files() {
+        let err = resolve_on_file(&["a".to_string(), "b".to_string()]).unwrap_err();
+        assert!(err.contains("at most once"), "got: {err}");
+        assert!(
+            err.contains("config file"),
+            "the error must point at config files, got: {err}"
+        );
+    }
+
     #[test]
     fn parse_extension_specs_handles_bare_path_and_entrypoint() {
         let specs = vec![

{dirsql-0.3.118 → dirsql-0.3.119}/packages/rust/src/db.rs

@@ -3,6 +3,7 @@ use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
 use thiserror::Error;
 
+use crate::parsed_vtab;
 use crate::path_table::{self, PathTable, Resolution};
 use crate::vtab;
 
@@ -107,18 +108,41 @@ fn quote_identifier(s: &str) -> String {
 /// persistent cache file — so a path-table can never leak into a persisted
 /// `sqlite_master`. `IF NOT EXISTS` makes a repeat reference a no-op, which is
 /// why no cross-call registry is needed.
-fn path_table_ddl(name: &str, table: &PathTable, ignore: &[String]) -> String {
-    let mut args = vec![
-        quote_literal(&table.root.to_string_lossy()),
-        quote_literal(&table.glob),
-        quote_literal(&table.path_prefix),
-    ];
+///
+/// With a `parser` present (the CLI's `--on-file`), the table is minted over
+/// the parsed module instead: its rows and schema come from the parser, not
+/// the stat columns, and the `path_prefix` is irrelevant (a parser wanting a
+/// path emits it). Both forms carry the same ignore rules.
+fn path_table_ddl(
+    name: &str,
+    table: &PathTable,
+    ignore: &[String],
+    parser: Option<&str>,
+) -> String {
+    let (module, mut args) = match parser {
+        Some(command) => (
+            parsed_vtab::MODULE_NAME,
+            vec![
+                quote_literal(&table.root.to_string_lossy()),
+                quote_literal(&table.glob),
+                quote_literal(command),
+            ],
+        ),
+        None => (
+            vtab::MODULE_NAME,
+            vec![
+                quote_literal(&table.root.to_string_lossy()),
+                quote_literal(&table.glob),
+                quote_literal(&table.path_prefix),
+            ],
+        ),
+    };
     args.extend(ignore.iter().map(|p| quote_literal(p)));
 
     format!(
         "CREATE VIRTUAL TABLE IF NOT EXISTS temp.{} USING {}({})",
         quote_identifier(name),
-        vtab::MODULE_NAME,
+        module,
         args.join(", "),
     )
 }
@@ -184,6 +208,10 @@ pub struct Db {
     hint_legacy_files_table: bool,
     /// Skip rules a path-table scan applies, seeded with the built-in defaults.
     path_table_ignore: Vec<String>,
+    /// When set (the CLI's `--on-file`), every path-table is minted over the
+    /// parser instead of the stat columns: its rows and schema come from the
+    /// command's output. `None` keeps the stat path-table behavior.
+    path_table_parser: Option<String>,
 }
 
 /// The skip rules a fresh `Db` starts with.
@@ -210,11 +238,13 @@ impl Db {
         let conn = Connection::open("")?;
         ensure_internal_rows_table(&conn)?;
         vtab::load_module(&conn)?;
+        parsed_vtab::load_module(&conn)?;
         Ok(Self {
             conn,
             path_table_root: None,
             hint_legacy_files_table: false,
             path_table_ignore: default_path_table_ignore(),
+            path_table_parser: None,
         })
     }
 
@@ -228,11 +258,13 @@ impl Db {
         conn.pragma_update(None, "synchronous", "NORMAL")?;
         ensure_internal_rows_table(&conn)?;
         vtab::load_module(&conn)?;
+        parsed_vtab::load_module(&conn)?;
         Ok(Self {
             conn,
             path_table_root: None,
             hint_legacy_files_table: false,
             path_table_ignore: default_path_table_ignore(),
+            path_table_parser: None,
         })
     }
 
@@ -255,6 +287,13 @@ impl Db {
         self.path_table_ignore.extend(patterns);
     }
 
+    /// Attach a parser command to every path-table minted on this connection
+    /// (the CLI's `--on-file`). With it set, a path-table's rows and schema
+    /// come from the command's output instead of the stat columns.
+    pub fn set_path_table_parser(&mut self, command: String) {
+        self.path_table_parser = Some(command);
+    }
+
     /// Borrow the underlying SQLite connection. Internal use only — exposed
     /// to the `persist` module so it can manage the sidecar tables.
     #[doc(hidden)]
@@ -710,8 +749,12 @@ impl Db {
     /// straight on the connection rather than through [`query`](Self::query),
     /// which classifies `CREATE VIRTUAL TABLE` as a write and would reject it.
     fn create_path_table(&self, name: &str, table: &PathTable) -> Result<()> {
-        self.conn
-            .execute_batch(&path_table_ddl(name, table, &self.path_table_ignore))?;
+        self.conn.execute_batch(&path_table_ddl(
+            name,
+            table,
+            &self.path_table_ignore,
+            self.path_table_parser.as_deref(),
+        ))?;
         Ok(())
     }
 }
@@ -2095,7 +2138,7 @@ mod tests {
 
     #[test]
     fn path_table_ddl_creates_in_temp_if_not_exists() {
-        let ddl = path_table_ddl("./docs/*.md", &docs_path_table(), &[]);
+        let ddl = path_table_ddl("./docs/*.md", &docs_path_table(), &[], None);
         assert_eq!(
             ddl,
             "CREATE VIRTUAL TABLE IF NOT EXISTS temp.\"./docs/*.md\" \
@@ -2111,10 +2154,10 @@ mod tests {
             path_prefix: "/var/log".to_string(),
         };
         assert!(
-            path_table_ddl("/var/log/*.log", &table, &[])
+            path_table_ddl("/var/log/*.log", &table, &[], None)
                 .ends_with("'/var/log', '*.log', '/var/log')"),
             "got: {}",
-            path_table_ddl("/var/log/*.log", &table, &[])
+            path_table_ddl("/var/log/*.log", &table, &[], None)
         );
     }
 
@@ -2124,6 +2167,7 @@ mod tests {
             "./",
             &docs_path_table(),
             &["node_modules/**".to_string(), "*.tmp".to_string()],
+            None,
         );
         assert!(
             ddl.ends_with("'', 'node_modules/**', '*.tmp')"),
@@ -2131,6 +2175,53 @@ mod tests {
         );
     }
 
+    #[test]
+    fn path_table_ddl_uses_the_parsed_module_when_a_parser_is_set() {
+        let ddl = path_table_ddl("./docs/*.md", &docs_path_table(), &[], Some("cat {path}"));
+        assert_eq!(
+            ddl,
+            "CREATE VIRTUAL TABLE IF NOT EXISTS temp.\"./docs/*.md\" \
+             USING dirsql_parsed('/root', 'docs/*.md', 'cat {path}')"
+        );
+    }
+
+    #[test]
+    fn path_table_ddl_parser_form_omits_the_path_prefix_and_carries_ignore() {
+        let table = PathTable {
+            root: PathBuf::from("/var/log"),
+            glob: "*.log".to_string(),
+            path_prefix: "/var/log".to_string(),
+        };
+        let ddl = path_table_ddl(
+            "/var/log/*.log",
+            &table,
+            &["node_modules/**".to_string()],
+            Some("parse.py {path}"),
+        );
+        assert!(
+            ddl.ends_with(
+                "USING dirsql_parsed('/var/log', '*.log', 'parse.py {path}', 'node_modules/**')"
+            ),
+            "the parser form drops the path prefix and keeps ignore rules, got: {ddl}"
+        );
+    }
+
+    #[test]
+    fn path_table_ddl_parser_form_quotes_a_command_with_a_quote() {
+        let ddl = path_table_ddl("./", &docs_path_table(), &[], Some("sh -c 'echo hi'"));
+        assert!(
+            ddl.contains("'sh -c ''echo hi'''"),
+            "an embedded quote must be doubled, got: {ddl}"
+        );
+    }
+
+    #[test]
+    fn set_path_table_parser_arms_the_parsed_module() {
+        let mut db = Db::new().unwrap();
+        db.set_path_table_parser("cat {path}".to_string());
+        assert_eq!(db.path_table_parser.as_deref(), Some("cat {path}"));
+    }
+
     #[test]
     fn query_leaves_a_path_name_alone_without_a_root() {
         let db = Db::new().unwrap();