uploadData() what to do with each change.
What uploadData() Must Do
Your uploadData() function reads queued transactions from the database. Each change is a PUT, PATCH, or DELETE on one row of a table in your client-side schema. See Write Operations.
For each transaction, uploadData() must:
- Send each change to the matching endpoint of your API, authenticated the way your API expects. If your auth provider issues JWTs, this can be the token your app sends to PowerSync. See Authenticating Writes.
- Classify the result of each call as success, a retryable error, or a rejected write.
- Throw on a retryable error, such as a network error or a 5xx response. The SDK keeps the transaction and retries it later.
- Log a rejected write and continue. If your API returns 4xx for validation errors or conflicts, treat those responses as rejected writes. Throwing on them instead turns them into a blocked transaction. A 401 from an expired token is different: refresh the token and retry.
- Mark the transaction complete once every change in it was applied or rejected.
What Your API Must Do
- Apply changes before responding. Write to the source database while the request is open, instead of queueing the work for later. Otherwise, the change can disappear from the device until it syncs back. See Applying Writes Before Responding.
- Return 5xx only for temporary errors. Use 5xx for problems that clear up, such as a database that is briefly unavailable. A 5xx for a write that can never succeed makes
uploadData()retry it until someone fixes the cause. - Report why a write was rejected. Include the reason in the response, or write it to a table that syncs back to the client, so that your app can show the error to the user. See Rejected Writes.
Convex
If your source database is Convex, call your Convex mutations fromuploadData(). Most Convex apps already have a mutation for each table they write to, so you don’t need a separate write endpoint.
If your app authenticates to PowerSync with Convex Auth tokens, configure PowerSync to accept the convex JWT audience. When you self-host, set it in client_auth.audience. On PowerSync Cloud, add a custom audience in the instance settings. See Custom Authentication.
For a working example, see the PowerSync Convex To-Do List Demo.
Prompt for Your Coding Agent
To have a coding agent writeuploadData(), copy this prompt into it. The agent installs the PowerSync agent skills, finds your connector, client-side schema, and API, and asks you about anything it can’t find before it writes code. It then adapts the uploadData() in the prompt to your SDK and your API.
The prompt’s default is to log and discard rejected writes so they can’t block the queue. It asks whether you also want a retry cap or a dead-letter queue.
Build with AI
Related Pages
- Write Path Concepts: write operations, authentication, and what happens when a write fails.
- Client-Side Integration: the backend connector, and when the SDK calls
uploadData(). - Custom Conflict Resolution: strategies for handling conflicts in your write endpoint.