Sync from docs: disconnect/disconnectAndClear nuance and connect once-per-session rule (powersync-docs #602) - #86
Open
bean1352 wants to merge 1 commit into
Open
Conversation
…connect() once-per-session rule - SKILL.md: split disconnectAndClear() rule to cover same-user sign-out case where keeping local data is safe, prefer disconnect() to avoid a full re-sync on the next sign-in. - SKILL.md: add rule that .connect() must be called once per session; calling it on focus events, token refreshes, or network changes opens redundant sync connections. - powersync-debug.md: update disconnect()/disconnectAndClear() 'when to use each' list to include same-user sign-out as a valid disconnect() case, clarifying that disconnectAndClear() is required only when another user accesses the device or security requires wiping local data. Source: powersync-ja/powersync-docs#602 (reducing-usage page and FAQ rework)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Source docs PR: powersync-ja/powersync-docs#602
What changed in docs
PR #602 added a new "Reducing Usage" page (
resources/usage-and-billing/reducing-usage.mdx) covering data synced and data hosted optimization strategies, and extensively reworked the usage FAQ with more precise guidance ondisconnect()vsdisconnectAndClear(), the single-connect-per-session pattern, and causes of high sync operation counts.Skill updates in this PR
skills/powersync/SKILL.md: Split thedisconnectAndClear()Key Rule into a conditional rule covering both cases. Added a new Key Rule that.connect()must be called once per session, not on focus events or token refreshes.skills/powersync/references/powersync-debug.md: Updated the "when to use each" list in thedisconnectAndClear()section to include same-user sign-out as a validdisconnect()case, matching the nuance introduced in the new docs page.Notes for reviewer
disconnect()vsdisconnectAndClear()on sign-out: The new docs clarify thatdisconnectAndClear()is not always required on sign-out. If the same user will return to their own device and security permits retaining local data,disconnect()is preferable because the client resumes from its saved sync position instead of re-downloading everything. The existing debug file implieddisconnectAndClear()for any logout, which contradicted the new guidance. Both files now distinguish user-account switches (always usedisconnectAndClear()) from same-user sign-outs (usedisconnect()when safe)..connect()once per session: The docs FAQ added guidance that opening onePowerSyncDatabaseand calling.connect()once, rather than reconnecting on window focus or token refresh, prevents unnecessary concurrent client counts and reconnect overhead. This pattern was not previously documented in the Key Rules.Items intentionally left untouched: The new docs page also covers compacting, defragmenting, bucket fan-out, large column patterns,
auto_subscribebehavior, and no-op update footguns. The compacting/defragmenting and bucket fan-out topics already appear inpowersync-debug.mdandpowersync-service.md. Theauto_subscribebehavior is covered insync-config.md. No-op updates are a new addition to the docs but are operationally focused (a DBA concern rather than a code-generation concern); adding them to the debug reference may be worth considering in a follow-up.Snyk scan: The
snyk-agent-scandemo endpoint returned 403 (proxy blocked in the sandbox). Thenode scripts/validate.mjsvalidation passed. The changed lines contain no connection strings, hex IDs, literal credentials, or credential-harvesting wording, so the scan would be expected to pass.Generated by Claude Code