docs: add debugging section for awaitTxId stalling issues

[KyleAMathews]

Summary

• Added comprehensive debugging guide to help developers diagnose and fix the common issue where awaitTxId stalls or times out
• The root cause is querying pg_current_xact_id() outside the mutation transaction, causing txid mismatches

What's included

• Explanation of the root cause (txid mismatch)
• How to enable debug logging with localStorage.debug = '*'
• Example logs showing both mismatched and matched txids
• Correct pattern for querying txid inside sql.begin()
• References to working examples in the codebase

This addresses the frequent support issue where users report "2/3 times it just stalls, with no errors whatsoever" when using awaitTxId or tx.isPersisted.promise.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: af9fbce

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

More templates

• todos
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@651

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@651

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@651

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@651

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@651

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@651

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@651

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@651

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@651

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@651

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@651

commit: af9fbce

[github-actions]

Size Change: 0 B

Total Size: 75.9 kB

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/collection/change-events.js	943 B
./packages/db/dist/esm/collection/changes.js	1.01 kB
./packages/db/dist/esm/collection/events.js	660 B
./packages/db/dist/esm/collection/index.js	3.31 kB
./packages/db/dist/esm/collection/indexes.js	1.16 kB
./packages/db/dist/esm/collection/lifecycle.js	1.8 kB
./packages/db/dist/esm/collection/mutations.js	2.5 kB
./packages/db/dist/esm/collection/state.js	3.82 kB
./packages/db/dist/esm/collection/subscription.js	1.83 kB
./packages/db/dist/esm/collection/sync.js	1.65 kB
./packages/db/dist/esm/deferred.js	230 B
./packages/db/dist/esm/errors.js	3.1 kB
./packages/db/dist/esm/index.js	1.58 kB
./packages/db/dist/esm/indexes/auto-index.js	806 B
./packages/db/dist/esm/indexes/base-index.js	835 B
./packages/db/dist/esm/indexes/btree-index.js	2 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.21 kB
./packages/db/dist/esm/indexes/reverse-index.js	577 B
./packages/db/dist/esm/local-only.js	827 B
./packages/db/dist/esm/local-storage.js	2.02 kB
./packages/db/dist/esm/optimistic-action.js	294 B
./packages/db/dist/esm/proxy.js	3.86 kB
./packages/db/dist/esm/query/builder/functions.js	615 B
./packages/db/dist/esm/query/builder/index.js	4.04 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	938 B
./packages/db/dist/esm/query/compiler/evaluators.js	1.55 kB
./packages/db/dist/esm/query/compiler/expressions.js	760 B
./packages/db/dist/esm/query/compiler/group-by.js	2.04 kB
./packages/db/dist/esm/query/compiler/index.js	2.04 kB
./packages/db/dist/esm/query/compiler/joins.js	2.52 kB
./packages/db/dist/esm/query/compiler/order-by.js	1.21 kB
./packages/db/dist/esm/query/compiler/select.js	1.28 kB
./packages/db/dist/esm/query/ir.js	785 B
./packages/db/dist/esm/query/live-query-collection.js	340 B
./packages/db/dist/esm/query/live/collection-config-builder.js	2.69 kB
./packages/db/dist/esm/query/live/collection-subscriber.js	1.92 kB
./packages/db/dist/esm/query/optimizer.js	3.08 kB
./packages/db/dist/esm/SortedMap.js	1.24 kB
./packages/db/dist/esm/transactions.js	3 kB
./packages/db/dist/esm/utils.js	1.01 kB
./packages/db/dist/esm/utils/browser-polyfills.js	365 B
./packages/db/dist/esm/utils/btree.js	6.01 kB
./packages/db/dist/esm/utils/comparison.js	754 B
./packages/db/dist/esm/utils/index-optimization.js	1.73 kB

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 1.47 kB

ℹ️ View Unchanged

Filename	Size
./packages/react-db/dist/esm/index.js	152 B
./packages/react-db/dist/esm/useLiveQuery.js	1.32 kB

_{compressed-size-action::react-db-package-size}

[samwillis]

LGTM, just one thought below