fix(db): publish one event per key for metadata-only sync commits #1795
main fromrefs/pull/1795/head·opened 🎯 Changes#
Fixes #1767.
Two optimistic writes in a row on the same key blow up on the second one:
Error: Query contributors with the same row key are not congruent
What's going on#
When a collection publishes a batch of changes, that batch is a diff, so each key should appear in it at most once. Here it appeared twice, with both events saying the same thing.
The sequence, using a query collection as the example:
- You make an optimistic update, and your
mutationFnacknowledges it withutils.writeUpsert. writeUpsertrefreshes the query cache, and applying that result records row ownership metadata. That metadata write goes into its own sync transaction — one with no row operations at all, just a metadata entry.- That transaction stays pending while your transaction is persisting.
- When your transaction completes, two different code paths each notice the row switching from optimistic to synced (
$synced: false → true), and both emit an event for it. Both land in the same published batch.
The guard meant to prevent that double-emit is recentlySyncedKeys, seeded by capturePreSyncVisibleState. But it derived its keys from a sync transaction's row operations only, while commitPendingTransactions derives its keys from operations plus row metadata writes. A metadata-only transaction fell straight through the gap between those two sets.
Downstream, the duplicated diff leaves the live query counting the old row at -2 and the new one at +2. The next optimistic write on that key then leaves two positive contributors with different values, which is exactly what the keyed reduction rejects.
That also explains the shape of the bug report: round one is what corrupts the bookkeeping, and round two is what notices.
The fix#
Pull the "which keys does this sync commit touch" derivation into a single helper, collectAffectedKeys, and use it in all three places that ask the question — commitPendingTransactions, capturePreSyncVisibleState, and cancelPendingSyncedTransaction. The bug was those key sets drifting apart, so this keeps them from drifting again rather than just patching the one that was behind.
Behaviour change is limited to the two sites that were missing metadata keys. commitPendingTransactions already had them.
Tests#
Two regression tests, both of which fail with the exact error before the fix:
packages/db/tests/collection-metadata-only-sync-commit.test.ts— core-level. Drives a metadata-only sync transaction directly through the sync API while an optimistic mutation is in flight, and asserts no published batch ever names one key twice.packages/query-db-collection/tests/optimistic-writeback.test.ts— the reported path, viautils.writeUpsert.
Why the existing tests missed it#
The suite covers sync transactions that carry row operations, and covers row metadata, but never a transaction that writes metadata with no row operations while an optimistic mutation is pending — the one shape where the two key sets disagree. The core test above closes that gap, and its "a batch never names a key twice" assertion is the more general form of the invariant, so it should catch other ways of producing a malformed batch too.
Verification#
db 3071 · query-db-collection 170 + 114 e2e · electric 242 · react-db 161 · offline-transactions 65 · powersync 92 · plus trailbase, rxdb, solid, svelte, vue and angular — all passing, typecheck and lint clean.
One note: collection-events.test.ts > should emit events with correct structure times out under full-suite load on my machine. It does the same on an unmodified main (3 runs out of 3), so it looks pre-existing and unrelated to this change.
✅ Checklist#
- I have tested this code locally with
pnpm test.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Summary by CodeRabbit#
Bug Fixes
- Fixed duplicate change events when synchronizing metadata-only updates.
- Prevented live queries from becoming inconsistent after repeated optimistic writes to the same record.
- Ensured synchronized metadata updates correctly participate in change tracking.
Tests
- Added regression coverage for metadata-only synchronization and consecutive optimistic updates.
- 1
Closing as superseded by merged #1797, which incorporates and tests one-event-per-key metadata-only sync publication. This branch no longer needs a separate merge.
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Team
Run ID:
1ea24d4d-9bc5-4758-8662-0330ef03e21f📥 Commits
Reviewing files that changed from the base of the PR and between 68366ecaeef6c12a13402b558bd4a68d7519442f and d48f28d747b2a187aa085db4ab39ac3ba0de6996.
📒 Files selected for processing (4)
.changeset/fix-metadata-only-sync-duplicate-events.mdpackages/db/src/collection/state.tspackages/db/tests/collection-metadata-only-sync-commit.test.tspackages/query-db-collection/tests/optimistic-writeback.test.tsIncluded review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.
📝 Walkthrough
Walkthrough#
The collection state now includes metadata-only sync keys when tracking affected rows. Sync commit, cancellation, and pre-sync capture use the shared helper. New regression tests cover duplicate events and consecutive optimistic writebacks.
Changes#
Metadata-only sync event deduplication
packages/db/src/collection/state.tscollectAffectedKeysgathers keys from sync operations and row metadata writes. Sync commit, cancellation, and pre-sync capture use this helper.packages/db/tests/collection-metadata-only-sync-commit.test.ts,packages/query-db-collection/tests/optimistic-writeback.test.ts,.changeset/fix-metadata-only-sync-duplicate-events.md@tanstack/db.Estimated code review effort: 3 (Moderate) | ~20 minutes
Merge Risk: ⚪ Minimal · up to
d48f2This localized change prevents duplicate events for metadata-only sync commits and protects optimistic writebacks from corrupting keyed query state; no actionable merge-blocking risk remains after normal checks and review.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
#1767by aligning affected-key tracking for metadata-only sync transactions. The regression tests cover duplicate event publication and consecutive optimistic writes through …Full details: Linked Issues check
Explanation
The changes address issue
#1767by aligning affected-key tracking for metadata-only sync transactions. The regression tests cover duplicate event publication and consecutive optimistic writes through the reported writeback path.Full details: Docstring Coverage
Explanation
No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3 files. (1 skipped: 1 unsupported.)
✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
❤️ Share