diff --git a/docs/lib/sample/database.dart b/docs/lib/sample/database.dart index a8e84a37..b5833f1c 100644 --- a/docs/lib/sample/database.dart +++ b/docs/lib/sample/database.dart @@ -87,7 +87,7 @@ Future connect() async { final result = await WasmDatabase.open( databaseName: 'todo_example', sqlite3Uri: Uri.parse('sqlite3.wasm'), - driftWorkerUri: Uri.parse('drift_worker.dart.js'), + driftWorkerUri: Uri.parse('/drift_worker.dart.js'), ); if (!result.chosenImplementation.fullySupported) { diff --git a/docs/pages/docs/Advanced Features/type_converters.md b/docs/pages/docs/Advanced Features/type_converters.md index 7a120ef0..3c2f344f 100644 --- a/docs/pages/docs/Advanced Features/type_converters.md +++ b/docs/pages/docs/Advanced Features/type_converters.md @@ -34,8 +34,8 @@ the object in `select`, `update` and `insert` statements. This feature also works with [compiled custom queries]({{ "/queries/custom" | absUrl }}). {% block "blocks/alert" title="Caution with equality" color="warning" %} -> If your converter returns an object that is not comparable by value, the generated dataclass will not - be comparable by value. +If your converter returns an object that is not comparable by value, the generated dataclass will not +be comparable by value. {% endblock %} ### Implicit enum converters @@ -59,23 +59,23 @@ class Tasks extends Table { ``` {% block "blocks/alert" title="Caution with enums" color="warning" %} -> It can be easy to accidentally invalidate your database by introducing another enum value. - For instance, let's say we inserted a `Task` into the database in the above example and set its - `Status` to `running` (index = 1). - Now we modify `Status` enum to include another entry: - ```dart - enum Status { - none, - starting, // new! - running, - stopped, - paused - } - ``` - When selecting the task, it will now report as `starting`, as that's the new value at index 1. - For this reason, it's best to add new values at the end of the enumeration, where they can't conflict - with existing values. Otherwise you'd need to bump your schema version and run a custom update statement - to fix this. +It can be easy to accidentally invalidate your database by introducing another enum value. +For instance, let's say we inserted a `Task` into the database in the above example and set its +`Status` to `running` (index = 1). +Now we modify `Status` enum to include another entry: +```dart +enum Status { + none, + starting, // new! + running, + stopped, + paused +} +``` +When selecting the task, it will now report as `starting`, as that's the new value at index 1. +For this reason, it's best to add new values at the end of the enumeration, where they can't conflict +with existing values. Otherwise you'd need to bump your schema version and run a custom update statement +to fix this. {% endblock %} If you prefer to store the enum as a text, you can use `textEnum` instead. @@ -95,21 +95,21 @@ class Tasks extends Table { ``` {% block "blocks/alert" title="Caution with enums" color="warning" %} -> It can be easy to accidentally invalidate your database by renaming your enum values. - For instance, let's say we inserted a `Task` into the database in the above example and set its - `Status` to `running`. - Now we modify `Status` enum to rename `running` into `processing`: - ```dart - enum Status { - none, - processing, - stopped, - paused - } - ``` - When selecting the task, it won't be able to find the enum value `running` anymore, and will throw an error. +It can be easy to accidentally invalidate your database by renaming your enum values. +For instance, let's say we inserted a `Task` into the database in the above example and set its +`Status` to `running`. +Now we modify `Status` enum to rename `running` into `processing`: +```dart +enum Status { + none, + processing, + stopped, + paused +} +``` +When selecting the task, it won't be able to find the enum value `running` anymore, and will throw an error. - For this reason, it's best to not modify the name of your enum values. Otherwise you'd need to bump your schema version and run a custom update statement to fix this. +For this reason, it's best to not modify the name of your enum values. Otherwise you'd need to bump your schema version and run a custom update statement to fix this. {% endblock %} Also note that you can't apply another type converter on a column declared with an enum converter. diff --git a/docs/pages/docs/Getting started/index.md b/docs/pages/docs/Getting started/index.md index aa68ea7b..5833f914 100644 --- a/docs/pages/docs/Getting started/index.md +++ b/docs/pages/docs/Getting started/index.md @@ -77,16 +77,16 @@ The ["Writing queries"]({{ "writing_queries.md" | pageUrl }}) article contains e to know to write selects, updates and inserts in drift! {% block "blocks/alert" title="Using the database" %} -> The database class from this guide is ready to be used with your app. - For Flutter apps, a Drift database class is typically instantiated at the top of your widget tree - and then passed down with `provider` or `riverpod`. - See [using the database]({{ '../faq.md#using-the-database' | pageUrl }}) for ideas on how to integrate - Drift into your app's state management. +The database class from this guide is ready to be used with your app. +For Flutter apps, a Drift database class is typically instantiated at the top of your widget tree +and then passed down with `provider` or `riverpod`. +See [using the database]({{ '../faq.md#using-the-database' | pageUrl }}) for ideas on how to integrate +Drift into your app's state management. - The setup in this guide uses [platform channels](https://flutter.dev/docs/development/platform-integration/platform-channels), - which are only available after running `runApp` by default. - When using drift before your app is initialized, please call `WidgetsFlutterBinding.ensureInitialized()` before using - the database to ensure that platform channels are ready. +The setup in this guide uses [platform channels](https://flutter.dev/docs/development/platform-integration/platform-channels), +which are only available after running `runApp` by default. +When using drift before your app is initialized, please call `WidgetsFlutterBinding.ensureInitialized()` before using +the database to ensure that platform channels are ready. {% endblock %} - The articles on [writing queries]({{ 'writing_queries.md' | pageUrl }}) and [Dart tables]({{ 'advanced_dart_tables.md' | pageUrl }}) introduce important concepts of the Dart API used to write queries. diff --git a/docs/pages/docs/Getting started/starting_with_sql.md b/docs/pages/docs/Getting started/starting_with_sql.md index 933ed494..37141418 100644 --- a/docs/pages/docs/Getting started/starting_with_sql.md +++ b/docs/pages/docs/Getting started/starting_with_sql.md @@ -94,14 +94,14 @@ further guides to help you learn more: on `drift` files, which explains `import` statements and the Dart-SQL interop. {% block "blocks/alert" title="Using the database" %} -> The database class from this guide is ready to be used with your app. - For Flutter apps, a Drift database class is typically instantiated at the top of your widget tree - and then passed down with `provider` or `riverpod`. - See [using the database]({{ '../faq.md#using-the-database' | pageUrl }}) for ideas on how to integrate - Drift into your app's state management. +The database class from this guide is ready to be used with your app. +For Flutter apps, a Drift database class is typically instantiated at the top of your widget tree +and then passed down with `provider` or `riverpod`. +See [using the database]({{ '../faq.md#using-the-database' | pageUrl }}) for ideas on how to integrate +Drift into your app's state management. - The setup in this guide uses [platform channels](https://flutter.dev/docs/development/platform-integration/platform-channels), - which are only available after running `runApp` by default. - When using drift before your app is initialized, please call `WidgetsFlutterBinding.ensureInitialized()` before using - the database to ensure that platform channels are ready. +The setup in this guide uses [platform channels](https://flutter.dev/docs/development/platform-integration/platform-channels), +which are only available after running `runApp` by default. +When using drift before your app is initialized, please call `WidgetsFlutterBinding.ensureInitialized()` before using +the database to ensure that platform channels are ready. {% endblock %} diff --git a/docs/pages/docs/Getting started/writing_queries.md b/docs/pages/docs/Getting started/writing_queries.md index 796c05b2..314929ac 100644 --- a/docs/pages/docs/Getting started/writing_queries.md +++ b/docs/pages/docs/Getting started/writing_queries.md @@ -274,12 +274,12 @@ Future trackWord(String word) { ``` {% block "blocks/alert" title="Unique constraints and conflict targets" %} -> Both `insertOnConflictUpdate` and `onConflict: DoUpdate` use an `DO UPDATE` - upsert in sql. This requires us to provide a so-called "conflict target", a - set of columns to check for uniqueness violations. By default, drift will use - the table's primary key as conflict target. That works in most cases, but if - you have custom `UNIQUE` constraints on some columns, you'll need to use - the `target` parameter on `DoUpdate` in Dart to include those columns. +Both `insertOnConflictUpdate` and `onConflict: DoUpdate` use an `DO UPDATE` +upsert in sql. This requires us to provide a so-called "conflict target", a +set of columns to check for uniqueness violations. By default, drift will use +the table's primary key as conflict target. That works in most cases, but if +you have custom `UNIQUE` constraints on some columns, you'll need to use +the `target` parameter on `DoUpdate` in Dart to include those columns. {% endblock %} Note that this requires a fairly recent sqlite3 version (3.24.0) that might not diff --git a/docs/pages/docs/platforms.md b/docs/pages/docs/platforms.md index 5e723c4f..f7896fd0 100644 --- a/docs/pages/docs/platforms.md +++ b/docs/pages/docs/platforms.md @@ -56,19 +56,19 @@ It only applies to your full Flutter app though, it can't override the sqlite3 v with `flutter test`. {% block "blocks/alert" title="A note on ffi and Android" %} -> `package:drift/native.dart` is the recommended drift implementation for new Android apps. - However, there are some smaller issues on some devices that you should be aware of: +`package:drift/native.dart` is the recommended drift implementation for new Android apps. +However, there are some smaller issues on some devices that you should be aware of: - - Using `sqlite3_flutter_libs` will include prebuilt binaries for 32-bit `x86` devices which you - probably won't need. You can apply a [filter](https://github.com/simolus3/sqlite3.dart/tree/master/sqlite3_flutter_libs#included-platforms) - in your `build.gradle` to remove those binaries. - - Opening `libsqlite3.so` fails on some Android 6.0.1 devices. This can be fixed by setting - `android.bundle.enableUncompressedNativeLibs=false` in your `gradle.properties` file. - Note that this will increase the disk usage of your app. See [this issue](https://github.com/simolus3/drift/issues/895#issuecomment-720195005) - for details. - - Out of memory errors for very complex queries: Since the regular tmp directory isn't available on Android, you need to inform - sqlite3 about the right directory to store temporary data. See [this comment](https://github.com/simolus3/drift/issues/876#issuecomment-710013503) - for an example on how to do that. +- Using `sqlite3_flutter_libs` will include prebuilt binaries for 32-bit `x86` devices which you + probably won't need. You can apply a [filter](https://github.com/simolus3/sqlite3.dart/tree/master/sqlite3_flutter_libs#included-platforms) + in your `build.gradle` to remove those binaries. +- Opening `libsqlite3.so` fails on some Android 6.0.1 devices. This can be fixed by setting + `android.bundle.enableUncompressedNativeLibs=false` in your `gradle.properties` file. + Note that this will increase the disk usage of your app. See [this issue](https://github.com/simolus3/drift/issues/895#issuecomment-720195005) + for details. +- Out of memory errors for very complex queries: Since the regular tmp directory isn't available on Android, you need to inform + sqlite3 about the right directory to store temporary data. See [this comment](https://github.com/simolus3/drift/issues/876#issuecomment-710013503) + for an example on how to do that. {% endblock %} ## Web diff --git a/docs/pages/docs/testing.md b/docs/pages/docs/testing.md index 6597d50c..13e426e7 100644 --- a/docs/pages/docs/testing.md +++ b/docs/pages/docs/testing.md @@ -54,22 +54,22 @@ class MyDatabase extends _$MyDatabase { We can't distribute an sqlite installation as a pub package (at least not as something that works outside of a Flutter build), so you need to ensure that you have the sqlite3 shared library installed on your -system. +system. On macOS, it's installed by default. -On Linux, you can use the `libsqlite3-dev` package on Ubuntu and the +On Linux, you can use the `libsqlite3-dev` package on Ubuntu and the `sqlite3` package on Arch (other distros will have similar packages). On Windows, you can [download 'Precompiled Binaries for Windows'](https://www.sqlite.org/download.html) -and extract `sqlite3.dll` into a folder that's in your `PATH` +and extract `sqlite3.dll` into a folder that's in your `PATH` environment variable. Then restart your device to ensure that all apps will run with this `PATH` change. {% endblock %} ## Writing tests -We can create an in-memory version of the database by using a +We can create an in-memory version of the database by using a `NativeDatabase.memory()` instead of a `FlutterQueryExecutor` or other implementations. A good place to open the database is the `setUp` and `tearDown` methods from `package:test`: @@ -77,7 +77,7 @@ place to open the database is the `setUp` and `tearDown` methods from import 'package:drift/native.dart'; import 'package:test/test.dart'; // the file defined above, you can test any drift database of course -import 'database.dart'; +import 'database.dart'; void main() { MyDatabase database; diff --git a/docs/pubspec.yaml b/docs/pubspec.yaml index ede27dd4..645e8e8d 100644 --- a/docs/pubspec.yaml +++ b/docs/pubspec.yaml @@ -11,12 +11,12 @@ dependencies: json_annotation: ^4.8.1 docsy: hosted: https://simonbinder.eu - version: ^0.2.2 + version: ^0.2.3 code_snippets: hosted: https://simonbinder.eu - version: ^0.0.12 + version: ^0.0.13 # used in snippets - http: ^0.13.5 + http: ^1.1.0 sqlite3: ^2.0.0 # Fake path_provider for snippets path_provider: @@ -38,16 +38,14 @@ dev_dependencies: build_web_compilers: ^4.0.0 built_site: hosted: https://simonbinder.eu - version: ^0.2.15 - linkcheck: ^3.0.0 + version: ^0.2.16 json_serializable: ^6.1.6 shelf: ^1.2.0 shelf_static: ^1.1.0 source_span: ^1.9.1 test: ^1.18.0 sqlparser: - zap_dev: ^0.2.2 - + zap_dev: ^0.2.3+1 dependency_overrides: # todo: Remove after https://github.com/dart-lang/mime/pull/43 @@ -55,10 +53,3 @@ dependency_overrides: git: url: https://github.com/simolus3/mime.git ref: woff2 - # The bootstrap_sass on pub.dev doesn't support null safety, so I'm hosting - # https://github.com/dart-league/bootstrap_sass/pull/13. - # Hopefully this can change soon once docsy migrates to bootstrap 5 - bootstrap_sass: - hosted: - url: https://simonbinder.eu - version: "4.6.0" diff --git a/docs/templates/partials/footer.html b/docs/templates/partials/footer.html index a8f984d1..0e2055b5 100644 --- a/docs/templates/partials/footer.html +++ b/docs/templates/partials/footer.html @@ -1,29 +1,29 @@ {% assign links = site.links %} -