Change Logs vs Polling: A Practical Sync Design for Self-Hosted Apps

A self-hosted application can work perfectly well on one machine and still need to exchange data with another installation. The design question is not just how often to ask for changes. It is how to make synchronization observable, bounded, and safe to retry.

In the recent OrderRestro 1.9.0 work, the sync path is triggered from a change log and uses authenticated push/pull requests. That is a useful starting point for thinking about sync in any local-first system: record what changed, identify the peer allowed to exchange it, and give the operator a place to configure the relationship.

What polling gets right

Polling is easy to reason about. A client asks for updates on a schedule, and a missed request is naturally retried on the next interval. For a small system, that simplicity may be the right choice.

The cost is repeated work when nothing changed, plus a delay bounded by the polling interval. Short intervals reduce delay but multiply requests and make “the connection is alive” easy to confuse with “all changes are applied.”

What a change log adds

A change log makes the work explicit. The sync process can ask for changes since a known point instead of scanning the entire data set. It also gives you a starting place for answering the operator’s most important question: what is waiting to sync?

A change log is not a complete reliability strategy. Retries need idempotency. The system needs a policy for old cursors, partial batches, deletions, and conflicting edits. A dashboard should distinguish “last request succeeded” from “all changes are current.”

Questions to answer before shipping

1. Can the same change be applied twice without duplicating an order?
2. What happens if the network fails halfway through a batch?
3. Can an operator see pending changes and the last successful exchange?
4. Which system wins when the same record changes in two places?

I’m building these questions into the way I evaluate sync features. A green status indicator is useful only if it describes a meaningful, tested condition.

OrderRestro’s release history and source are public at https://github.com/Raktim94/nodedr-restaurant-pos. The implementation details are evolving, so treat the repository as the source of truth for the current release.

I write about the engineering behind OrderRestro and other self-hosted business software on RaktimRanjit.com.