Writing Client Changes

Your app backend needs to expose an API endpoint to write changes from the PowerSync client.

This could be:

1. A single endpoint accepting a batch of changes from the client, with minimal client-side processing.

2. Separate endpoints based on the types of changes.

3. A combination of the above.

For details of the client-side interface to your backend, see Integrating With Your Backend.

It's important that your endpoint be blocking/synchronous with underlying Postgres writes. In other words, don't place writes into something like a queue for processing later, process them immediately. For more details, see the explainer below.

Why must my write endpoint be synchronous?

Client applications advance to a write checkpoint after uploads have been processed, so if the client believes that the server has written changes into Postgres, but the next checkpoint does not contain your uploaded changes, those changes will be removed from the client. This could manifest as UI glitches for your end-users, where the changes dissappear from the device for a few seconds and then re-appear.

Changes recorded on the client

The change queue on the client stores three types of operations:

1. PUT / Create new row - contains the value for each non-null column. Generated by INSERT statements.

2. PATCH / Update existing row - contains the id, and value of each changed column. Generated by UPDATE statements.

3. DELETE / Delete existing row - contains the id. Generated by DELETE statements.

Recommendations

The PowerSync client SDKs do not prescribe any specific request / response format ‚ custom client-side code is used to communicate with your app backend, and can use any format.

We do recommend:

1. Use a batch endpoint to handle high volumes of changes.

2. Use an error response (5xx) only when the changes cannot be applied due to a temporary error (e.g. database not available).

3. For validation errors or write conflicts, acknowledge and discard the change. If an error is returned for this, it will block the PowerSync client's upload queue.

To propagate validation or write error messages back to the client, use:

1. A 2xx response, with details in the response.

2. Write the errors back in a separate table that is synced back to the client.

For details on approaches, see:

pageHandling Write / Validation Errors

For details on handling write conflicts, see:

pageHandling Update Conflicts