uploadData() function to send them to your write endpoint. Your write endpoint applies them to your source database, and the PowerSync Service syncs the result back to the client. Write Path Overview walks through these steps.
Write Operations
The client SDK records each change to a synced table in the upload queue as one of three operations:
The SDK groups the operations from one local database transaction into a transaction in the upload queue.
Authenticating Writes
If your auth provider issues JWTs, we recommend that your write endpoint verify the same JWT that your app sends to PowerSync. Your backend connector’sfetchCredentials() already returns this token, so uploadData() can send it in the request’s Authorization header. To verify the token:
- Check the signature with your auth provider’s keys, usually from its JWKS URL.
- Check the issuer and expiry.
- Accept the audience that your PowerSync instance is configured for. If your write endpoint already verifies tokens for a different audience, add this one to the accepted list.
sub claim holds the user ID. Use it to decide which writes that user is allowed to make. See Authentication for the audience and keys each provider uses.
Applying Writes Before Responding
Your write endpoint must store each write in the source database before it responds. Don’t put writes in a queue to process later. If your backend has to apply writes asynchronously, use Custom Write Checkpoints. After an upload, the client requests a write checkpoint. This checkpoint marks the source database position at that moment. The client then waits until it has synced data up to that checkpoint before it updates the local database with the synced data. If a write is not in the source database yet, the synced data does not include it, and the change disappears from the device. It appears again after the write reaches the source database and syncs. See Consistency.What Happens When a Write Fails
The SDK removes changes from the upload queue only whenuploadData() calls complete() on them. If uploadData() throws an error or returns without calling complete(), the changes stay in the queue. The SDK calls uploadData() again after a delay. It keeps doing this while the sync stream is connected. For the retry delay and how the sync status reports upload errors, see Error Handling.
When a write fails, your write endpoint and uploadData() decide between the following outcomes.
Retryable Errors
A retryable error is a failure that is likely to succeed later without any change to the write, such as a network error, a timeout, or a database that is temporarily unavailable.uploadData() throws, and the SDK retries.
A retry sends the whole transaction or batch again, including changes that your write endpoint may already have applied. Make each write safe to repeat. For example, don’t reject a create or delete only because an earlier attempt already applied it.
Rejected Writes
A rejected write is a write that your write endpoint will never apply, for example because it fails validation. Your write endpoint tellsuploadData() that it rejected the write, preferably with a 2xx response that includes the reason. uploadData() then marks the write complete, and the queue keeps moving.
The rejected change stays in the local database until the upload queue is empty and the client has synced. Then the local data is replaced with the state from your source database. See How Changes Are Rolled Back.
To keep a record of rejected writes, your write endpoint can store each one in a dead-letter queue: a table or queue on your backend that you inspect later. If you apply a dead-lettered write later, newer writes from the same client may already be in your source database, so the writes are applied out of order.
To show the user why a write was rejected, return the reason in the 2xx response, or write it to a table that syncs back to the client. See Custom Conflict Resolution for examples.
To reject fewer writes, consider relaxing backend constraints that aren’t strictly required. Accepting slightly inconsistent data can be better than discarding the user’s change.
Blocked Transactions
A blocked transaction is a failed transaction that stays in the upload queue and prevents later writes from uploading. A transaction becomes blocked whenuploadData() throws, or returns without calling complete(), for a write that a retry can’t fix, such as one that violates a constraint. Your uploadData() code decides how to handle each response, so this can happen with any status, 4xx or 5xx. If uploadData() throws, the sync status shows an uploadError on every attempt.
Your app may also keep a transaction blocked on purpose, for example when your write endpoint refuses a write because the user lacks a permission that an administrator can grant.
Your app needs a way to resolve a blocked transaction, such as showing the problem to the user. When the cause is fixed, the next retry succeeds. If the write should be dropped instead, uploadData() calls complete() on the transaction. The change is rolled back like a rejected write, so the user loses the changes they made in that transaction.
How Changes Are Rolled Back
The client has no explicit rollback operation. Instead, the client SDK keeps a copy of the data as last synced from the source database, separate from local changes. When the upload queue is empty and the client has synced up to its latest write checkpoint, the SDK replaces the local data with that synced copy. As a result:- A change that your write endpoint applied appears in the synced copy, so the local data stays the same.
- A change that your write endpoint applied in a modified form is replaced with the version from your source database.
- A change that your write endpoint rejected is not in the synced copy, so the local data returns to its last synced state.
- A change that a later write from another client overwrote is replaced with that other write.
Related Pages
- Handling Update Conflicts: what happens when two clients change the same row.
- Custom Conflict Resolution: strategies for resolving conflicts in your write endpoint.