dirsql 0.4.106__tar.gz → 0.4.108__tar.gz

{dirsql-0.4.106 → dirsql-0.4.108}/Cargo.lock

@@ -573,7 +573,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql"
-version = "0.4.106"
+version = "0.4.108"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -625,7 +625,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.106"
+version = "0.4.108"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.106 → dirsql-0.4.108}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.106
+Version: 0.4.108
 Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

{dirsql-0.4.106 → dirsql-0.4.108}/docs/howto/react-to-changes.md

@@ -7,7 +7,8 @@ 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. A named table's columns are whatever
+watched, so `watch()` on an instance with no named tables raises an error and
+`/events` returns `503`. Define one next to your files. A named table's columns are whatever
 its [`on-file`](../reference/config.md#table) hook emits; here a minimal hook
 prints each file's basename:
 

{dirsql-0.4.106/packages/rust → dirsql-0.4.108}/docs/reference/http-api.md

@@ -115,4 +115,4 @@ Row values serialize as in [`POST /query`](#value-serialization).
 |---|---|
 | `200` | Stream opened (`text/event-stream`). |
 | `405` | `POST /events`. Plain-text body `method not allowed`. |
-| `503` | The server is in [degraded mode](./cli.md#degraded-mode), or its filesystem watcher failed to start (for example, the inotify limit is exhausted). JSON `{"error": …}` body; for a watcher failure the message starts `filesystem watcher failed to start:` and gives the reason. `POST /query` keeps working. |
+| `503` | The server is in [degraded mode](./cli.md#degraded-mode), or its filesystem watcher failed to start (for example, the inotify limit is exhausted, or the instance has no named tables). JSON `{"error": …}` body; for a watcher failure the message starts `filesystem watcher failed to start:` and gives the reason. `POST /query` keeps working. |

{dirsql-0.4.106 → dirsql-0.4.108}/docs/reference/sdk.md

@@ -301,6 +301,10 @@ under the root. The watcher starts on first iteration (Python/TypeScript)
 or at the `watch()` call (Rust). The stream never terminates on its own;
 stop consuming it to stop.
 
+An instance with no named tables cannot be watched: path-tables emit no
+watch events, so `watch()` (and the polling primitives) raise an error naming
+that cause. Define a table first.
+
 Python/TypeScript: each `watch()` call returns an independent stream, and every stream
 on one instance receives every event observed after it was created, so
 several consumers (one per client, say) can share one instance.

{dirsql-0.4.106 → dirsql-0.4.108}/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.4.106"
+version = "0.4.108"
 # abi3 note: the `abi3-py310` pyo3 feature (below) builds ONE stable-ABI
 # `cp310-abi3` wheel per platform that loads on every CPython >= 3.10
 # (matching `pyproject.toml`'s `requires-python = ">=3.10"`), instead of

dirsql-0.4.108/packages/python/changelog.d/2026-10-08-watch-requires-named-table.md

@@ -0,0 +1 @@
+**Changed** — `watch()` (and the polling primitives) on an instance with no named tables now fails immediately with `watching requires at least one named table: path-tables emit no watch events; define a table`, instead of starting a watcher that never yields. The `dirsql server` `/events` endpoint returns 503 with the same reason; `/query` is unaffected.

{dirsql-0.4.106/packages/rust → dirsql-0.4.108/packages/python}/docs/howto/react-to-changes.md

@@ -7,7 +7,8 @@ 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. A named table's columns are whatever
+watched, so `watch()` on an instance with no named tables raises an error and
+`/events` returns `503`. Define one next to your files. A named table's columns are whatever
 its [`on-file`](../reference/config.md#table) hook emits; here a minimal hook
 prints each file's basename:
 

{dirsql-0.4.106 → dirsql-0.4.108}/packages/python/docs/reference/http-api.md

@@ -115,4 +115,4 @@ Row values serialize as in [`POST /query`](#value-serialization).
 |---|---|
 | `200` | Stream opened (`text/event-stream`). |
 | `405` | `POST /events`. Plain-text body `method not allowed`. |
-| `503` | The server is in [degraded mode](./cli.md#degraded-mode), or its filesystem watcher failed to start (for example, the inotify limit is exhausted). JSON `{"error": …}` body; for a watcher failure the message starts `filesystem watcher failed to start:` and gives the reason. `POST /query` keeps working. |
+| `503` | The server is in [degraded mode](./cli.md#degraded-mode), or its filesystem watcher failed to start (for example, the inotify limit is exhausted, or the instance has no named tables). JSON `{"error": …}` body; for a watcher failure the message starts `filesystem watcher failed to start:` and gives the reason. `POST /query` keeps working. |

{dirsql-0.4.106/packages/rust → dirsql-0.4.108/packages/python}/docs/reference/sdk.md

@@ -301,6 +301,10 @@ under the root. The watcher starts on first iteration (Python/TypeScript)
 or at the `watch()` call (Rust). The stream never terminates on its own;
 stop consuming it to stop.
 
+An instance with no named tables cannot be watched: path-tables emit no
+watch events, so `watch()` (and the polling primitives) raise an error naming
+that cause. Define a table first.
+
 Python/TypeScript: each `watch()` call returns an independent stream, and every stream
 on one instance receives every event observed after it was created, so
 several consumers (one per client, say) can share one instance.

dirsql-0.4.108/packages/python/e2e-attestations/bot-1406-watch-no-tables-1008.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/server_speed_test.py tests/e2e/query_contract_test.py tests/e2e/sigint_interrupt_test.py tests/e2e/cli_version_test.py -x -q",
+  "ran_at": 1791474667,
+  "exit_code": 0,
+  "commit": "31f567c6cc0e5873a9bdc41df84e95a6722527f1",
+  "branch": "bot/1406-watch-no-tables-1008"
+}

dirsql-0.4.108/packages/python/e2e-attestations/bot-1461-row-footprint-1008.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/query_contract_test.py tests/e2e/on_file_query_test.py tests/e2e/stat_speed_test.py tests/e2e/glob_speed_one_level_test.py tests/e2e/glob_speed_recursive_test.py tests/e2e/use_case_dossier_test.py -x -q",
+  "ran_at": 1791489188,
+  "exit_code": 0,
+  "commit": "fe75eb79358f5324a5af3395d1e2383e6233c98f",
+  "branch": "bot/1461-row-footprint-1008"
+}

dirsql-0.4.108/packages/python/migrations.d/2026-10-08-watch-requires-named-table.md

@@ -0,0 +1,23 @@
+### `watch()` requires a named table
+
+#### Summary
+
+`watch()`, `poll_events()`/`pollEvents()` and `start_watching()`/`startWatcher()` on an instance with no named tables now raise an error naming the cause, rather than watching and silently yielding nothing. Path-tables emit no watch events. Instances with at least one named table are unaffected.
+
+#### Required changes
+
+| Before | After |
+| --- | --- |
+| `DirSQL(root).watch()` yields nothing forever | Define a table (programmatic or `[[table]]`), or stop calling `watch()` |
+
+#### Deprecations removed
+
+_None._
+
+#### Behavior changes without code changes
+
+A path-table-only instance that called `watch()` now gets an error. `dirsql server` with no tables returns 503 from `/events`.
+
+#### Verification
+
+Run `dirsql server -c <config with no [[table]]>` and `curl -i http://localhost:7117/events`; expect `503` naming "path-tables emit no watch events".

{dirsql-0.4.106 → dirsql-0.4.108}/packages/rust/Cargo.toml

@@ -6,7 +6,7 @@ description = "Ephemeral SQL index over a local directory"
 # version stays for the binding crates (publish = false). The literal
 # intentionally lags the published version: putitoutthere rewrites it to
 # the planned release version at build time and never commits it back.
-version = "0.4.106"
+version = "0.4.108"
 edition.workspace = true
 # Literal `license` (not `license.workspace = true`) because
 # putitoutthere's preflight check reads `[package].license` directly

{dirsql-0.4.106/packages/python → dirsql-0.4.108/packages/rust}/docs/howto/react-to-changes.md

@@ -7,7 +7,8 @@ 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. A named table's columns are whatever
+watched, so `watch()` on an instance with no named tables raises an error and
+`/events` returns `503`. Define one next to your files. A named table's columns are whatever
 its [`on-file`](../reference/config.md#table) hook emits; here a minimal hook
 prints each file's basename:
 

{dirsql-0.4.106 → dirsql-0.4.108/packages/rust}/docs/reference/http-api.md

@@ -115,4 +115,4 @@ Row values serialize as in [`POST /query`](#value-serialization).
 |---|---|
 | `200` | Stream opened (`text/event-stream`). |
 | `405` | `POST /events`. Plain-text body `method not allowed`. |
-| `503` | The server is in [degraded mode](./cli.md#degraded-mode), or its filesystem watcher failed to start (for example, the inotify limit is exhausted). JSON `{"error": …}` body; for a watcher failure the message starts `filesystem watcher failed to start:` and gives the reason. `POST /query` keeps working. |
+| `503` | The server is in [degraded mode](./cli.md#degraded-mode), or its filesystem watcher failed to start (for example, the inotify limit is exhausted, or the instance has no named tables). JSON `{"error": …}` body; for a watcher failure the message starts `filesystem watcher failed to start:` and gives the reason. `POST /query` keeps working. |

{dirsql-0.4.106/packages/python → dirsql-0.4.108/packages/rust}/docs/reference/sdk.md

@@ -301,6 +301,10 @@ under the root. The watcher starts on first iteration (Python/TypeScript)
 or at the `watch()` call (Rust). The stream never terminates on its own;
 stop consuming it to stop.
 
+An instance with no named tables cannot be watched: path-tables emit no
+watch events, so `watch()` (and the polling primitives) raise an error naming
+that cause. Define a table first.
+
 Python/TypeScript: each `watch()` call returns an independent stream, and every stream
 on one instance receives every event observed after it was created, so
 several consumers (one per client, say) can share one instance.

{dirsql-0.4.106 → dirsql-0.4.108}/packages/rust/src/cli/server.rs

@@ -109,6 +109,16 @@ fn start_watch_task(db: DirSQL, tx: broadcast::Sender<String>) -> Option<String>
 mod tests {
     use super::*;
 
+    fn db_with_a_table(root: &std::path::Path) -> DirSQL {
+        let config = root.join("dirsql.toml");
+        std::fs::write(
+            &config,
+            "[[table]]\nname = \"t\"\nddl = \"CREATE TABLE t (x TEXT)\"\nglob = \"*.none\"\non-file = \"true\"\n",
+        )
+        .unwrap();
+        DirSQL::builder().root(root).config(config).build().unwrap()
+    }
+
     // An `Unavailable` state needs no DB/filesystem, so the real bind /
     // graceful-shutdown plumbing runs without standing up an index.
     #[tokio::test]
@@ -130,7 +140,7 @@ mod tests {
     #[tokio::test]
     async fn serve_with_a_ready_db_attaches_the_watcher_then_shuts_down() {
         let dir = tempfile::tempdir().unwrap();
-        let db = DirSQL::new(dir.path(), Vec::new()).unwrap();
+        let db = db_with_a_table(dir.path());
         let config = ServerConfig::bind("127.0.0.1".to_string(), 0);
         let handle = serve(config, db).await.expect("bind on an ephemeral port");
         assert_ne!(handle.local_addr().port(), 0);
@@ -140,17 +150,29 @@ mod tests {
     #[tokio::test]
     async fn start_watch_task_reports_no_failure_once_the_watcher_attaches() {
         let dir = tempfile::tempdir().unwrap();
-        let db = DirSQL::new(dir.path(), Vec::new()).unwrap();
+        let db = db_with_a_table(dir.path());
         let (tx, _) = broadcast::channel::<String>(1);
         assert_eq!(start_watch_task(db, tx), None);
     }
 
+    #[tokio::test]
+    async fn start_watch_task_names_the_cause_without_named_tables() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = DirSQL::new(dir.path(), Vec::new()).unwrap();
+        let (tx, _) = broadcast::channel::<String>(1);
+        let reason = start_watch_task(db, tx).expect("watch() must fail");
+        assert!(
+            reason.contains("path-tables emit no watch events"),
+            "got: {reason}"
+        );
+    }
+
     // `poll_events` locks out `watch`, the one deterministic way to make the
     // watcher refuse to attach without exhausting inotify.
     #[tokio::test]
     async fn start_watch_task_returns_the_reason_when_the_watcher_cannot_attach() {
         let dir = tempfile::tempdir().unwrap();
-        let db = DirSQL::new(dir.path(), Vec::new()).unwrap();
+        let db = db_with_a_table(dir.path());
         db.poll_events(std::time::Duration::ZERO).unwrap();
         let (tx, _) = broadcast::channel::<String>(1);
         let reason = start_watch_task(db, tx).expect("watch() must fail");

{dirsql-0.4.106 → dirsql-0.4.108}/packages/rust/src/lib.rs

@@ -407,13 +407,6 @@ impl Table {
 struct DirSqlInner {
     db: Mutex<Db>,
     root: PathBuf,
-    /// Canonicalized `root`, used **only** for the live filesystem watcher:
-    /// `notify` misbehaves on relative paths (it may deliver no events, or
-    /// deliver them under the cwd-joined path so the relative prefix no
-    /// longer strips). Literal fallback when canonicalization fails (e.g. a
-    /// not-yet-created root); the user's `root` — and therefore the initial
-    /// scan and the `path` column — stays byte-for-byte unchanged.
-    watch_root: PathBuf,
     /// One entry per distinct table anchor; each holds the matcher for the
     /// tables anchored there.
     groups: Vec<AnchorGroup>,
@@ -437,13 +430,7 @@ struct DirSqlInner {
     fs: Arc<dyn FileSystem>,
 }
 
-fn watch_scopes(index_root: &Path, groups: &[AnchorGroup]) -> Vec<WatchScope> {
-    if groups.is_empty() {
-        return vec![WatchScope {
-            root: index_root.to_path_buf(),
-            ignore: TableMatcher::new(&[], &[]).expect("no patterns to compile"),
-        }];
-    }
+fn watch_scopes(groups: &[AnchorGroup]) -> Vec<WatchScope> {
     groups
         .iter()
         .map(|group| WatchScope {
@@ -456,8 +443,11 @@ fn watch_scopes(index_root: &Path, groups: &[AnchorGroup]) -> Vec<WatchScope> {
 /// The tables sharing one anchor, matched against paths relative to it.
 struct AnchorGroup {
     anchor: PathBuf,
-    /// `anchor` canonicalized for the live watcher; see
-    /// [`DirSqlInner::watch_root`].
+    /// `anchor` canonicalized for the live watcher only: `notify` misbehaves
+    /// on relative paths (it may deliver no events, or deliver them under the
+    /// cwd-joined path so the relative prefix no longer strips). Literal
+    /// fallback when canonicalization fails; `anchor` and the `path` column
+    /// stay byte-for-byte as supplied.
     watch_anchor: PathBuf,
     matcher: TableMatcher,
     tables: Vec<String>,
@@ -585,6 +575,7 @@ impl DirSQL {
     /// no-ops. Called implicitly by [`poll_events`](Self::poll_events) and
     /// [`watch`](Self::watch).
     pub fn start_watching(&self) -> Result<()> {
+        self.require_named_tables()?;
         let mut guard = self.inner.watcher.lock().map_err(DirSqlError::lock)?;
         if guard.is_none() {
             // Watch the canonicalized anchors, never the (possibly relative)
@@ -595,11 +586,19 @@ impl DirSQL {
         Ok(())
     }
 
+    fn require_named_tables(&self) -> Result<()> {
+        if self.inner.groups.is_empty() {
+            return Err(DirSqlError::watch_msg(
+                "watching requires at least one named table: path-tables emit no watch events; define a table",
+            ));
+        }
+        Ok(())
+    }
+
     /// The trees the live watcher must cover: each table anchor, under the
-    /// skip rules its tables' scan applies. A build with no tables still
-    /// watches the index root.
+    /// skip rules its tables' scan applies.
     fn watch_scopes(&self) -> Vec<WatchScope> {
-        watch_scopes(&self.inner.watch_root, &self.inner.groups)
+        watch_scopes(&self.inner.groups)
     }
 
     /// Poll-based watch API. Blocks up to `timeout` waiting for the next
@@ -680,6 +679,7 @@ impl DirSQL {
     ///
     /// Mutually exclusive with [`poll_events`](Self::poll_events).
     pub fn watch(&self) -> Result<WatchStream> {
+        self.require_named_tables()?;
         if self.inner.poll_used.load(Ordering::SeqCst) {
             return Err(DirSqlError::watch_msg(
                 "poll_events() already in use; cannot call watch()",
@@ -1583,9 +1583,6 @@ impl DirSQL {
         // Commit the ingest transaction.
         _tx.commit().map_err(DirSqlError::sqlite)?;
 
-        // Canonicalize the watch root so the live watcher never sees a
-        // relative path; `root` itself is left untouched.
-        let watch_root = PathBuf::from(fs.canonical_root(&root));
         let mut groups = groups;
         for group in &mut groups {
             group.watch_anchor = PathBuf::from(fs.canonical_root(&group.anchor));
@@ -1595,7 +1592,6 @@ impl DirSQL {
             inner: Arc::new(DirSqlInner {
                 db: Mutex::new(db),
                 root,
-                watch_root,
                 groups,
                 on_file_map,
                 strict_map,
@@ -3436,11 +3432,11 @@ mod internal_tests {
         );
     }
 
-    /// Building with a **relative** root canonicalizes `watch_root` to an
+    /// Building with a **relative** root canonicalizes the watch anchor to an
     /// absolute path while leaving `root` exactly as the caller supplied it,
     /// so `notify` never sees `.`.
     #[test]
-    fn relative_root_canonicalizes_watch_root_only() {
+    fn relative_root_canonicalizes_watch_anchor_only() {
         let canonical = if cfg!(windows) {
             r"C:\ws\canonical"
         } else {
@@ -3462,11 +3458,11 @@ mod internal_tests {
 
         assert_eq!(db.inner.root, PathBuf::from("."));
         assert!(
-            db.inner.watch_root.is_absolute(),
-            "watch_root must be absolute, got {:?}",
-            db.inner.watch_root
+            db.inner.groups[0].watch_anchor.is_absolute(),
+            "watch_anchor must be absolute, got {:?}",
+            db.inner.groups[0].watch_anchor
         );
-        assert_eq!(db.inner.watch_root, PathBuf::from(canonical));
+        assert_eq!(db.inner.groups[0].watch_anchor, PathBuf::from(canonical));
     }
 
     /// With an absolute root, `process_file_event` strips the `watch_root`
@@ -3730,8 +3726,17 @@ mod internal_tests {
     /// tableless for these lock-poison / error-path tests.
     fn simple_db() -> (TempDir, DirSQL) {
         let dir = TempDir::new().unwrap();
-        let db =
-            DirSQL::with_ignore(dir.path(), Vec::<Table>::new(), Vec::<String>::new()).unwrap();
+        let db = DirSQL::with_ignore(
+            dir.path(),
+            vec![Table::new(
+                "t",
+                "CREATE TABLE t (x TEXT)",
+                "*.none",
+                |_| vec![],
+            )],
+            Vec::<String>::new(),
+        )
+        .unwrap();
         (dir, db)
     }
 
@@ -4141,6 +4146,27 @@ mod internal_tests {
         );
     }
 
+    #[test]
+    fn watch_without_named_tables_names_the_cause() {
+        let db = DirSQL::new(TempDir::new().unwrap().path(), vec![]).unwrap();
+        let err = db.watch().unwrap_err().to_string();
+        assert!(
+            err.contains("path-tables emit no watch events"),
+            "got: {err}"
+        );
+        assert!(err.contains("define a table"), "got: {err}");
+    }
+
+    #[test]
+    fn poll_events_without_named_tables_names_the_cause() {
+        let db = DirSQL::new(TempDir::new().unwrap().path(), vec![]).unwrap();
+        let err = db.poll_events(Duration::ZERO).unwrap_err().to_string();
+        assert!(
+            err.contains("path-tables emit no watch events"),
+            "got: {err}"
+        );
+    }
+
     #[test]
     fn watch_twice_reports_already_started() {
         let (_dir, db) = simple_db();
@@ -4968,7 +4994,16 @@ mod internal_tests {
     #[tokio::test]
     async fn async_dirsql_builds_queries_and_forwards() {
         let dir = TempDir::new().unwrap();
-        let adb = AsyncDirSQL::new(dir.path(), Vec::<Table>::new()).unwrap();
+        let adb = AsyncDirSQL::new(
+            dir.path(),
+            vec![Table::new(
+                "t",
+                "CREATE TABLE t (x TEXT)",
+                "*.none",
+                |_| vec![],
+            )],
+        )
+        .unwrap();
         adb.ready().await.unwrap();
         let rows = adb.query("SELECT 1 AS n").await.unwrap();
         assert_eq!(rows[0]["n"], Value::Integer(1));
@@ -4984,7 +5019,16 @@ mod internal_tests {
     #[tokio::test]
     async fn async_dirsql_watch_forwards() {
         let dir = TempDir::new().unwrap();
-        let adb = AsyncDirSQL::new(dir.path(), Vec::<Table>::new()).unwrap();
+        let adb = AsyncDirSQL::new(
+            dir.path(),
+            vec![Table::new(
+                "t",
+                "CREATE TABLE t (x TEXT)",
+                "*.none",
+                |_| vec![],
+            )],
+        )
+        .unwrap();
         adb.ready().await.unwrap();
         let _stream = adb.watch().unwrap();
     }
@@ -5848,7 +5892,7 @@ mod internal_tests {
             .collect();
         let ignore: Vec<String> = ignore.iter().map(|p| p.to_string()).collect();
         let (groups, _, _) = compile_groups(&tables, &ignore, Path::new("/idx")).unwrap();
-        watch_scopes(Path::new("/canonical-idx"), &groups)
+        watch_scopes(&groups)
     }
 
     fn roots(scopes: &[WatchScope]) -> Vec<PathBuf> {
@@ -5860,14 +5904,10 @@ mod internal_tests {
         let dir = TempDir::new().unwrap();
         let db = populated_db(dir.path(), "**/*.txt", &["a.txt"]);
 
-        assert_eq!(roots(&db.watch_scopes()), vec![db.inner.watch_root.clone()]);
-    }
-
-    #[test]
-    fn watch_scopes_without_tables_is_the_whole_index_root() {
-        let scopes = scopes_for(&[], &[]);
-        assert_eq!(roots(&scopes), vec![PathBuf::from("/canonical-idx")]);
-        assert!(!scopes[0].ignore.is_ignored_dir(Path::new("node_modules")));
+        assert_eq!(
+            roots(&db.watch_scopes()),
+            vec![db.inner.groups[0].watch_anchor.clone()]
+        );
     }
 
     #[test]