From 11970d0b88e9e4841d96ddd01996ccbeca171f65 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Mon, 20 Jul 2026 15:27:49 +0200 Subject: [PATCH 1/6] Document custom http clients for Dart and Kotlin --- client-sdks/reference/flutter.mdx | 47 +++++++++++++++++++++++++++++++ client-sdks/reference/kotlin.mdx | 43 ++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+) diff --git a/client-sdks/reference/flutter.mdx b/client-sdks/reference/flutter.mdx index 19f93178..f90d5a5f 100644 --- a/client-sdks/reference/flutter.mdx +++ b/client-sdks/reference/flutter.mdx @@ -348,10 +348,57 @@ class TodosWidget extends StatelessWidget { } } ``` + ## Configure Logging Since version 1.1.2 of the SDK, logging is enabled by default and outputs logs from PowerSync to the console in debug mode. +To disable this, or to configure logging in release-mode configurations, use the `logger` parameter on the `PowerSyncDatabase` constructor. +PowerSync uses [`package:logging`](https://pub.dev/packages/logging) to emit logs, see that package for additional information. + +## Custom HTTP clients and headers + +PowerSync uses a streaming HTTP response to connect to the PowerSync service. The SDK will use the default `Client()` from the +[http package](https://pub.dev/packages/http) for that, which uses the `HttpClient` from `dart:io` on native platforms and `fetch()` +on the web. + +You can also supply a custom HTTP client. This can be used to enable a faster HTTP implementation like [`cronet_http`](https://pub.dev/packages/cronet_http), +or to add custom request headers that may be required if you run the PowerSync service behind a reverse-proxy. + +```dart +import 'package:http/http.dart'; +import 'package:powersync/powersync.dart'; + +final class _AddHeaderClient extends BaseClient { + final Client inner; + + _AddHeaderClient([Client? inner]) : inner = inner ?? Client(); + + @override + Future send(BaseRequest request) { + request.headers['x-my-custom-header'] = 'set for all requests'; + return inner.send(request); + } + + @override + void close() => inner.close(); +} + +Future connect(PowerSyncDatabase db) async { + await db.connect( + connector: MyBackendConnector(db), + options: SyncOptions( + httpClient: _AddHeaderClient.new + ), + ); +} +``` + + + On the web, PowerSync uses a shared worker for the sync process. As Dart objects cannot be shared between tabs and workers, the worker will use a + random tab as a proxy to send requests. This can slow down the sync process slightly. + + ## Additional Usage Examples For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the [Usage Examples](/client-sdks/usage-examples) page. diff --git a/client-sdks/reference/kotlin.mdx b/client-sdks/reference/kotlin.mdx index a532f07f..c4885ba6 100644 --- a/client-sdks/reference/kotlin.mdx +++ b/client-sdks/reference/kotlin.mdx @@ -320,6 +320,49 @@ Logger.e("Some error"); ... ``` +## Custom HTTP clients and headers + +PowerSync uses streaming HTTP responses or WebSockets to connect to the PowerSync service. The SDK uses +[ktor](https://ktor.io/) as a cross-platform HTTP client. `com.powersync:core` depends on an OkHttp on Android and JVM targets +and on the Darwin engine for native Apple targets. + +How the PowerSync SDK configures client engines can be configured by passing an instance of `SyncClientConfiguration.ExtendedConfig` +in `SyncOptions`: + +```kotlin +import com.powersync.sync.SyncClientConfiguration +import com.powersync.sync.SyncOptions +import io.ktor.client.plugins.defaultRequest +import io.ktor.client.request.header + +db.connect( + connector, + options = SyncOptions( + clientConfiguration = SyncClientConfiguration.ExtendedConfig { + // For more options, see https://ktor.io/docs/client-create-and-configure.html#plugins + defaultRequest { + header("X-Custom-Header", "Used by PowerSync") + } + } + ) +) +``` + +If you want to use a custom HTTP client engine instead, use `SyncClientConfiguration.ExistingClient` instead: + +```kotlin +import com.powersync.sync.configureSyncHttpClient + +db.connect( + connector, + options = SyncOptions( + clientConfiguration = SyncClientConfiguration.ExistingClient(HttpClient(YourPreferredClientEngine) { + // Important: This configures a minimal set of plugins required by the PowerSync sync client. + configureSyncHttpClient() + }) + ) +) +``` ## Additional Usage Examples From 279efbd5136dc277334fad20b8b257c82eae9cdf Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Mon, 20 Jul 2026 15:36:42 +0200 Subject: [PATCH 2/6] Document custom http clients for Swift --- client-sdks/reference/swift.mdx | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/client-sdks/reference/swift.mdx b/client-sdks/reference/swift.mdx index 87628703..587598cc 100644 --- a/client-sdks/reference/swift.mdx +++ b/client-sdks/reference/swift.mdx @@ -306,6 +306,30 @@ from a single context: This is not a concern for app extensions released as part of the same bundle, but something to be aware of for app groups. +## Custom HTTP clients and headers + +PowerSync uses a streaming HTTP response to connect to the PowerSync service. By default, the Swift SDK uses `URLSession.shared` +to run HTTP requests. + +A custom `URLSession` can be provided as a sync option. This can be used to add custom HTTP headers, for example: + +```swift +let config = URLSessionConfiguration.ephemeral +config.httpAdditionalHeaders = ["x-my-custom-header": "example"] +let session = URLSession(configuration: config) + +try await db.connect( + connector: connector, + options: ConnectOptions( + clientConfiguration: SyncClientConfiguration( + urlSession: session + ) + ) +) +``` + +For more information, see Apple's documentation on [`URLSessionConfiguration`](https://developer.apple.com/documentation/foundation/urlsessionconfiguration). + ## Additional Usage Examples For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the [Usage Examples](/client-sdks/usage-examples) page. From 7e346ad6894fbeeb57b54c9c796f223d037f8bf3 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Mon, 20 Jul 2026 16:05:23 +0200 Subject: [PATCH 3/6] AI feedback --- client-sdks/reference/flutter.mdx | 12 ++++++------ client-sdks/reference/kotlin.mdx | 10 +++++----- client-sdks/reference/swift.mdx | 4 ++-- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/client-sdks/reference/flutter.mdx b/client-sdks/reference/flutter.mdx index f90d5a5f..df68999f 100644 --- a/client-sdks/reference/flutter.mdx +++ b/client-sdks/reference/flutter.mdx @@ -354,12 +354,12 @@ class TodosWidget extends StatelessWidget { Since version 1.1.2 of the SDK, logging is enabled by default and outputs logs from PowerSync to the console in debug mode. To disable this, or to configure logging in release-mode configurations, use the `logger` parameter on the `PowerSyncDatabase` constructor. -PowerSync uses [`package:logging`](https://pub.dev/packages/logging) to emit logs, see that package for additional information. +PowerSync uses [`package:logging`](https://pub.dev/packages/logging) to emit logs. See that package for additional information. -## Custom HTTP clients and headers +## Custom HTTP Clients and Headers -PowerSync uses a streaming HTTP response to connect to the PowerSync service. The SDK will use the default `Client()` from the -[http package](https://pub.dev/packages/http) for that, which uses the `HttpClient` from `dart:io` on native platforms and `fetch()` +PowerSync uses a streaming HTTP response to connect to the PowerSync service. The SDK uses the default `Client()` from the +[http package](https://pub.dev/packages/http) for that, which relies on `HttpClient` from `dart:io` on native platforms and `fetch()` on the web. You can also supply a custom HTTP client. This can be used to enable a faster HTTP implementation like [`cronet_http`](https://pub.dev/packages/cronet_http), @@ -394,10 +394,10 @@ Future connect(PowerSyncDatabase db) async { } ``` - + On the web, PowerSync uses a shared worker for the sync process. As Dart objects cannot be shared between tabs and workers, the worker will use a random tab as a proxy to send requests. This can slow down the sync process slightly. - + ## Additional Usage Examples diff --git a/client-sdks/reference/kotlin.mdx b/client-sdks/reference/kotlin.mdx index c4885ba6..389c9db3 100644 --- a/client-sdks/reference/kotlin.mdx +++ b/client-sdks/reference/kotlin.mdx @@ -320,13 +320,13 @@ Logger.e("Some error"); ... ``` -## Custom HTTP clients and headers +## Custom HTTP Clients and Headers PowerSync uses streaming HTTP responses or WebSockets to connect to the PowerSync service. The SDK uses -[ktor](https://ktor.io/) as a cross-platform HTTP client. `com.powersync:core` depends on an OkHttp on Android and JVM targets -and on the Darwin engine for native Apple targets. +[ktor](https://ktor.io/) as a cross-platform HTTP client. `com.powersync:core` depends on an OkHttp-based +implementation on Android and JVM targets, and on the Darwin engine for native Apple targets. -How the PowerSync SDK configures client engines can be configured by passing an instance of `SyncClientConfiguration.ExtendedConfig` +Configure how the PowerSync SDK sets up client engines by passing an instance of `SyncClientConfiguration.ExtendedConfig` in `SyncOptions`: ```kotlin @@ -348,7 +348,7 @@ db.connect( ) ``` -If you want to use a custom HTTP client engine instead, use `SyncClientConfiguration.ExistingClient` instead: +If you want to use a custom HTTP client engine instead, use `SyncClientConfiguration.ExistingClient`: ```kotlin import com.powersync.sync.configureSyncHttpClient diff --git a/client-sdks/reference/swift.mdx b/client-sdks/reference/swift.mdx index 587598cc..9e36e2b2 100644 --- a/client-sdks/reference/swift.mdx +++ b/client-sdks/reference/swift.mdx @@ -306,12 +306,12 @@ from a single context: This is not a concern for app extensions released as part of the same bundle, but something to be aware of for app groups. -## Custom HTTP clients and headers +## Custom HTTP Clients and Headers PowerSync uses a streaming HTTP response to connect to the PowerSync service. By default, the Swift SDK uses `URLSession.shared` to run HTTP requests. -A custom `URLSession` can be provided as a sync option. This can be used to add custom HTTP headers, for example: +You can provide a custom `URLSession` as a sync option. This can be used to add custom HTTP headers, for example: ```swift let config = URLSessionConfiguration.ephemeral From f25d5a232893624def62d5e78c6b22dbcd12701e Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Wed, 29 Jul 2026 13:39:16 +0200 Subject: [PATCH 4/6] Update client-sdks/reference/kotlin.mdx Co-authored-by: benitav --- client-sdks/reference/kotlin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/client-sdks/reference/kotlin.mdx b/client-sdks/reference/kotlin.mdx index 389c9db3..c76fbf51 100644 --- a/client-sdks/reference/kotlin.mdx +++ b/client-sdks/reference/kotlin.mdx @@ -322,7 +322,7 @@ Logger.e("Some error"); ## Custom HTTP Clients and Headers -PowerSync uses streaming HTTP responses or WebSockets to connect to the PowerSync service. The SDK uses +PowerSync uses streaming HTTP responses or WebSockets to connect to the PowerSync Service. The SDK uses [ktor](https://ktor.io/) as a cross-platform HTTP client. `com.powersync:core` depends on an OkHttp-based implementation on Android and JVM targets, and on the Darwin engine for native Apple targets. From 2d88949999bc87df0a2e73b7ac0e1103ea80ac5e Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Wed, 29 Jul 2026 13:39:24 +0200 Subject: [PATCH 5/6] Update client-sdks/reference/flutter.mdx Co-authored-by: benitav --- client-sdks/reference/flutter.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/client-sdks/reference/flutter.mdx b/client-sdks/reference/flutter.mdx index df68999f..4b4c76bf 100644 --- a/client-sdks/reference/flutter.mdx +++ b/client-sdks/reference/flutter.mdx @@ -358,7 +358,7 @@ PowerSync uses [`package:logging`](https://pub.dev/packages/logging) to emit log ## Custom HTTP Clients and Headers -PowerSync uses a streaming HTTP response to connect to the PowerSync service. The SDK uses the default `Client()` from the +PowerSync uses a streaming HTTP response to connect to the PowerSync Service. The SDK uses the default `Client()` from the [http package](https://pub.dev/packages/http) for that, which relies on `HttpClient` from `dart:io` on native platforms and `fetch()` on the web. From c3bd90002c3b1b63a81c5d7cda1b2e55797daf43 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Wed, 29 Jul 2026 13:41:48 +0200 Subject: [PATCH 6/6] Fix more Service capitalization issues --- client-sdks/reference/flutter.mdx | 2 +- client-sdks/reference/swift.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/client-sdks/reference/flutter.mdx b/client-sdks/reference/flutter.mdx index 4b4c76bf..a1b49a48 100644 --- a/client-sdks/reference/flutter.mdx +++ b/client-sdks/reference/flutter.mdx @@ -363,7 +363,7 @@ PowerSync uses a streaming HTTP response to connect to the PowerSync Service. Th on the web. You can also supply a custom HTTP client. This can be used to enable a faster HTTP implementation like [`cronet_http`](https://pub.dev/packages/cronet_http), -or to add custom request headers that may be required if you run the PowerSync service behind a reverse-proxy. +or to add custom request headers that may be required if you run the PowerSync Service behind a reverse-proxy. ```dart import 'package:http/http.dart'; diff --git a/client-sdks/reference/swift.mdx b/client-sdks/reference/swift.mdx index 9e36e2b2..6e38bf5f 100644 --- a/client-sdks/reference/swift.mdx +++ b/client-sdks/reference/swift.mdx @@ -296,7 +296,7 @@ from a single context: writes. Outside of SQLite using file locks, there is no additional coordination for multi-process access. - Consider using [`PRAGMA busy_timeout`](https://sqlite.org/pragma.html#pragma_busy_timeout) to make SQLite wait longer. - Be ready to handle `SQLITE_BUSY` errors if multiple processes attempt to write to the database. -2. Do not call `connect()` in more than one process: If two processes attempt to connect to the PowerSync service for +2. Do not call `connect()` in more than one process: If two processes attempt to connect to the PowerSync Service for the same database, this wastes resources and can also lead to concurrency issues. If you share databases with extensions or app groups, ensure there is only one context responsible for connecting. 3. Avoid multiple versions of the Swift SDK: While the SQLite file format is stable and databases can safely be accessed @@ -308,7 +308,7 @@ from a single context: ## Custom HTTP Clients and Headers -PowerSync uses a streaming HTTP response to connect to the PowerSync service. By default, the Swift SDK uses `URLSession.shared` +PowerSync uses a streaming HTTP response to connect to the PowerSync Service. By default, the Swift SDK uses `URLSession.shared` to run HTTP requests. You can provide a custom `URLSession` as a sync option. This can be used to add custom HTTP headers, for example: