Skip to main content

PowerSync: Designed for Causal+ Consistency

PowerSync is designed to have causal+ consistency, while providing enough flexibility for applications to perform their own data validations and conflict handling. PowerSync’s consistency properties have been tested and verified.

How It Works: Checkpoints

A checkpoint is a single point-in-time on the server (similar to an LSN in Postgres) with a consistent state: only fully committed transactions are part of the state. The client only updates its local state when it has all the data matching a checkpoint, and then it updates the state to exactly match that of the checkpoint. There is no intermediate state while downloading large sets of changes such as large server-side transactions. Different tables and buckets are all included in the same consistent checkpoint, to ensure that the state is consistent over all data in the client. Checkpoint Requests (currently in an alpha release) let you wait until the local database has applied a new point-in-time checkpoint after the initial sync.

Client-Side Mutations

Client-side mutations are applied on top of the last checkpoint received from the , as well as being persisted into an upload queue. While mutations are present in the upload queue, the client does not advance to a new checkpoint. This means the client never has to resolve conflicts locally. Only once all the client-side mutations have been acknowledged by the server, and the data for that new checkpoint is downloaded by the client, does the client advance to the next checkpoint. This ensures that the operations are always ordered correctly on the client.
There is one nuanced case here, which is buckets with Priority 0 if you are using Prioritized Syncing.

Validation and Conflict Handling

Your backend decides how each uploaded mutation is applied, so it also decides what happens when one fails, for example because it violates a constraint or an access rule. Because the client doesn’t advance to a new checkpoint while mutations are queued, a mutation that stays in the upload queue also holds back newer synced data. What Happens When a Write Fails explains how to handle each kind of failure. See also:

Questions?

If you have any questions about consistency, please join our Discord to discuss.