Multiple Client Versions

Handle multiple client app versions that require different output schemas from Sync Streams.

When schema changes are additive, old clients ignore the new tables and columns, and no special handling is required. More drastic changes, such as renaming tables or changing a table’s structure, can break older app versions that are still in use. In these cases, define separate versions of the affected Sync Streams so that each client version receives the tables and columns it expects.

Versioning by Stream Name

With Sync Streams, the most convenient approach is usually to define a new stream alongside the old one. New app versions subscribe to the new stream, while older app versions continue subscribing to the old one.

For example, suppose a new app version changes the structure of the assets table in its client-side schema, defining it as assets_v2, while older app versions still define assets. Define a new stream alongside the existing one, using an alias to map the source assets table to the new client-side name:

streams:
  # Old stream, kept for backward compatibility with older app versions.
  # Remove it once those versions are no longer in use.
  user_assets:
    query: SELECT * FROM assets WHERE user_id = auth.user_id()

  # New app versions subscribe to this stream.
  # The alias maps the table to the new client-side name.
  user_assets_v2:
    query: SELECT * FROM assets AS assets_v2 WHERE user_id = auth.user_id()

// New app versions subscribe to the new stream
const subscription = await db.syncStream('user_assets_v2').subscribe();

Once the older app versions are no longer in use, remove the old stream from your configuration and deploy the change.

Versioning with Connection Parameters

Alternatively, clients can pass their version to the PowerSync Service as a connection parameter, and stream queries filter on it so each client only receives data for its version. This approach is useful when your streams are auto-subscribed: auto-subscribed streams sync to every client on connect, so clients cannot select a stream version by name. In legacy Sync Rules, connection parameters are called client parameters.

The example below implements the same assets use case, with both stream versions auto-subscribed and filtered by a schema_version connection parameter:

Sync Streams

# Client passes connection params: {"schema_version": <version>}
streams:
  user_assets:
    auto_subscribe: true
    query: SELECT * FROM assets
           WHERE user_id = auth.user_id()
           AND connection.parameter('schema_version') = '1'

  user_assets_v2:
    auto_subscribe: true
    query: SELECT * FROM assets AS assets_v2
           WHERE user_id = auth.user_id()
           AND connection.parameter('schema_version') = '2'

Sync Rules (Legacy)

# Client passes in: "params": {"schema_version": <version>}
  user_assets:
    parameters: SELECT request.user_id() AS user_id
      WHERE request.parameters() ->> 'schema_version' = '1'
    data:
      - SELECT * FROM assets WHERE user_id = bucket.user_id

  user_assets_v2:
    parameters: SELECT request.user_id() AS user_id
      WHERE request.parameters() ->> 'schema_version' = '2'
    data:
      - SELECT * FROM assets AS assets_v2 WHERE user_id = bucket.user_id

Handle queries based on parameters set by the client with care. The client can send any value for these parameters, so it’s not a good place to do authorization. If the parameter must be authenticated, use parameters from the JWT instead.