fix(localdb): snapshot delivers FK-linked rows in any order (scadaproj#37)

The snapshot streamed tables by name and rows by pk_json text, so a child
(or a self-reference whose parent's key sorts later) reached the receiver
first, failed its immediate FK check and was dead-lettered - permanently,
since the snapshot's watermark and ack covered it (LocalDb-002).

Sender: stream referenced tables first (Kahn order, name tie-break).
Receiver: SnapshotApplier defers rows that fail only
SQLITE_CONSTRAINT_FOREIGNKEY, retries them as rows land, and dead-letters
true orphans at SnapshotComplete. Delta path unchanged; wire unchanged.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 14:52:35 -05:00
parent 48813bba6f
commit 4af0ea8152
7 changed files with 351 additions and 18 deletions
+9
View File
@@ -304,6 +304,15 @@ All options are validated at startup (`ZB.MOM.WW.Configuration` validators).
the parent unreplicated. The check runs at registration and reads the whole database's
foreign keys, so a child table created *after* registration is caught at the next startup,
not at the moment of the `CREATE TABLE`.
- **Foreign keys between replicated tables (`NO ACTION`/`RESTRICT`) survive a snapshot as of
`0.3.6`.** The sender streams referenced tables before the tables that reference them, and
the receiver defers a snapshot row that fails only its FK check, retrying it as more rows
land; one whose parent never arrives is dead-lettered at `SnapshotComplete`. Before `0.3.6`
a child that arrived before its parent (name order, or a self-reference whose parent's key
sorts later as `pk_json` text) was dead-lettered for good. **Mixed pairs:** a pre-`0.3.6`
receiver still loses self-referencing rows that arrive child-first, and a pre-`0.3.6`
sender's name order relies on the `0.3.6` receiver's deferral — so upgrade both nodes before
adding FK-linked tables. Deferred rows are held in memory until the snapshot completes.
- **CDC semantics** — rows that existed **before** `RegisterReplicated` are not captured
and are not snapshotted; only changes after registration are replicated. **Opt out with
`RegisterReplicated(table, baselineExistingRows: true)`**, which seeds the row-version