Your backend application receives the write operations based on how you defined your uploadData() function in the PowerSyncBackendConnector in your client-side app. See Integrate with your Backend in the Client-Side Setup section for details.

Since you get to define the client-side uploadData() function as you wish, you have full control over how to structure your backend application API to accept write operations from the client. For example, you can have:

  1. A single API endpoint that accepts a batch of write operations from the client, with minimal client-side processing.
  2. Separate API endpoints based on the types of write operations. In your uploadData(), you can call the respective endpoints as needed.
  3. A combination of the above.

You can also use any API style you want — e.g. REST, GraphQL, gRPC, etc.

It’s important that your API endpoint be blocking/synchronous with underlying writes to the backend database (Postgres, MongoDB or MySQL).

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.

​
Write operations recorded on the client

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

OperationPurposeContentsSQLite Statement
PUTCreate new rowContains the value for each non-null columnGenerated by INSERT statements.
PATCHUpdate existing rowContains the row id, and value of each changed column.Generated by UPDATE statements.
DELETEDelete existing rowContains the row idGenerated by DELETE statements.

​
Recommendations

The PowerSync Client SDK does not prescribe any specific request/response format for your backend application API that accepts the write operations. You can implement it as you wish.

We do however recommend the following:

  1. Use a batch endpoint to handle high volumes of write operations.
  2. Use an error response (5xx) only when the write operations cannot be applied due to a temporary error (e.g. backend database not available). In this scenario, the PowerSync Client SDK can retry uploading the write operation and it should succeed at a later time.
  3. For validation errors or write conflicts, you should avoid returning an error response (4xx), since it will block the PowerSync client’s upload queue. Instead, it is best to return a 2xx response, and if needed, propagate the validation or other error message(s) back to the client, for example by:
    1. Including the error details in the 2xx response.
    2. Writing the error(s) into a separate table/collection that is synced to the client, so that the client/user can handle the error(s).

For details on approaches, see:

Handling Write / Validation Errors

For details on handling write conflicts, see:

Handling Update Conflicts

​
Example backend implementations

See our Example Projects page for examples of custom backend implementations (e.g. Django, Node.js, Rails, etc.) that you can use as a guide for your implementation.

For Postgres developers, using Supabase is an easy alternative to a custom backend. Several of our example/demo apps demonstrate how to use Supabase as the backend. These examples use the PostgREST API exposed by Supabase to upload write operations. Alternatively, Supabase’s Edge Functions can also be used.