Skip to main content
PowerSync Sync Rules is the current generally-available/stable/production-ready mechanism to control which data gets synchronized to which clients/devices (i.e. they enable dynamic partial replication).
Sync Streams Available in Early AlphaSync Streams are now available in early alpha! Sync Streams will eventually replace Sync Rules and are designed to allow for more dynamic syncing, while not compromising on existing offline-first capabilities. See the Overview page for more details.
Sync Rules are defined in a YAML file. For PowerSync Cloud, they are edited and deployed to a specific PowerSync instance in the PowerSync Dashboard. For self-hosting setups, they are defined as part of your instance configuration.

​
Key Concepts

​
Bucket Definition

Sync Rules are a set of bucket definitions. A bucket definition defines the actual individual buckets that will be created by the PowerSync Service when it replicates data from your source database. Clients then sync the individual buckets that are relevant to them based on their parameters (see below). Each bucket definition consists of:
  • A custom name for the bucket, e.g user_lists
  • Zero or more Parameter Queries which are used to explicitly select the parameters for the bucket. If no Parameter Query is specified in the bucket definition, it’s automatically a global bucket.
  • One or more Data Queries which selects the data for the bucket. Data Queries can make use of the parameters that are selected in the Parameter Query.
Sync Rules with a single bucket definition
bucket_definitions:
  user_lists: # name for the bucket
    # Parameter Query, selecting a user_id parameter:
    parameters: SELECT request.user_id() as user_id 
    data: # Data Query, selecting data, filtering using the user_id parameter:
      - SELECT * FROM lists WHERE owner_id = bucket.user_id

​
Parameters

A Parameter is a value that can be used in the Sync Rules to create dynamic sync behavior for each user/client. Each client syncs only the relevant buckets based on the parameters for that client (i.e. the results that would be returned from the Parameter Query for that client).

​
Parameter Queries

Parameter Queries are SQL-like queries that explicitly define the parameters for a bucket. The following values can be selected in Parameter Queries:
  • Authentication Parameters (see below)
  • Client Parameters (see below)
  • Values From a Table/Collection (see below)
See Parameter Queries for more details and examples. Also see Supported SQL for limitations.

​
Authentication Parameters

This is a set of parameters specified in the user’s JWT authentication token, and they are signed as part of the JWT (see Authentication). This always includes the JWT subject (sub) which is the user ID, but may include additional and custom parameters (other claims in the JWT). Authentication Parameters are used to identify the user, and specify permissions for the user. They need to be explicitly selected in the Parameter Query to be used in Sync Rules:
Example of selecting Authentication Parameter in a Parameter Query
parameters: SELECT request.user_id() as user_id
See Parameter Queries for more details and examples.

​
Client Parameters

Clients can specify Client Parameters when connecting to PowerSync (i.e. when connect() is called). Client Parameters need to be explicitly selected in the Parameter Query to be used in Sync Rules:
Example of selecting a Client Parameter in a Parameter Query
parameters: SELECT (request.parameters() ->> 'current_project') as current_project
The ->> operator in the above example extracts a value from a string containing JSON (which is the format provided by request.parameters()). See Operators and Functions
A client can pass any value for a Client Parameter. Hence, Client Parameters should always be treated with care, and should not be used for access control purposes. That being said, Client Parameters can be useful for use cases such as syncing different buckets based on state in the client app, for example only syncing data for the project currently selected, or syncing different buckets based on the client version (see here).
See Client Parameters and Parameter Queries for more details and examples.

​
Values From a Table/Collection

A Parameter Query can select a parameter from a table/collection in your source database, e.g.:
Selecting a parameter from a table in the source database
SELECT primary_list_id FROM users WHERE users.id = request.user_id()
See Parameter Queries for more details and examples.

​
Data Queries

Data Queries select the data for the bucket, and can make use of any of the bucket parameters (i.e. values returned by the Parameter Queries). When referencing a parameter, the syntax bucket.<parameter-name> should be used in the Data Query: 
data:
  - SELECT * FROM lists WHERE owner_id = bucket.user_id
See Data Queries for more details and examples. Also see Supported SQL for limitations.

​
Global Buckets

If no Parameter Query is specified in the bucket definition, the bucket is automatically a global bucket. These buckets will be synced to all clients/users.
See Global Buckets for more details and examples.

​
Potential Parameter Values Determine Created Buckets

When your PowerSync Service instance replicates data from your source database based on your Sync Rules configuration (i.e. your bucket definitions), it finds all possible values for your defined parameters in the relevant tables/collections in your source database, and creates individual buckets based on those values. For example, let’s say you have a bucket named user_todo_lists that contains the to-do lists for a user, and that bucket utilizes a user_id parameter (which will be obtained from the JWT) to scope those to-do lists. Now let’s say users with IDs 1, 2 and 3 exist in the source database. PowerSync will then replicate data from the source database and preemptively create individual buckets with bucket IDs of user_todo_lists["1"], user_todo_lists["2"] and user_todo_lists["3"]. This architecture is key to the scalability and performance of PowerSync. See the PowerSync Service architecture overview for more background.

​
Designing Sync Rules

Designing your Sync Rules is basically about organizing data into buckets, and creating the bucket definitions accordingly.
See Organize Data Into Buckets.