Skip to main content
Designing your Sync Rules is about organizing data into buckets, and creating the bucket definitions accordingly. Each bucket definition defines a set of tables/collections and rows/documents to sync.
  • If there’s some data you want to sync to all your users/clients, you can add bucket definitions for one or more Global Buckets. This is the simplest way to get started with PowerSync.
  • If there’s data that that you want to filter by user, so that different users/clients get different subsets of data, you can can add bucket definitions to your Sync Rules specifically for that purpose, using the user_id Authentication Parameter that comes from the JWT.
  • You can also filter data based on other parameters, such as project, organization, etc. — using additional bucket definitions with those parameters.
When designing your buckets, it is recommended, but not required, to group all data in a bucket where the same parameters apply.

​
Defining Buckets

Sync Rules take the form of a containing all your bucket definitions. A bucket definition contains two sets of queries:
  1. Parameter Queries: Select bucket parameters
  2. Data Queries: Select data in the bucket using the bucket parameters
Here is an example of Sync Rules containing a single bucket definition, which will sync only the lists that belong to the user: 
bucket_definitions:
  user_lists:
    # select parameters for the bucket - in this case we are just selecting the user_id
    parameters: SELECT request.user_id() as user_id # (request.user_id() comes from the JWT token)  
    data:
      # select data rows/documents using the parameters above
      - SELECT * FROM lists WHERE owner_id = bucket.user_id
You can choose any name for a bucket. The above Sync Rules contains only one bucket definition, with a bucket name of user_lists.
Note: The table/collection names that your Data Queries select from in your Sync Rules must match the table names defined in your client-side schema.
The supported SQL in Parameter Queries and Data Queries is based on a small subset of the SQL standard syntax. Not all SQL constructs are supported. See Supported SQL.

​
Limit on Number of Buckets Per Client

There is a maximum cap on the number of buckets that each user/client can sync — the default limit is 1,000. What this practically means is that the total number of across all your bucket definitions for each specific user/client cannot exceed that limit. If the Parameter Queries for a specific user/client exceed that limit, you will get a PSYNC_S2305 error from the PowerSync Service. Note that this limit only applies to each individual user/client. You can have many more buckets in total in your project, as long as each user syncs no more total buckets than the limit. For example, your PowerSync Service instance could track let’s say 1,000,000 buckets in total, but each user syncs a small fraction of those buckets.
This limit can be increased upon request for Team and Enterprise customers, however: as the number of buckets exceeds 1,000, performance degrades. See Performance and Limits