Skip to main content
If you don’t have a write endpoint and your backend doesn’t run on Node.js, you can build one in your own stack. Follow the API contract of the reference write implementation, so that you can use its reference connector as your app’s 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:
  1. Implement POST /api/data as defined in the OpenAPI spec.
  2. Apply each transaction in its own database transaction, and return one result per transaction, in order.
  3. 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.
The error mappings in the reference repository’s 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 implements POST /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 own uploadData(), 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 sub claim, 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, a DELETE, or a PUT that replaces a row, check that the user may change the existing row, not only the new values.
  • 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_attempted for the remaining transactions, so that later writes don’t overtake the failed one.
  • Classify each failure. The connector acts on the status of each result. These status and field names come from the OpenAPI spec:
    • Return retryable_error for failures that are likely to succeed later, such as a lost database connection or a deadlock. If you know how long to wait, add retry_after_ms.
    • Return fatal_error for 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_handling to true when 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.
  • 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 PUT as an upsert, and treat a PATCH or DELETE of 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’s opData, and return fatal_error for 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.