Merge branch 'develop' into new-query-builder

Author: simolus3

.github/actions/prepare/action.yml

@@ -2,14 +2,21 @@ name: Prepare
 description: Prepare CI environment to test a component of drift
 
 inputs:
-  dart_version:
-    description: Dart version, to restore the dependency cache
+  flutter_version:
+    description: Flutter version to use.
     required: true
 
 runs:
   using: "composite"
   steps:
-    - uses: dart-lang/setup-dart@v1
+    - name: Set up Flutter
+      uses: subosito/flutter-action@v2
+      with:
+        channel: stable
+        flutter-version: ${{ inputs.flutter_version }}
+        cache: true
+        cache-key: "flutter-:os:-:channel:-:version:-:arch:-:hash:"
+        cache-path: "${{ runner.tool_cache }}/flutter/:channel:-:version:-:arch:"
 
     # Setup sqlite3
     - name: Download sqlite3
@@ -31,9 +38,9 @@ runs:
     - uses: actions/cache@v4
       with:
         path: "${{ env.PUB_CACHE }}"
-        key: dart-dependencies-${{ inputs.dart_version }}-${{ hashFiles('**/pubspec.yaml') }}
+        key: dart-dependencies-${{ inputs.flutter_version }}-${{ hashFiles('**/pubspec.yaml') }}
         restore-keys: |
-          dart-dependencies-${{ inputs.dart_version }}-
+          dart-dependencies-${{ inputs.flutter_version }}-
           dart-dependencies-
     - name: Setup melos
       run: dart pub global activate melos && dart pub get

.github/workflows/main.yml

@@ -25,21 +25,15 @@ jobs:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/prepare
         with:
-          dart_version: ${{ needs.setup.outputs.dart_version }}
-      - name: Setup Flutter
-        uses: subosito/flutter-action@v2
-        with:
-          flutter-version: 3.27
-          cache: true
-          cache-key: "flutter-:os:-:channel:-:version:-:arch:-:hash:"
-          cache-path: "${{ runner.tool_cache }}/flutter/:channel:-:version:-:arch:"
+          flutter_version: ${{ needs.setup.outputs.flutter_version }}
       - name: Bootstrap Dart packages
         run: melos bootstrap --scope drift_docs,drift,app
         working-directory: .
       - name: Run build
         env:
           IS_RELEASE: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/latest-release' }}
         run: |
+          dart pub global activate webdev
           chmod +x ./docs.sh
           ./docs.sh build
       - name: Analyze Dart and Drift sources
@@ -89,7 +83,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/prepare
         with:
-          dart_version: ${{ needs.setup.outputs.dart_version }}
+          flutter_version: ${{ needs.setup.outputs.flutter_version }}
       - run: melos bootstrap --scope drift
         working-directory: .
       # analysis
@@ -121,7 +115,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/prepare
         with:
-          dart_version: ${{ needs.setup.outputs.dart_version }}
+          flutter_version: ${{ needs.setup.outputs.flutter_version }}
       - run: melos bootstrap --scope drift
         working-directory: .
       # Using build_runner test allows compiling the tests with ddc, which is much faster than
@@ -146,7 +140,7 @@ jobs:
   #     - uses: actions/checkout@v4
   #     - uses: ./.github/actions/prepare
   #       with:
-  #         dart_version: ${{ needs.setup.outputs.dart_version }}
+  #         flutter_version: ${{ needs.setup.outputs.flutter_version }}
   #     - run: melos bootstrap --scope drift
   #       working-directory: .
   #     - run: dart test -p ${{ matrix.browser }} --compiler dart2js --total-shards 4 --shard-index ${{ matrix.shard }}
@@ -159,14 +153,15 @@ jobs:
         working-directory: drift
     strategy:
       matrix:
-        browser: [chrome, firefox]
+        browser: [chrome] # Dart 3.7 unfortunately broke tests with dart2wasm on Firefox
+        # browser: [chrome, firefox]
     name: "Drift web unit tests, dart2wasm, ${{ matrix.browser }}"
     steps:
       # setup
       - uses: actions/checkout@v4
       - uses: ./.github/actions/prepare
         with:
-          dart_version: ${{ needs.setup.outputs.dart_version }}
+          flutter_version: ${{ needs.setup.outputs.flutter_version }}
       - run: melos bootstrap --scope drift
         working-directory: .
       - run: dart test -p ${{ matrix.browser }} --compiler dart2wasm
@@ -183,7 +178,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/prepare
         with:
-          dart_version: ${{ needs.setup.outputs.dart_version }}
+          flutter_version: ${{ needs.setup.outputs.flutter_version }}
       - run: melos bootstrap --scope drift_dev --scope drift
         working-directory: .
       # analysis
@@ -204,7 +199,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/prepare
         with:
