From f6bafbd8860f20d19de948c269b1d4ab6e6170b0 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Mon, 20 Jul 2026 15:27:49 +0200 Subject: [PATCH 1/3] 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 190b33471b7c2e54076c3715a262e4a01ae67620 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Mon, 20 Jul 2026 15:36:42 +0200 Subject: [PATCH 2/3] 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 64216339..df6cef68 100644 --- a/client-sdks/reference/swift.mdx +++ b/client-sdks/reference/swift.mdx @@ -277,6 +277,30 @@ let db = PowerSyncDatabase( The `DefaultLogger` supports the following severity levels: `.debug`, `.info`, `.warn`, `.error`. +## 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 67e92158099bc2966e67dd2730be409ae7314d71 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Mon, 20 Jul 2026 16:05:23 +0200 Subject: [PATCH 3/3] 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 df6cef68..a202f3fd 100644 --- a/client-sdks/reference/swift.mdx +++ b/client-sdks/reference/swift.mdx @@ -277,12 +277,12 @@ let db = PowerSyncDatabase( The `DefaultLogger` supports the following severity levels: `.debug`, `.info`, `.warn`, `.error`. -## 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