Skip to content

Commit

Permalink
Update packages used in documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
simolus3 committed Sep 10, 2023
1 parent c3d2065 commit da0392c
Show file tree
Hide file tree
Showing 11 changed files with 101 additions and 108 deletions.
2 changes: 1 addition & 1 deletion docs/lib/sample/database.dart
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ Future<WasmDatabaseResult> 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) {
Expand Down
68 changes: 34 additions & 34 deletions docs/pages/docs/Advanced Features/type_converters.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.

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.
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.
{% endblock %}

Also note that you can't apply another type converter on a column declared with an enum converter.
Expand Down
20 changes: 10 additions & 10 deletions docs/pages/docs/Getting started/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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 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.
{% 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.
Expand Down
20 changes: 10 additions & 10 deletions docs/pages/docs/Getting started/starting_with_sql.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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 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.
{% endblock %}
12 changes: 6 additions & 6 deletions docs/pages/docs/Getting started/writing_queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -274,12 +274,12 @@ Future<void> 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
Expand Down
26 changes: 13 additions & 13 deletions docs/pages/docs/platforms.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

- 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.
`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.
{% endblock %}

## Web
Expand Down
10 changes: 5 additions & 5 deletions docs/pages/docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,30 +54,30 @@ 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`:
```dart
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;
Expand Down
19 changes: 5 additions & 14 deletions docs/pubspec.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -38,27 +38,18 @@ 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
mime:
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"
22 changes: 11 additions & 11 deletions docs/templates/partials/footer.html
Original file line number Diff line number Diff line change
@@ -1,29 +1,29 @@
{% assign links = site.links %}
<footer class="bg-dark py-5 row d-print-none">
<div class="container-fluid mx-sm-5">
<div class="row">
<footer class="td-footer row d-print-none">
<div class="container-fluid">
<div class="row mx-md-2">
<div class="col-6 col-sm-4 text-xs-center order-sm-2">
{% if links.user %}
{% assign links = links.user %}
{% include "partials/footer-links-block.html" %}
{% endif %}
</div>
<div class="col-6 col-sm-4 text-right text-xs-center order-sm-3">
<div class="col-6 col-sm-4 text-end text-xs-center order-sm-3">
{% if links.developer %}
{% assign links = links.developer %}
{% include "partials/footer-links-block.html" %}
{% endif %}
</div>
<div class="col-12 col-sm-4 text-center py-2 order-sm-2">
<div class="td-footer__copyright-etc col-12 col-sm-4 text-center py-2 order-sm-2">
{% if site.copyright %}
<small class="text-white"><div>&copy; {{ site.copyright }}</div>
Except where otherwise noted, content on this site is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer">CC BY 4.0</a> license.
Code snippets are marked with <a href="http://creativecommons.org/publicdomain/zero/1.0" target="_blank" rel="license noopener noreferrer">CC0 1.0</a>,
drift itself is <a href="https://github.com/simolus3/drift/blob/develop/LICENSE" rel="license" target="_blank">MIT-licensed</a>.
</small>
<span><div>&copy; {{ site.copyright }}</div>
Except where otherwise noted, content on this site is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer">CC BY 4.0</a> license.
Code snippets are marked with <a href="http://creativecommons.org/publicdomain/zero/1.0" target="_blank" rel="license noopener noreferrer">CC0 1.0</a>,
drift itself is <a href="https://github.com/simolus3/drift/blob/develop/LICENSE" rel="license" target="_blank">MIT-licensed</a>.
</span>
{% endif %}
{% if site.privacy_policy %}
<small class="ml-1"><a href="{{ site.privacy_policy }}" target="_blank">{{ "footer_privacy_policy" | i18n }}</a></small>
<span class="ml-1"><a href="{{ site.privacy_policy }}" target="_blank">{{ "footer_privacy_policy" | i18n }}</a></span>
{% endif %}
</div>
</div>
Expand Down
8 changes: 5 additions & 3 deletions docs/website.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ site:
- name: "Contact me via e-mail"
url: "mailto:oss@simonbinder.eu"
icon: "fa fa-envelope"
- name: "Room in gitter"
url: "https://gitter.im/moor-dart/community"
icon: "fab fa-gitter"
# - name: "Room in gitter"
# url: "https://gitter.im/moor-dart/community"
# icon: "fab fa-gitter"
- name: "Project on GitHub"
url: "https://github.com/simolus3/drift"
icon: "fab fa-github"
Expand All @@ -29,8 +29,10 @@ site:
url: "/docs/"
- name: "Pub"
url: "https://pub.dev/packages/drift"
external: true
- name: "GitHub"
url: "https://github.com/simolus3/drift/"
external: true
- name: "API docs"
url: "/api/"

Expand Down
2 changes: 1 addition & 1 deletion drift_dev/pubspec.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ dependencies:
sqlparser: '^0.31.0'

# Dart analysis
analyzer: ^5.12.0
analyzer: '>=5.12.0 <7.0.0'
analyzer_plugin: ^0.11.0
source_span: ^1.5.5
package_config: ^2.0.0
Expand Down

0 comments on commit da0392c

Please sign in to comment.