uploadData().
Implement the Reference API Contract
An OpenAPI spec defines the API between the reference connector and the reference write endpoint. To build the same write endpoint in your stack:- Implement
POST /api/dataas defined in the OpenAPI spec. - Apply each transaction in its own database transaction, and return one result per transaction, in order.
- In your app, use the reference connector for your SDK: the Custom Backend example in Backend Connector Examples. Set its write endpoint URL to your endpoint, and fill in the other placeholders as described in the reference write implementation’s Connect Your App step.
backend/shared/src/persistence folder show which database errors are retryable and which cause rejected writes.
Prompt for Your Coding Agent
To have a coding agent build your write endpoint, copy this prompt into it. The agent installs the PowerSync agent skills, reads the reference write implementation, explores your backend, and asks you about anything it can’t find before it writes code. It then implementsPOST /api/data in your stack with the same behavior as the reference, so that the reference connector works against it unchanged.
The prompt covers your backend only. It always asks you to confirm which writes each user may make before it writes code.
Build with AI
Designing a Different API
You don’t have to follow the reference contract. If you write your ownuploadData(), your write endpoint can use any style, such as REST, GraphQL, or gRPC. It can be a single endpoint for all changes, or one endpoint per table or operation. An endpoint that accepts a batch of changes needs fewer requests when your app makes many writes at once, such as during bulk imports.
Your write endpoint still has to meet the requirements in Write Path Concepts. Use Your Existing API describes what uploadData() must do for an API that you design.
For example backends in Django, Node.js, and other stacks, see Example Projects.
Best Practices
Check your write endpoint against this list before you deploy it. Except for the first item, these apply to any write endpoint.- Follow the reference API contract. If your write endpoint implements the reference OpenAPI spec, the reference connector for your SDK, the Custom Backend example, works without changes to its upload code. If your API contract differs from the reference, you write
uploadData()yourself. - Accept the JWT that your app sends to PowerSync. Your backend connector uses one token for sync and for uploads. Accept the audience that your PowerSync instance is configured for. See Authenticating Writes.
- Authorize every write. PowerSync does not check writes, so a client can send any change to your write endpoint. For each operation:
- Take the user ID from the token’s
subclaim, NOT from a column that the client sends. - Accept only the tables and columns that clients may write. The client sends the table name, so never put an unchecked table name in SQL. Apply strict validation rules to table and column names to prevent injection attacks.
- For a
PATCH, aDELETE, or aPUTthat replaces a row, check that the user may change the existing row, not only the new values.
- Take the user ID from the token’s
- Expect authorization to change while a device is offline. Your write endpoint checks a write when it arrives, which can be days after the user made it. If the user lost access, distinguish between a rejected write or a blocked transaction.
- Store writes before you respond. Process writes synchronously. Don’t put writes in a queue to process later. Otherwise, the change disappears from the device until it reaches the source database and syncs back to the device. See Applying Writes Before Responding.
- Apply each client database transaction in one backend database transaction. Either all of its changes are stored or none are. Process transactions in the order that you receive them, and return one result per transaction in the same order. After a failure that stops the batch, return
not_attemptedfor the remaining transactions, so that later writes don’t overtake the failed one. - Classify each failure. The connector acts on the
statusof each result. These status and field names come from the OpenAPI spec:- Return
retryable_errorfor failures that are likely to succeed later, such as a lost database connection or a deadlock. If you know how long to wait, addretry_after_ms. - Return
fatal_errorfor writes that can never succeed, such as constraint violations or invalid data. Return an HTTP 200 response, since the connector retries every non-2xx response. - Set
requires_client_handlingtotruewhen the user or an administrator can fix the cause, such as a missing permission. The connector then keeps the transaction in the queue. - Return HTTP 401 or 403 only when the token is missing or invalid. On either of these responses, the connector fetches a new token.
- Return
- Store rejected writes in a dead-letter queue. If you only log them, the user’s change is lost. Store the transaction, the user ID, and the error, and alert when new entries arrive. If you apply an entry later, newer writes from the same client may already be applied. See Rejected Writes.
- Make every write safe to repeat. The connector can send a transaction again, for example when the response is lost after your write endpoint committed it. Treat a
PUTas an upsert, and treat aPATCHorDELETEof a missing row as a success. Beware of duplication of side effects such as notifications and webhooks. - Accept writes from older app versions. The upload queue is stored on the device, so writes made offline can arrive after you release a new app version or change your schema. Add tables and columns instead of renaming or removing the ones that older versions write to.
- Choose a conflict policy. If your write endpoint applies writes in the order they arrive, the last write to a column wins. If your app needs different behavior, see Handling Update Conflicts and Custom Conflict Resolution.
- Validate values and size limits. Check the type and range of each value in an operation’s
op_data, the request field that holds the SDK’sopData, and returnfatal_errorfor invalid data. If you set a request body size limit, make it larger than your largest transaction. A transaction that exceeds the limit fails on every retry and blocks the queue. - Log enough to debug a stuck device. For each failed operation, log the user ID, the table, the row ID, and the error code. Track how often your write endpoint returns each error status. A blocked transaction is otherwise visible only on the device.
Related Pages
- Reference Write Implementation: how uploads are applied, batching, and conflict behavior.
- Write Path Concepts: authentication and what happens when a write fails.
- Client-Side Integration: the backend connector, and when the SDK calls
uploadData().