Manual sync
The sync worker runs every 30 seconds on its own. Most of the time you don’t think about it. But there are moments — right after a big import, when you want to verify a fix landed everywhere, when a paired device looks stale — where waiting up to 30 seconds is too long. The Force sync now button runs a sync cycle out of band, right now.
What the button does
Clicking Force sync now in Settings → System → Cloud Sync triggers a single, full sync cycle on this desktop. The same four steps the auto-worker runs:
Healthcheck
GET /api/sync/health against the cloud, 5-second timeout. Failure aborts the cycle and shows a red status pill. The 30-second auto-worker keeps running underneath.
Push dirty rows
Bundle every locally-modified row (_isDirty = 1) and POST to /api/sync/push. Cloud writes them, runs FK resolution, returns confirmed UUIDs.
Pull what changed elsewhere
GET /api/sync/pull?since=<lastSyncedAt>. Merge the returned rows into local SQLite, resolving conflicts last-write-wins on updated_at.
Stamp success
Round-tripped rows get _lastSyncedAt = now, _isDirty = 0. The button shows a green pill with the new last-synced timestamp.
The whole cycle usually takes 1-3 seconds. A fresh-paired device’s first cycle pulls the full tenant snapshot and can take 30+ seconds — that’s a one-time cost.
When to reach for it
Five real reasons:
- Right after a bulk import — you imported 500 products on tablet A. You’re switching to tablet B to verify they show up. Force sync on B to skip the 30-second wait.
- You’re about to power down — closing up shop, want to make sure today’s sales pushed before the desktop sleeps. Force sync, see the green pill, walk away.
- Stale data alert on another device — paired tablet B says Last seen 14 minutes ago on the Devices panel. Force sync on B to refresh its check-in, or call the cashier to do it.
- Investigating a “where did my edit go?” report — force sync on both devices, compare values. If they still differ, you’re looking at a conflict, not a sync delay.
- After a network outage — Wi-Fi just came back, dirty rows have been piling up locally. Force sync clears the backlog instead of waiting for the next 30-second tick.
When not to use it
- Repeatedly, in a tight loop — if force-sync solves a problem, the next auto-cycle would have solved it 30 seconds later. If repeated force-syncs don’t solve it, the issue isn’t sync timing — see Sync troubleshooting.
- As a “fix” for stuck dirty rows — rows that won’t push usually have a real error (FK violation, schema mismatch). Force sync just retries the same broken push. Look at the error in the sync log instead.
- Mid-checkout — the API client routes through the cycle, so force-syncing while a cashier is on the checkout dialog can briefly stall the form. Wait until they’re done.
The header status pill
Above and beyond the System-tab button, the app’s top header shows a small sync status pill the whole time you’re logged in. Three states:
| Pill | Meaning |
|---|---|
Green dot · Synced 12s ago | Last cycle succeeded recently. Healthy. |
Yellow dot · Syncing... | A cycle is in flight right now. |
Red dot · Offline · last sync 3h ago | Last cycle failed; on local-only fallback. |
Clicking the pill opens the sync log overlay — last 20 cycles with timing, push/pull row counts, and any errors. Useful for “is this device actually syncing?” without leaving POS to open Settings.
Push then pull, in that order
Force sync always pushes before pulling. This matters because if you’ve made local edits that haven’t synced yet and the cloud has also received edits to the same rows from another device, the push side ensures your edits are time-stamped at their original updated_at (when you made them) — not at sync-time. Last-write-wins then correctly compares timestamps and resolves to whoever’s edit was actually most recent in real time.
Pulling first would lose this — the pull would overwrite your dirty rows with cloud values, then your push would re-overwrite the cloud, and the timestamp ordering would lie about who wrote when.
Force pull from cloud
Hidden under Show advanced below the Force sync button. This bypasses the push step and only runs the pull. Use it when you want to grab the cloud’s view as authoritative without sending up your local dirty rows yet — useful in rare debug-style scenarios where you suspect your local writes are bad data.
99% of users should never touch this. The default Force sync is what you want.
Related
Sync overview
The 30-second auto-cycle and the WebSocket realtime channel.
Conflict resolution
Last-write-wins and the corner cases force sync can’t resolve.
Device list
Last-seen-at and per-device sync stats — see if force sync changes them.
Sync troubleshooting
When force sync doesn’t fix it.