-          dart_version: ${{ needs.setup.outputs.dart_version }}
+          flutter_version: ${{ needs.setup.outputs.flutter_version }}
       - run: dart pub upgrade
       # analysis
       - run: dart format -o none --set-exit-if-changed .
@@ -248,7 +243,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/prepare
         with:
-          dart_version: ${{ needs.setup.outputs.dart_version }}
+          flutter_version: ${{ needs.setup.outputs.flutter_version }}
       - run: melos bootstrap --no-flutter
         working-directory: .
       - name: Postgres integration tests
@@ -284,7 +279,9 @@ jobs:
     needs: [setup]
     strategy:
       matrix:
-        flutter: ["3.27"]
+        # We currently don't support <3.35.1 because we depend on melos v7, which needs Dart 3.9.0.
+        # Generally, we try to support the latest two stable Flutter releases.
+        flutter: ["3.35.1"]
 
     steps:
       - uses: actions/checkout@v4
@@ -327,17 +324,22 @@ jobs:
         working-directory: examples/app
       - run: flutter analyze
         working-directory: examples/app
+      - run: flutter analyze
+        working-directory: drift_flutter
+      - run: flutter test
+        working-directory: drift_flutter
       - run: flutter test
         working-directory: examples/app
   migration_integration_tests:
     name: "Integration tests for migration tooling"
     needs: [setup]
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/prepare
         with:
-          dart_version: ${{ needs.setup.outputs.dart_version }}
+          flutter_version: ${{ needs.setup.outputs.flutter_version }}
       - run: melos bootstrap --scope migrations_example
         working-directory: .
       - name: Run build
@@ -360,17 +362,18 @@ jobs:
     name: "Web integration tests"
     needs: [drift]
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/prepare
         with:
-          dart_version: ${{ needs.setup.outputs.dart_version }}
+          flutter_version: ${{ needs.setup.outputs.flutter_version }}
       - uses: nanasess/setup-chromedriver@v2
       - run: melos bootstrap --scope web_wasm
         working-directory: .
       - name: Test
         working-directory: extras/integration_tests/web_wasm
-        run: dart test
+        run: dart test -P gh_actions
 #  upload_coverage:
 #    runs-on: ubuntu-20.04
 #    needs: [moor, sqlparser]

.github/workflows/setup.yml

@@ -1,9 +1,9 @@
 on:
   workflow_call:
     outputs:
-      dart_version:
-        description: Version of the Dart SDK used during the setup run, useful for dependency restoring
-        value: ${{ jobs.dart_dependencies.outputs.dart_version }}
+      flutter_version:
+        description: Version of the Flutter SDK used during the setup run.
+        value: ${{ jobs.dart_dependencies.outputs.flutter_version }}
 
 jobs:
   # Compile the latest sqlite3 library, which will be used to run tests in drift
@@ -47,22 +47,22 @@ jobs:
     name: Get and cache Dart dependencies
     runs-on: ubuntu-latest
     outputs:
-      dart_version: ${{ steps.dart_version.outputs.version }}
+      flutter_version: ${{ steps.setup_flutter.outputs.VERSION }}
     steps:
       - uses: actions/checkout@v4
-      - uses: dart-lang/setup-dart@v1
-      - name: Get Dart version
-        id: dart_version
-        run: |
-          version=`cat $DART_HOME/version`
-          echo "Running on Dart $version"
-          echo "version=$version" >> $GITHUB_STATE
+      - name: Set up Flutter
+        id: setup_flutter
+        uses: subosito/flutter-action@v2
+        with:
+          cache: true
+          cache-key: "flutter-:os:-:channel:-:version:-:arch:-:hash:"
+          cache-path: "${{ runner.tool_cache }}/flutter/:channel:-:version:-:arch:"
       - uses: actions/cache@v4
         with:
           path: "${{ env.PUB_CACHE }}"
-          key: dart-dependencies-${{ steps.dart_version.outputs.version }}-${{ hashFiles('**/pubspec.yaml') }}
+          key: dart-dependencies-${{ steps.setup_flutter.outputs.VERSION }}-${{ hashFiles('**/pubspec.yaml') }}
           restore-keys: |
-            dart-dependencies-${{ steps.dart_version.outputs.version }}-
+            dart-dependencies-${{ steps.setup_flutter.outputs.VERSION }}-
             dart-dependencies-
       - name: Setup melos
         run: dart pub global activate melos && dart pub get

docs/README.md

@@ -11,10 +11,14 @@ Folder Structure:
 - `mkdocs` Contains the MkDocs configuration.
 
 ### Building the Documentation
+
 You will need to make the `docs.sh` script executable before you can run it. You can do this by running the following command:
 
 ```bash
 chmod +x docs.sh
+
+# Also, make sure webdev is installed:
+dart pub global activate webdev
 ```
 
 Run the following command to build the documentation:

