dirsql 0.4.130 → 0.4.131

package/docs/howto/search-indexes.md

@@ -12,12 +12,16 @@ as in [Define tables for your files](./define-tables.md).
 
 ## Why triggers, and why only two
 
-`dirsql` writes file rows with plain `INSERT` and `DELETE`; an update is a
-delete and an insert in one transaction, and there is no `UPDATE` path on user
-rows. So an insert trigger and a delete trigger cover every way a row can
+`dirsql` writes the rows of a table with no key with plain `INSERT` and
+`DELETE`; a changed row is a delete and an insert in one transaction. So an
+insert trigger and a delete trigger cover every way a row can
 change — during the initial build, on each [watcher](./react-to-changes.md)
 event, and when a [persistent cache](./persist.md) reconciles a tree that
 moved on. There is no third trigger to write and no maintenance command to run.
+A table with a `PRIMARY KEY`, or a `UNIQUE` column the command fills, has its
+changed rows `UPDATE`d in place instead
+([hooks](../reference/hooks.md#on-file-contract)); give it an `AFTER UPDATE`
+trigger as well.
 
 The triggers are also the part that goes wrong, which is why the templates
 spell them out rather than hiding them behind an abstraction.

package/docs/reference/config.md

@@ -236,6 +236,11 @@ rows — filtered to the DDL — are the table. For plain stat columns with no
 command, query the path directly with a [path-table](./path-tables.md)
 instead of declaring a table.
 
+Tables' `on-file` commands run one table at a time, in declaration order:
+a table's command finishes before the next table's starts, whatever order
+their files sort in. That holds at startup and when a change under watch
+re-runs several tables at once.
+
 ```toml
 [[table]]
 name = "comments"
@@ -302,11 +307,14 @@ dirsql query "SELECT text FROM messages_fts WHERE messages_fts MATCH 'deploy'" \
   -c ./.dirsql.toml
 ```
 
-Those two triggers are all a keyword index needs. dirsql writes file rows with
-plain `INSERT` and `DELETE` — an update is a delete and an insert in one
-transaction, and there is no `UPDATE` path on user rows — so triggers you
-declare here stay current through the initial load and every
-[watcher](../howto/react-to-changes.md) event. The same shape with a `vec0`
+Those two triggers are all a keyword index needs. `messages` declares no key,
+so dirsql writes its rows with plain `INSERT` and `DELETE` — a changed row is a
+delete and an insert in one transaction — and triggers you declare here stay
+current through the initial load and every
+[watcher](../howto/react-to-changes.md) event. A table with a `PRIMARY KEY` or
+`UNIQUE` column the command fills has its changed rows `UPDATE`d in place
+instead (see [hooks](./hooks.md#on-file-contract)); give it an
+`AFTER UPDATE` trigger too. The same shape with a `vec0`
 virtual table and an [`embed()`](#dirsql-function) call in the trigger gives
 you stored vectors.
 
@@ -337,6 +345,39 @@ Two consequences of `ddl` running **once, when the table is created**:
   That is the only invalidation lane: dirsql tracks no ownership of what the
   batch made.
 
+### Foreign keys
+
+SQLite enforces a `REFERENCES` clause in a table's `ddl`. Tables fill in no
+fixed order, so `dirsql` checks foreign keys once per unit of work rather than
+per row: every constraint is deferred to the end of the unit, as if declared
+`DEFERRABLE INITIALLY DEFERRED`. A unit is the initial build, or one batch of
+[watcher](../howto/react-to-changes.md) events across all tables. A child may
+land before its parent, and a parent's file may change while its children
+point at it.
+
+A row that still references nothing when the unit ends fails the whole unit,
+and the error names each offending row, the file that produced it, and the
+values that match nothing:
+
+```text
+foreign key violation: `task` row from `projects/beta/tasks/t1.json` has project_id = 2, which matches no row in `project`
+```
+
+- **Build:** the build fails and nothing is written.
+- **Watch:** the batch is rolled back and reported as one error event, against
+  the child's table and file. The database stays as it was before the batch.
+  The rejected changes are retried with each later batch, as the files stand
+  then, and land with the first batch that resolves them, such as one that
+  repoints or deletes the orphaned child. Until then each later batch is also
+  tried on its own and lands if it leaves no orphan, and the error is reported
+  again. A table's `on-file` command re-reads all of its files, so a later
+  batch that touches the same table carries the orphaning change and waits
+  too.
+
+`ON DELETE` and `ON UPDATE` actions are not deferred. `dirsql` applies a changed
+file as a delete and an insert, so `ON DELETE CASCADE` deletes the children of a
+parent whose file is edited or renamed, even though their files still exist.
+
 ### `on-file` row mapping
 
 The command prints one JSON object per line (NDJSON); each line becomes one
@@ -369,6 +410,8 @@ The configs load and merge in **argv order**:
   that config file's own directory** — so a relative command like
   `on-file = "sh ./extract.sh"` resolves against the config that declared it,
   wherever it lives.
+- **`on-file` commands run in argv order**: every table of the first config,
+  in declaration order, before any table of the second.
 - Each config is **validated on its own** (the [parse errors](#parse-errors)
   below apply per file). There is no cross-file merge validation, with two
   structural exceptions: **two configs defining a table of the same name is

package/docs/reference/hooks.md

@@ -128,7 +128,22 @@ for path in sys.argv[1:]:
 There is no row-to-file attribution: dirsql does not know which file a row
 came from, and a row that needs the path carries it as a column the command
 emitted. In watch mode a change to any file under the table's glob re-runs
-the command over all of the table's files and replaces the table's rows.
+the command over all of the table's files and writes only the difference,
+comparing just the columns the command emits:
+
+- A table with a key matches old and new rows by it. The key is the
+  `PRIMARY KEY`, or else a `UNIQUE` constraint (or unique index) whose columns
+  the command fills, non-NULL, in every row. A matched row that changed is
+  `UPDATE`d in place, so its rowid and every column the command leaves out (a
+  generated `INTEGER PRIMARY KEY`, a default) keep their values, and the watch
+  stream carries an `update`. A key that disappears is deleted and a new key is
+  inserted.
+- A table without one has no row identity: a row the command still emits
+  stays put, and every other row is deleted or inserted.
+
+With `CREATE TABLE experiments (id INTEGER PRIMARY KEY, folder_name TEXT UNIQUE, name TEXT)`
+and a command that emits `folder_name` and `name`, renaming an experiment keeps
+its `id`, so a table that stores that `id` still points at it.
 
 The same command is attachable two ways, over the same contract: the
 `on-file` config key on a `[[table]]`, and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.4.130",
+  "version": "0.4.131",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -221,10 +221,10 @@
     ]
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.4.130",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.130",
-    "@dirsql/lib-darwin-x64": "0.4.130",
-    "@dirsql/lib-darwin-arm64": "0.4.130",
-    "@dirsql/lib-win32-x64-msvc": "0.4.130"
+    "@dirsql/lib-linux-x64-gnu": "0.4.131",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.131",
+    "@dirsql/lib-darwin-x64": "0.4.131",
+    "@dirsql/lib-darwin-arm64": "0.4.131",
+    "@dirsql/lib-win32-x64-msvc": "0.4.131"
   }
 }