Glossary

Bucket / Bucket instance

A group of rows, from one or more tables.

Each bucket can be synced by any number of users, as a whole. The PowerSync protocol does not support syncing partial buckets (filtering inside buckets).

Each bucket is defined by its bucket definition name and set of parameter values. Together this forms its id, for example by_user["user1","admin"].

Bucket Definition

This is the “sync rule” that describes buckets. Specifies the name, parameter query(ies), and data queries.

Each bucket definition describes a set of buckets using SQL queries.

Bucket Parameters

This is the set of parameters that uniquely identifies an individual bucket within a bucket definition. Together with the bucket name, this forms the bucket id.

The bucket parameters are defined using one or more SQL queries in a bucket definition. These queries can return values directly from the user's authentication token (token parameters), and/or select values from a table.

Token Parameters

This is a set of parameters specified in the user's authentication token. This always includes user_id, but may include additional parameters.

Token parameters are used to identify the user, and specify permissions for the user.

These parameters are signed as part of the JWT generated on your app backend.

Client Parameters

(Future functionality, not available yet)

In addition to token parameters, the client may add parameters to the sync request.

These parameters are not authenticated, and should not be used to implement "permissions".

However, these can be used to filter data based for some other use cases:

1. Sync different buckets based on the client version.

2. Sync different buckets based on state in the client app, for example only synchronizing data for the customer currently selected.

Global Buckets

Global buckets are buckets with no parameters.

If no parameter query is specified, the bucket is automatically a global bucket.

Parameter queries may still be used to filter buckets for an user, as long as it does not contain any output columns.