Client SDKs: Split connector interface

[simolus3]

TL;DR: This proposes to split the PowerSyncBackendConnector interface into two superinterfaces: One providing credentials (for streaming downloads) and one responsible for uploading changes. We then allow connecting in upload or download-only mode.

Current status:

• 2026-09-07: Proposal published, Kotlin PR in Backend connector split powersync-kotlin#380.

Current ‘backend connector’ architecture

The specifics vary slightly based on the specific SDK, but generally when wiring up the PowerSync Client SDK, you have to define a “backend connector” class with 2 methods:

• fetchCredentials() which needs to return an object containing:
  • token: JWT for authentication with PowerSync Service. Developers can either reuse the existing JWT from their authentication provider, or mint a new JWT specific for PowerSync, by calling their own backend API
  • endpoint: PowerSync Service instance URL
• uploadData() which gets entries from the upload queue, uploads them to the developer/customer’s backend, and marks those transactions as complete so that they are removed from the upload queue

Problem statements

There are several paper cuts involved with the tight coupling of everything in the ‘backend connector’.

1. If you are not fetching a JWT from your backend, but rather reusing an existing JWT from your authentication provider which you are getting from local state, then having fetchCredentials() as part of the “backend connector” does not make sense semantically.
2. The fact that fetchCredentials() and uploadData() are both part of a “backend connector” makes the concepts more complicated to explain in our documentation (and makes structuring the documentation more complicated)
   1. Setup Guide → Connect to PowerSync Service Instance
   2. Client-Side Integration With Your Backend
3. We've been asked about an upload-only mode of the client SDK that can be used without connecting to a PowerSync Service instance. However, you are forced to call connect() on the PowerSyncDatabase in order to pass a “backend connector” with an uploadData() implementation. You cannot upload client-side mutations to your backend without connecting to a PowerSync Service instance.
4. The different URLs involved in fetchCredentials() (PowerSync Service instance endpoint URL and custom backend URL) can cause confusion.
5. When it comes to uploadData(), it would be better to standardize terminology to refer to the entries in the upload queue as “mutations” everywhere in our code/APIs and documentation. “Mutations” is the most clear description we can use.
   1. At the moment we use a mix of “CRUD”, “CRUD operations”, “CRUD items” (which doesn’t make sense because that includes reads), “writes”, “write operations”, “mutations” and “changes” in different places, and the naming of uploadData() doesn’t align with any of those.

Goals

1. See whether concepts can be simplified: can we eliminate the concept of a ‘backend connector’?
2. Reduce the tight coupling between the different parts of the current ‘backend connector’
   1. Allow mutations on the client-side SQLite database to be uploaded without connecting to a PowerSync Service instance
   2. Consider separating configuring the JWT and PowerSync Service instance URL
3. Improving naming
   1. Of uploadData() — standardize on “mutations”
   2. And of fetchCredentials() — in many/most cases it won’t require fetching from your backend, if you reuse an existing JWT
4. Preserve convenience and type-safety, and avoid introducing new footguns or new sources of confusion

Proposal

Note: The internal document lists additional proposals, this is a summary based on discussions in comments.

While preserving backwards compatibility, eliminate the concept of a 'backend connector' in favor of these interfaces (or, where appropriate for an SDK, callback functions):

public interface Authenticator {
    // Fetch or use cached credentials
    public suspend fun resolveCredentials(): String
    // Hint that the credentials were rejected by the PowerSync service
    public fun invalidateCredentials()
}

public fun interface MutationUploader {
    public suspend fun uploadMutations(onDatabase: PowerSyncDatabase)
}

// existing class now implements these interfaces
public abstract class PowerSyncBackendConnector: Authenticator, MutationUploader { /* ... */ }

public interface CustomCheckpointRequestAuthenticator: Authenticator {}

Depending on the SDK, we then add overloads or optional parameters for connect():

suspend fun connect(
    powerSyncEndpoint: String,
    authenticator: Authenticator? = null,
    uploads: MutationUploader? = null,
    options: SyncOptions = SyncOptions(),
)

Calling connect(backendConnector) continues to work.

Additional considerations

Local mutations that are never uploaded

What do we do with a database that has pending ps_crud items and is then connected in download-only mode? It wouldn't be able to apply checkpoints, and we only surface that as log items which are easy to overlook.

To make this error state easier to observe, maybe we should also add these errors to the sync status.

Upgrading a partial connection to a full connection

Consider a connect call only providing credentials for downloads (no mutation upload callback) followed by another call only providing a mutation uploader (and no separate credentials).

In this state, should the database be fully connected (using the initial set of credentials for downloads and the second call for uploads), or should only the last connect call have any effect (meaning that the database is upload-only?).

Making connect() calls "add up" feels nicer, but is not consistently possible when e.g. different options like retry delays are passed to the calls. So only letting the last call have an effect is more consistent.

Requesting checkpoints in download-only mode

In upload-only mode, the database has no credentials to connect to the PowerSync service and thus can't request write checkpoints / checkpoint requests. We'd upload everything from ps_crud and then keep the checkpoint gate at i64::max.

In this state, if the database is then connected in download-only mode, should it request a checkpoint? Conceptually, requesting checkpoints is part of the upload process but it probably makes sense to run that once in a download-only connection to make sure we can apply checkpoints.