Skip to main content
Sync Rules are deprecated. For the Sync Streams version of this page, see Prioritized Sync.

​
Overview

PowerSync supports defining sync priorities, which allows you to control the sync order for different data. This is useful when certain data should be available sooner than others. In Sync Rules, you assign priorities to bucket definitions. The priority determines when data in that bucket syncs relative to other buckets.
AvailabilityThis feature was introduced in version 1.7.1 of the PowerSync Service, and in the following SDK versions:

​
Why Use Sync Priorities?

PowerSync’s standard sync protocol ensures that:
  • The local data view is only updated when a fully consistent checkpoint is available.
  • All pending local changes must be uploaded, acknowledged, and synced back before new data is applied.
While this guarantees consistency, it can lead to delays, especially for large datasets or continuous client-side updates. Sync priorities provide a way to speed up syncing of high-priority data while still maintaining overall integrity.

​
How It Works

Each bucket is assigned a priority value between 0 and 3, where:
  • 0 is the highest priority and has special behavior (detailed below).
  • 3 is the default and lowest priority.
  • Lower numbers indicate higher priority.
Higher-priority data syncs first, and lower-priority data syncs later. If you only use a single priority, there is no difference between priorities 1-3. The difference only comes in when you use multiple different priorities.

​
Syntax and Configuration

Define priorities using the priority YAML key on a bucket definition, or with the _priority attribute inside a parameter query:
Priorities must be static and cannot depend on row values within a parameter query.

​
Example: Syncing Lists Before Todos

Consider a scenario where you want to display lists immediately while loading todos in the background. This approach allows users to view and interact with lists right away without waiting for todos to sync.
The user_lists bucket syncs first (priority 1), allowing users to see and interact with their lists immediately. The user_todos bucket syncs afterward (priority 2), loading in the background.

​
Behavioral Considerations

  • Interruption for Higher Priority Data: Syncing lower-priority data may be interrupted if new data for higher-priority buckets arrives.
  • Local Changes & Consistency: If local writes fail due to validation or permission issues, they are only reverted after all data has synced.
  • Deleted Data: Deleted data may only be removed after all priorities have completed syncing.
  • Data Ordering: Lower-priority data will never appear before higher-priority data.

​
Special Case: Priority 0

Priority 0 buckets sync regardless of pending uploads. For example, in a collaborative document editing app (e.g., using Yjs), each change is stored as a separate row. Since out-of-order updates don’t affect document integrity, Priority 0 can ensure immediate availability of updates. Caution: If misused, Priority 0 may cause flickering or inconsistencies, as updates could arrive out of order.

​
Consistency Considerations

PowerSync’s full consistency guarantees only apply once all priorities have completed syncing. When higher-priority data is synced, all inserts and updates at that priority level will be consistent. However, deletes are only applied when the full sync completes, so you may still have some stale data at those priority levels. Consider the following example: Imagine a task management app where users create lists and todos. Some users have millions of todos. To improve first-load speed:
  • Lists are assigned Priority 1, syncing first to allow UI rendering.
  • Todos are assigned Priority 2, loading in the background.
Now, if another user adds new todos, it’s possible for the list count (synced at Priority 1) to temporarily not match the actual todos (synced at Priority 2). If real-time accuracy is required, both lists and todos should use the same priority.

​
Client-Side Considerations

The client SDK APIs for tracking sync status per priority are the same for Sync Rules and Sync Streams: waitForFirstSync(priority), SyncStatus.priorityStatusEntries(), and SyncStatus.statusForPriority(priority). See Client-Side Considerations on the Sync Streams page for details and a Flutter example.