From 8691ffecf3d4ca4452ac9b2e5488dedb6f5ccbd7 Mon Sep 17 00:00:00 2001 From: benitav Date: Tue, 5 Nov 2024 12:49:53 +0200 Subject: [PATCH 1/8] Notes on performance --- .../flutter/flutter-web-support.mdx | 33 +++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/client-sdk-references/flutter/flutter-web-support.mdx b/client-sdk-references/flutter/flutter-web-support.mdx index ec0a1f10..8da0ed51 100644 --- a/client-sdk-references/flutter/flutter-web-support.mdx +++ b/client-sdk-references/flutter/flutter-web-support.mdx @@ -2,7 +2,11 @@ title: "Flutter Web Support (Beta)" --- -Web support for Flutter in version `^1.9.0` is currently in its alpha stage. + +Web support for Flutter in version `^1.9.0` is currently in a **beta** release. It is functionally ready for production use, provided that you've tested your use cases. + +Please see the [Limitations](#limitations) detailed below. + ## Demo app @@ -25,7 +29,7 @@ flutter pub add powersync:'^1.9.0' The latest version can be found [here](https://pub.dev/packages/powersync/versions). -## Additional config +### Additional config Web support requires `sqlite3.wasm` and worker (`powersync_db.worker.js` and `powersync_sync.worker.js`) assets to be served from the web application. They can be downloaded to the web directory by running the following command in your application's root folder. @@ -63,3 +67,28 @@ Web database connections do not support concurrency. A single database connectio Direct access to the synchronous `CommonDatabase` (`sqlite.Database` equivalent for web) connection is not available. `computeWithDatabase` is not available on web. +### Performance + +This SDK uses IndexedDB as the filesystem mode by default due to its wide compatibility. However, benchmark testing has indicated that performance can be slow. We are looking into ways to improve this. + +For better performance in the interim, you can configure your app to use the OPFS (Origin-Private File System), which is faster but requires additional setup. Essentially, it requires adding two headers to the HTTP server response when a client requests the Flutter web application: + +- `Cross-Origin-Opener-Policy`: Needs to be set to `same-origin`. +- `Cross-Origin-Embedder-Policy`: Needs to be set to `require-corp`. + +#### Enabling OPFS for development +When running the Flutter web app locally, add the headers by running: + +```bash +flutter run -d chrome --web-header "Cross-Origin-Opener-Policy=same-origin" --web-header "Cross-Origin-Embedder-Policy=require-corp" +``` + +#### Enabling OPFS in production + +When serving a Flutter Web app in production, the [Flutter docs](https://docs.flutter.dev/deployment/web#building-the-app-for-release) recommend building the web app with `flutter build web`, then serving the content with an HTTP server. The server should be configured to use the above headers. + + +**Further reading**: + +[Drift](https://drift.simonbinder.eu/) uses the same packages as our [`sqlite_async`](https://github.com/powersync-ja/sqlite_async.dart) package under the hood, and Drift has the best documentation for how the web filesystem is selected. See [here](https://drift.simonbinder.eu/platforms/web/) for the web compatibility notes and [here](https://drift.simonbinder.eu/platforms/web/#additional-headers) for additional notes on the required web headers. + \ No newline at end of file From aae821031feb29836ef6838493719f81029fb42d Mon Sep 17 00:00:00 2001 From: benitav Date: Tue, 5 Nov 2024 12:52:22 +0200 Subject: [PATCH 2/8] Rename to current limitations --- client-sdk-references/flutter/flutter-web-support.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/client-sdk-references/flutter/flutter-web-support.mdx b/client-sdk-references/flutter/flutter-web-support.mdx index 8da0ed51..d9ddd97a 100644 --- a/client-sdk-references/flutter/flutter-web-support.mdx +++ b/client-sdk-references/flutter/flutter-web-support.mdx @@ -5,7 +5,7 @@ title: "Flutter Web Support (Beta)" Web support for Flutter in version `^1.9.0` is currently in a **beta** release. It is functionally ready for production use, provided that you've tested your use cases. -Please see the [Limitations](#limitations) detailed below. +Please see the [Current Limitations](#current-limitations) detailed below. ## Demo app @@ -39,7 +39,7 @@ dart run powersync:setup_web The same code is used for initializing native and web `PowerSyncDatabase` clients. -## Limitations +## Current Limitations The API for Web is essentially the same as for native platforms, however, some features within `PowerSyncDatabase` clients are not available. From f5f93aa3e8a0ea19130cd0afddc7468c6e18e76e Mon Sep 17 00:00:00 2001 From: benitav Date: Tue, 5 Nov 2024 14:32:12 +0200 Subject: [PATCH 3/8] OPFS as recommended config --- .../flutter/flutter-web-support.mdx | 54 ++++++++++--------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/client-sdk-references/flutter/flutter-web-support.mdx b/client-sdk-references/flutter/flutter-web-support.mdx index d9ddd97a..0ee432ff 100644 --- a/client-sdk-references/flutter/flutter-web-support.mdx +++ b/client-sdk-references/flutter/flutter-web-support.mdx @@ -31,6 +31,7 @@ The latest version can be found [here](https://pub.dev/packages/powersync/versio ### Additional config +#### Assets Web support requires `sqlite3.wasm` and worker (`powersync_db.worker.js` and `powersync_sync.worker.js`) assets to be served from the web application. They can be downloaded to the web directory by running the following command in your application's root folder. ```bash @@ -39,6 +40,34 @@ dart run powersync:setup_web The same code is used for initializing native and web `PowerSyncDatabase` clients. +#### OPFS for improved performance + +This SDK supports different storage modes of the SQLite database with varying levels of performance and compatibility: + +- IndexedDB: Highly compatible with different browsers, but performance is slow. +- OPFS (Origin-Private File System): Significantly faster but requires additional configuration. + +OPFS is the preferred mode when it is available. Otherwise file storage falls back to IndexedDB. + +Enabling OPFS requires adding two headers to the HTTP server response when a client requests the Flutter web application: + +- `Cross-Origin-Opener-Policy`: Needs to be set to `same-origin`. +- `Cross-Origin-Embedder-Policy`: Needs to be set to `require-corp`. + +When running the app locally, you can use the following command to include the required headers: + +```bash +flutter run -d chrome --web-header "Cross-Origin-Opener-Policy=same-origin" --web-header "Cross-Origin-Embedder-Policy=require-corp" +``` + +When serving a Flutter Web app in production, the [Flutter docs](https://docs.flutter.dev/deployment/web#building-the-app-for-release) recommend building the web app with `flutter build web`, then serving the content with an HTTP server. The server should be configured to use the above headers. + + +**Further reading**: + +[Drift](https://drift.simonbinder.eu/) uses the same packages as our [`sqlite_async`](https://github.com/powersync-ja/sqlite_async.dart) package under the hood, and Drift has the best documentation for how the web filesystem is selected. See [here](https://drift.simonbinder.eu/platforms/web/) for the web compatibility notes and [here](https://drift.simonbinder.eu/platforms/web/#additional-headers) for additional notes on the required web headers. + + ## Current Limitations The API for Web is essentially the same as for native platforms, however, some features within `PowerSyncDatabase` clients are not available. @@ -67,28 +96,3 @@ Web database connections do not support concurrency. A single database connectio Direct access to the synchronous `CommonDatabase` (`sqlite.Database` equivalent for web) connection is not available. `computeWithDatabase` is not available on web. -### Performance - -This SDK uses IndexedDB as the filesystem mode by default due to its wide compatibility. However, benchmark testing has indicated that performance can be slow. We are looking into ways to improve this. - -For better performance in the interim, you can configure your app to use the OPFS (Origin-Private File System), which is faster but requires additional setup. Essentially, it requires adding two headers to the HTTP server response when a client requests the Flutter web application: - -- `Cross-Origin-Opener-Policy`: Needs to be set to `same-origin`. -- `Cross-Origin-Embedder-Policy`: Needs to be set to `require-corp`. - -#### Enabling OPFS for development -When running the Flutter web app locally, add the headers by running: - -```bash -flutter run -d chrome --web-header "Cross-Origin-Opener-Policy=same-origin" --web-header "Cross-Origin-Embedder-Policy=require-corp" -``` - -#### Enabling OPFS in production - -When serving a Flutter Web app in production, the [Flutter docs](https://docs.flutter.dev/deployment/web#building-the-app-for-release) recommend building the web app with `flutter build web`, then serving the content with an HTTP server. The server should be configured to use the above headers. - - -**Further reading**: - -[Drift](https://drift.simonbinder.eu/) uses the same packages as our [`sqlite_async`](https://github.com/powersync-ja/sqlite_async.dart) package under the hood, and Drift has the best documentation for how the web filesystem is selected. See [here](https://drift.simonbinder.eu/platforms/web/) for the web compatibility notes and [here](https://drift.simonbinder.eu/platforms/web/#additional-headers) for additional notes on the required web headers. - \ No newline at end of file From af1cc579e8e67b1c802f4e317cacb04e17eaac10 Mon Sep 17 00:00:00 2001 From: benitav Date: Tue, 5 Nov 2024 14:46:23 +0200 Subject: [PATCH 4/8] Polish --- client-sdk-references/flutter/flutter-web-support.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/client-sdk-references/flutter/flutter-web-support.mdx b/client-sdk-references/flutter/flutter-web-support.mdx index 0ee432ff..913cc3de 100644 --- a/client-sdk-references/flutter/flutter-web-support.mdx +++ b/client-sdk-references/flutter/flutter-web-support.mdx @@ -12,7 +12,7 @@ Please see the [Current Limitations](#current-limitations) detailed below. The easiest way to test Flutter Web support is to run the [Supabase Todo-List](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist) demo app: -1. Checkout [the powersync.dart repo's](https://github.com/powersync-ja/powersync.dart/tree/main) `main` branch. +1. Clone [the powersync.dart repo](https://github.com/powersync-ja/powersync.dart/tree/main). 1. **Note**: If you are an existing user updating to the latest code after a git pull, run `melos exec 'flutter pub upgrade'` in the repo's root and make sure it succeeds. 2. Run `melos prepare` in the repo's root 3. cd into the `demos/supabase-todolist` folder @@ -21,14 +21,12 @@ The easiest way to test Flutter Web support is to run the [Supabase Todo-List](h ## Installing PowerSync in your own project -Install the latest alpha version of the package, for example: +Install the [latest version]((https://pub.dev/packages/powersync/versions)) of the package, for example: ```bash flutter pub add powersync:'^1.9.0' ``` -The latest version can be found [here](https://pub.dev/packages/powersync/versions). - ### Additional config #### Assets From 245f5b41926b288f4b38a1dc44a5ed423d25ca44 Mon Sep 17 00:00:00 2001 From: benitav Date: Tue, 5 Nov 2024 14:50:54 +0200 Subject: [PATCH 5/8] Rename current limitations to limitations --- client-sdk-references/flutter/flutter-web-support.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/client-sdk-references/flutter/flutter-web-support.mdx b/client-sdk-references/flutter/flutter-web-support.mdx index 913cc3de..898133c4 100644 --- a/client-sdk-references/flutter/flutter-web-support.mdx +++ b/client-sdk-references/flutter/flutter-web-support.mdx @@ -5,7 +5,7 @@ title: "Flutter Web Support (Beta)" Web support for Flutter in version `^1.9.0` is currently in a **beta** release. It is functionally ready for production use, provided that you've tested your use cases. -Please see the [Current Limitations](#current-limitations) detailed below. +Please see the [Limitations](#limitations) detailed below. ## Demo app @@ -66,7 +66,7 @@ When serving a Flutter Web app in production, the [Flutter docs](https://docs.fl [Drift](https://drift.simonbinder.eu/) uses the same packages as our [`sqlite_async`](https://github.com/powersync-ja/sqlite_async.dart) package under the hood, and Drift has the best documentation for how the web filesystem is selected. See [here](https://drift.simonbinder.eu/platforms/web/) for the web compatibility notes and [here](https://drift.simonbinder.eu/platforms/web/#additional-headers) for additional notes on the required web headers. -## Current Limitations +## Limitations The API for Web is essentially the same as for native platforms, however, some features within `PowerSyncDatabase` clients are not available. From bb247ca6c0ed899c918f94d5bc087e47f96ce30b Mon Sep 17 00:00:00 2001 From: benitav Date: Tue, 5 Nov 2024 14:53:42 +0200 Subject: [PATCH 6/8] Tweaks --- client-sdk-references/flutter/flutter-web-support.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/client-sdk-references/flutter/flutter-web-support.mdx b/client-sdk-references/flutter/flutter-web-support.mdx index 898133c4..6ede0778 100644 --- a/client-sdk-references/flutter/flutter-web-support.mdx +++ b/client-sdk-references/flutter/flutter-web-support.mdx @@ -21,7 +21,7 @@ The easiest way to test Flutter Web support is to run the [Supabase Todo-List](h ## Installing PowerSync in your own project -Install the [latest version]((https://pub.dev/packages/powersync/versions)) of the package, for example: +Install the [latest version](https://pub.dev/packages/powersync/versions) of the package, for example: ```bash flutter pub add powersync:'^1.9.0' @@ -42,10 +42,10 @@ The same code is used for initializing native and web `PowerSyncDatabase` client This SDK supports different storage modes of the SQLite database with varying levels of performance and compatibility: -- IndexedDB: Highly compatible with different browsers, but performance is slow. -- OPFS (Origin-Private File System): Significantly faster but requires additional configuration. +- **IndexedDB**: Highly compatible with different browsers, but performance is slow. +- **OPFS** (Origin-Private File System): Significantly faster but requires additional configuration. -OPFS is the preferred mode when it is available. Otherwise file storage falls back to IndexedDB. +OPFS is the preferred mode when it is available. Otherwise database storage falls back to IndexedDB. Enabling OPFS requires adding two headers to the HTTP server response when a client requests the Flutter web application: From 6e4bb06a0b1521ec8c2ae86e46df3676cc10f24f Mon Sep 17 00:00:00 2001 From: benitav Date: Tue, 5 Nov 2024 14:54:16 +0200 Subject: [PATCH 7/8] Another polish --- client-sdk-references/flutter/flutter-web-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/client-sdk-references/flutter/flutter-web-support.mdx b/client-sdk-references/flutter/flutter-web-support.mdx index 6ede0778..c801ed72 100644 --- a/client-sdk-references/flutter/flutter-web-support.mdx +++ b/client-sdk-references/flutter/flutter-web-support.mdx @@ -12,7 +12,7 @@ Please see the [Limitations](#limitations) detailed below. The easiest way to test Flutter Web support is to run the [Supabase Todo-List](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist) demo app: -1. Clone [the powersync.dart repo](https://github.com/powersync-ja/powersync.dart/tree/main). +1. Clone the [powersync.dart](https://github.com/powersync-ja/powersync.dart/tree/main) repo. 1. **Note**: If you are an existing user updating to the latest code after a git pull, run `melos exec 'flutter pub upgrade'` in the repo's root and make sure it succeeds. 2. Run `melos prepare` in the repo's root 3. cd into the `demos/supabase-todolist` folder From 631d562b6d9f891b68e7632fd2eb9c60c352a77e Mon Sep 17 00:00:00 2001 From: benitav Date: Tue, 5 Nov 2024 15:53:22 +0200 Subject: [PATCH 8/8] Minor reword --- client-sdk-references/flutter/flutter-web-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/client-sdk-references/flutter/flutter-web-support.mdx b/client-sdk-references/flutter/flutter-web-support.mdx index c801ed72..97f76f0f 100644 --- a/client-sdk-references/flutter/flutter-web-support.mdx +++ b/client-sdk-references/flutter/flutter-web-support.mdx @@ -63,7 +63,7 @@ When serving a Flutter Web app in production, the [Flutter docs](https://docs.fl **Further reading**: -[Drift](https://drift.simonbinder.eu/) uses the same packages as our [`sqlite_async`](https://github.com/powersync-ja/sqlite_async.dart) package under the hood, and Drift has the best documentation for how the web filesystem is selected. See [here](https://drift.simonbinder.eu/platforms/web/) for the web compatibility notes and [here](https://drift.simonbinder.eu/platforms/web/#additional-headers) for additional notes on the required web headers. +[Drift](https://drift.simonbinder.eu/) uses the same packages as our [`sqlite_async`](https://github.com/powersync-ja/sqlite_async.dart) package under the hood, and has excellent documentation for how the web filesystem is selected. See [here](https://drift.simonbinder.eu/platforms/web/) for web compatibility notes and [here](https://drift.simonbinder.eu/platforms/web/#additional-headers) for additional notes on the required web headers. ## Limitations