docs/build.yaml

@@ -44,9 +44,8 @@ targets:
       drift_dev:analyzer:
         enabled: true
         options: &options
-          sql:
-            dialect: sqlite
-            options:
+          dialects:
+            sqlite:
               version: "3.39"
           databases:
             main_db: "lib/snippets/dart_api/manager.dart"

docs/docs.sh

@@ -35,9 +35,9 @@ run_webdev(){
     # The below command will compile the dart code in `/web` to js & run build_runner
     if [ $1 -eq 1 ]; then
         echo "Running dev build"
-        dart run webdev build -o web:build/web -- --delete-conflicting-outputs
+        dart pub global run webdev build -o web:build/web -- --delete-conflicting-outputs
     else
-        dart run webdev build -o web:build/web -- --delete-conflicting-outputs --release
+        dart pub global run webdev build -o web:build/web -- --delete-conflicting-outputs --release
     fi
     if [ $? -ne 0 ]; then
         echo "Failed to build the project"

docs/docs/Examples/existing_databases.md

@@ -38,8 +38,6 @@ flutter:
 
 To initialize the database before using drift, you need to extract the asset from your
 app onto the device.
-In drift, you can use a [LazyDatabase](https://pub.dev/documentation/drift/latest/drift/LazyDatabase-class.html)
-to perform that work just before your drift database is opened:
 
 ```dart
 import 'package:drift/drift.dart';
@@ -79,6 +77,21 @@ LazyDatabase _openConnection() {
 }
 ```
 
+===  "Using `drift_flutter`"
+
+    {{ load_snippet('(full)','lib/snippets/examples/existing_databases_flutter.dart.excerpt.json',indent=4) }}
+
+===  "Using `package:drift/native.dart`"
+
+    In drift, you can use a [LazyDatabase](https://pub.dev/documentation/drift/latest/drift/LazyDatabase-class.html)
+    to perform that work just before your drift database is opened:
+
+    {{ load_snippet('(full)','lib/snippets/examples/existing_databases_native.dart.excerpt.json',indent=4) }}
+
+
+!!! warning
+    This snippet only works on native platforms. See [existing databases on the web](../Platforms/web.md#using-existing-databases) for web support.
+
 Finally, use that method to open your database:
 
 ```dart

docs/docs/Examples/server_sync.md

@@ -35,8 +35,37 @@ in which he shares the approach used by Visible to sync local changes to the ser
 Additional approaches are also discussed in [this issue](https://github.com/simolus3/drift/issues/136) and
 [here](https://github.com/simolus3/drift/discussions/2880).
 
+Jan Zimola has published [a demo](https://github.com/Musta-Pollo/custom_supabase_drift_doc_sync) for data
+sync using the WatermelonDB protocol for synchronization (with a Dart implementation for clients and a pgSQL-based
+implementation for servers). The server code is generic and does not depend on the actual tables, only on their interface.
+It uses code generation to automate most of the client logic.
+
+## PowerSync
+
+<small>
+_Disclosure_: Drift maintainer Simon Binder [works at the team maintaining PowerSync](https://www.powersync.com/blog/simon-binder-joins-powersync).
+While this page only reflects his personal opinion, please keep that in mind and perhaps consult other sources on sync options for Dart too.
+</small>
+
+PowerSync is sync solution with [stable and official Flutter support](https://docs.powersync.com/client-sdk-references/flutter).
+Using a sync service available as a managed cloud offering or for self-hosting, you define buckets of data to make available to individual users.
+A client SDK for Dart/Flutter connects to this service to automatically sync changes from backend databases in real-time.
+
+While PowerSync automatically collects client-side changes, you're still responsible for uploading these to your backend (which can then validate them).
+For managed Postgres databases such as Supabase, using row-level security and [direct uploads from clients](https://docs.powersync.com/integration-guides/supabase-+-powersync)
+avoids the use of a separate backend.
+
+PowerSync also offers a [package for drift support](https://docs.powersync.com/client-sdk-references/flutter/flutter-orm-support#example-implementation) (currently in Alpha)
+that will make your query streams update in real-time for changes from the backend.
+[This example](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist-drift) shows how PowerSync can be integrated into a drift app.
+
 ## ElectricSQL
 
+!!! note "This section may be outdated"
+
+    The Dart package for Electric referenced here refers to an [older version of Electric SQL](https://legacy.electric-sql.com/),
+    the current version of Electric does not appear to be available to Dart apps.
+
 [ElectricSQL](https://electric-sql.com/) is a solution you can self-host to synchronize PostgreSQL databases
 with clients.
 Instead of having to deal with changes manually, a service receives updates from the PostgreSQL server and