AMT-Cheif
/
drift
mirror of https://github.com/AMT-Cheif/drift.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Move remaining pages to their target destination

This commit is contained in:
Simon Binder 2023-09-18 23:04:47 +02:00
parent e059313649
commit addb457d4a
No known key found for this signature in database
GPG Key ID: 7891917E4147B8C0
27 changed files with 291 additions and 235 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/lib/snippets/dart_api/tables.dart
View File

@ -82,3 +82,17 @@ class Users extends Table {
TextColumn get name => text()();
}
// #enddocregion index
// #docregion custom-type
typedef Category = ({int id, String name});
@UseRowClass(Category)
class Categories extends Table {
IntColumn get id => integer().autoIncrement()();
TextColumn get name => text()();
// #enddocregion custom-type
@override
String get tableName => 'categories2';
// #docregion custom-type
}
// #enddocregion custom-type

0
docs/lib/snippets/platforms.dart → docs/lib/snippets/platforms/platforms.dart
View File

7
docs/pages/docs/Advanced Features/index.md
View File

@ -1,7 +0,0 @@
---
data:
title: Advanced Features
weight: 20
description: Learn about some advanced features of drift
template: layouts/docs/list
---

1
docs/pages/docs/CLI.md
View File

@ -2,6 +2,7 @@
data:
title: "Command line tools for drift"
description: A set of CLI tools to interact with drift projects
weight: 20
path: /cli/
template: layouts/docs/single
---

2
docs/pages/docs/Dart API/index.md
View File

@ -1,7 +1,7 @@
---
data:
title: Dart API
description: Drift APIs for your app
description: Drift's Dart library for declaring tables and writing queries.
weight: 2
template: layouts/docs/list
---

0
docs/pages/docs/Advanced Features/schema_inspection.md → docs/pages/docs/Dart API/schema_inspection.md
View File

37
docs/pages/docs/Dart API/tables.md
View File

@ -28,10 +28,10 @@ In the example above, `IntColumn get category => integer().nullable()();` define
holding nullable integer values named `category`.
This section describes all the options available when declaring columns.
## Supported column types
### Supported column types
Drift supports a variety of column types out of the box. You can store custom classes in columns by using
[type converters]({{ "../Advanced Features/type_converters.md" | pageUrl }}).
[type converters]({{ "../type_converters.md" | pageUrl }}).
| Dart type | Column | Corresponding SQLite type |
|--------------|---------------|-----------------------------------------------------|
@ -42,8 +42,8 @@ Drift supports a variety of column types out of the box. You can store custom cl
| `String` | `text()` | `TEXT` |
| `DateTime` | `dateTime()` | `INTEGER` (default) or `TEXT` depending on [options](#datetime-options) |
| `Uint8List` | `blob()` | `BLOB` |
| `Enum` | `intEnum()` | `INTEGER` (more information available [here]({{ "../Advanced Features/type_converters.md#implicit-enum-converters" | pageUrl }})). |
| `Enum` | `textEnum()` | `TEXT` (more information available [here]({{ "../Advanced Features/type_converters.md#implicit-enum-converters" | pageUrl }})). |
| `Enum` | `intEnum()` | `INTEGER` (more information available [here]({{ "../type_converters.md#implicit-enum-converters" | pageUrl }})). |
| `Enum` | `textEnum()` | `TEXT` (more information available [here]({{ "../type_converters.md#implicit-enum-converters" | pageUrl }})). |
Note that the mapping for `boolean`, `dateTime` and type converters only applies when storing records in
the database.
@ -51,6 +51,17 @@ They don't affect JSON serialization at all. For instance, `boolean` values are
in the `fromJson` factory, even though they would be saved as `0` or `1` in the database.
If you want a custom mapping for JSON, you need to provide your own [`ValueSerializer`](https://pub.dev/documentation/drift/latest/drift/ValueSerializer-class.html).
### Custom column types
While is constrained by the types supported by sqlite3, it supports type converters
to store arbitrary Dart types in SQL.
{% assign type_converters = 'package:drift_docs/snippets/type_converters/converters.dart.excerpt.json' | readString | json_decode %}
{% include "blocks/snippet" snippets = type_converters name = 'table' %}
For more information about type converters, see the page on [type converters]({{ "../type_converters.md#implicit-enum-converters" | pageUrl }})
on this website.
### `BigInt` support
Drift supports the `int64()` column builder to indicate that a column stores
@ -125,7 +136,7 @@ Drift supports two approaches of storing `DateTime` values in SQL:
This behavior works well with the date functions in sqlite3 while also
preserving "UTC-ness" for stored values.
The mode can be changed with the `store_date_time_values_as_text` [build option]({{ '../Advanced Features/builder_options.md' | pageUrl }}).
The mode can be changed with the `store_date_time_values_as_text` [build option]({{ '../Generation options/index.md' | pageUrl }}).
Regardless of the option used, drift's builtin support for
[date and time functions]({{ 'expressions.md#date-and-time' | pageUrl }})
@ -217,7 +228,7 @@ If you do want to make a column nullable, just use `nullable()`:
{% include "blocks/snippet" snippets = snippets name = 'nnbd' %}
## References
### References
[Foreign key references](https://www.sqlite.org/foreignkeys.html) can be expressed
in Dart tables with the `references()` method when building a column:
@ -234,7 +245,7 @@ Be aware that, in sqlite3, foreign key references aren't enabled by default.
They need to be enabled with `PRAGMA foreign_keys = ON`.
A suitable place to issue that pragma with drift is in a [post-migration callback]({{ '../Migrations/index.md#post-migration-callbacks' | pageUrl }}).
## Default values
### Default values
You can set a default value for a column. When not explicitly set, the default value will
be used when inserting a new row. To set a constant default value, use `withDefault`:
@ -340,6 +351,18 @@ That doesn't work in all cases though. With the `EnabledCategories` class from a
a `EnabledCategorie` data class. In those cases, you can use the [`@DataClassName`](https://pub.dev/documentation/drift/latest/drift/DataClassName-class.html)
annotation to set the desired name.
## Existing row classes
By default, drift generates a row class for each table. This row class can be used to access all columns, it also
implements `hashCode`, `operator==` and a few other useful operators.
When you want to use your own type hierarchy, or have more control over the generated classes, you can
also tell drift to your own class or type:
{% include "blocks/snippet" snippets = snippets name="custom-type" %}
Drift verifies that the type is suitable for storing a row of that table.
More details about this feature are [described here]({{ '../custom_row_classes.md' | pageUrl }}).
## Table options
In addition to the options added to individual columns, some constraints apply to the whole

2
docs/pages/docs/Dart API/views.md
View File

@ -20,7 +20,7 @@ Inside a Dart view, use
The columns referenced in `select` may refer to two kinds of columns:
- Columns defined on the view itself (like `itemCount` in the example above).
- Columns defined on referenced tables (like `categories.description` in the example).
For these references, advanced drift features like [type converters]({{ '../Advanced Features/type_converters.md' | pageUrl }})
For these references, advanced drift features like [type converters]({{ '../type_converters.md' | pageUrl }})
used in the column's definition from the table are also applied to the view's column.
Both kind of columns will be added to the data class for the view when selected.

2
docs/pages/docs/Examples/index.md
View File

@ -1,7 +1,7 @@
---
data:
title: "Examples"
weight: 3
weight: 30
description: Example apps using drift
template: layouts/docs/list
---

63
docs/pages/docs/Generation options/in_other_builders.md Normal file
View File

@ -0,0 +1,63 @@
---
data:
title: "Using drift classes in other builders"
description: Configure your build to allow drift dataclasses to be seen by other builders.
template: layouts/docs/single
---
It is possible to use classes generated by drift in other builders.
Due to technicalities related to Dart's build system and `source_gen`, this approach requires a custom configuration
and minor code changes. Put this content in a file called `build.yaml` next to your `pubspec.yaml`:
```yaml
targets:
$default:
# disable the default generators, we'll only use the non-shared drift generator here
auto_apply_builders: false
builders:
drift_dev|not_shared:
enabled: true
# If needed, you can configure the builder like this:
# options:
# skip_verification_code: true
# use_experimental_inference: true
# This builder is necessary for drift-file preprocessing. You can disable it if you're not
# using .drift files with type converters.
drift_dev|preparing_builder:
enabled: true
run_built_value:
dependencies: ['your_package_name']
builders:
# Disable drift builders. By default, those would run on each target
drift_dev:
enabled: false
drift_dev|preparing_builder:
enabled: false
# we don't need to disable drift|not_shared, because it's disabled by default
```
In all files that use generated drift code, you'll have to replace `part 'filename.g.dart'` with `part 'filename.drift.dart'`.
If you use drift _and_ another builder in the same file, you'll need both `.g.dart` and `.drift.dart` as part-files.
A full example is available as part of [the drift repo](https://github.com/simolus3/drift/tree/develop/examples/with_built_value).
If you run into any problems with this approach, feel free to open an issue on drift.
## The technicalities, explained
Almost all code generation packages use a so called "shared part file" approach provided by `source_gen`.
It's a common protocol that allows unrelated builders to write into the same `.g.dart` file.
For this to work, each builder first writes a `.part` file with its name. For instance, if you used `drift`
and `built_value` in the same project, those part files could be called `.drift.part` and `.built_value.part`.
Later, the common `source_gen` package would merge the part files into a single `.g.dart` file.
This works great for most use cases, but a downside is that each builder can't see the final `.g.dart`
file, or use any classes or methods defined in it. To fix that, drift offers an optional builder -
`drift_dev|not_shared` - that will generate a separate part file only containing
code generated by drift. So most of the work resolves around disabling the default generator of drift
and use the non-shared generator instead.
Finally, we need to the build system to run drift first, and all the other builders otherwise. This is
why we split the builders up into multiple targets. The first target will only run drift, the second
target has a dependency on the first one and will run all the other builders.

199
docs/pages/docs/Advanced Features/builder_options.md → docs/pages/docs/Generation options/index.md
View File

@ -1,11 +1,12 @@
---
data:
title: "Builder options"
description: >-
Advanced options applied when writing the generated code
template: layouts/docs/single
aliases:
- "options/"
title: Generation options
description: Options for `drift_dev` and `build_runner` to change the generated code.
weight: 7
template: layouts/docs/list
#path: docs/advanced-features/builder_options/
#aliases:
# - "options/"
---
The `drift_dev` package supports a range of options that control how code
@ -75,7 +76,7 @@ At the moment, drift supports these options:
* `case_from_dart_to_sql` (defaults to `snake_case`): Controls how the table and column names are re-cased from the Dart identifiers.
The possible values are `preserve`, `camelCase`, `CONSTANT_CASE`, `snake_case`, `PascalCase`, `lowercase` and `UPPERCASE` (default: `snake_case`).
* `write_to_columns_mixins`: Whether the `toColumns` method should be written as a mixin instead of being added directly to the data class.
This is useful when using [existing row classes]({{ 'custom_row_classes.md' | pageUrl }}), as the mixin is generated for those as well.
This is useful when using [existing row classes]({{ '../custom_row_classes.md' | pageUrl }}), as the mixin is generated for those as well.
* `fatal_warnings`: When enabled (defaults to `false`), warnings found by `drift_dev` in the build process (like syntax errors in SQL queries or
unresolved references in your Dart tables) will cause the build to fail.
* `preamble`: This option is useful when using drift [as a standalone part builder](#using-drift-classes-in-other-builders) or when running a
@ -226,187 +227,7 @@ We recommend enabling these options.
{% endcomment %}
However, you can disable some default drift features and reduce the amount of generated code with the following options:
- `skip_verification_code: true`: You can remove a significant portion of generated code with this option. The
downside is that error messages when inserting invalid data will be less specific.
- `skip_verification_code: true`: You can remove a significant portion of generated code with this option. The
downside is that error messages when inserting invalid data will be less specific.
- `data_class_to_companions: false`: Don't generate the `toCompanion` method on data classes. If you don't need that
method, you can disable this option.
## Using drift classes in other builders
It is possible to use classes generated by drift in other builders.
Due to technicalities related to Dart's build system and `source_gen`, this approach requires a custom configuration
and minor code changes. Put this content in a file called `build.yaml` next to your `pubspec.yaml`:
```yaml
targets:
$default:
# disable the default generators, we'll only use the non-shared drift generator here
auto_apply_builders: false
builders:
drift_dev|not_shared:
enabled: true
# If needed, you can configure the builder like this:
# options:
# skip_verification_code: true
# use_experimental_inference: true
# This builder is necessary for drift-file preprocessing. You can disable it if you're not
# using .drift files with type converters.
drift_dev|preparing_builder:
enabled: true
run_built_value:
dependencies: ['your_package_name']
builders:
# Disable drift builders. By default, those would run on each target
drift_dev:
enabled: false
drift_dev|preparing_builder:
enabled: false
# we don't need to disable drift|not_shared, because it's disabled by default
```
In all files that use generated drift code, you'll have to replace `part 'filename.g.dart'` with `part 'filename.drift.dart'`.
If you use drift _and_ another builder in the same file, you'll need both `.g.dart` and `.drift.dart` as part-files.
A full example is available as part of [the drift repo](https://github.com/simolus3/drift/tree/develop/examples/with_built_value).
If you run into any problems with this approach, feel free to open an issue on drift.
### The technicalities, explained
Almost all code generation packages use a so called "shared part file" approach provided by `source_gen`.
It's a common protocol that allows unrelated builders to write into the same `.g.dart` file.
For this to work, each builder first writes a `.part` file with its name. For instance, if you used `drift`
and `built_value` in the same project, those part files could be called `.drift.part` and `.built_value.part`.
Later, the common `source_gen` package would merge the part files into a single `.g.dart` file.
This works great for most use cases, but a downside is that each builder can't see the final `.g.dart`
file, or use any classes or methods defined in it. To fix that, drift offers an optional builder -
`drift_dev|not_shared` - that will generate a separate part file only containing
code generated by drift. So most of the work resolves around disabling the default generator of drift
and use the non-shared generator instead.
Finally, we need to the build system to run drift first, and all the other builders otherwise. This is
why we split the builders up into multiple targets. The first target will only run drift, the second
target has a dependency on the first one and will run all the other builders.
## Modular code generation
By default, drift generates code from a single entrypoint - all tables, views
and queries for a database are generated into a single part file.
For larger projects, this file can become quite large, slowing down builds and
the analyzer when it is re-generated.
Drift supports an alternative and modular code-generation mode intended as an
alternative for larger projects.
With this setup, drift generates multiple files and automatically manages
imports between them.
As a motivating example, consider a large drift project with many tables or
views being split across different files:
```
lib/src/database/
├── database.dart
├── tables/
│ ├── users.drift
│ ├── settings.drift
│ ├── groups.drift
│ └── search.drift
└── views/
├── friends.drift
└── categories.dart
```
While a modular structure (with `import`s in drift files) is helpful to structure
sources, drift still generates everything into a single `database.g.dart` file.
With a growing number of tables and queries, drift may need to generate tens of
thousands of lines of code for data classes, companions and query results.
With its modular generation mode, drift instead generates sources for each input
file, like this:
```
lib/src/database/
├── database.dart
├── database.drift.dart
├── tables/
│ ├── users.drift
│ ├── users.drift.dart
│ ├── settings.drift
│ ├── settings.drift.dart
│ └── ...
└── views/
├── friends.drift
├── friends.drift.dart
├── categories.dart
└── categories.drift.dart
```
### Enabling modular code generation
_Note_: A small example using modular code generation is also part of [drift's repository](https://github.com/simolus3/drift/tree/develop/examples/modular).
As drift's modular code generation mode generates different file patterns than
the default builder, it needs to be enabled explicitly. For this, create a
`build.yaml` file in which you disable the default `drift_dev` build and enable
the two builders for modular generation: `drift_dev:analyzer` and
`drift_dev:modular`. They should both get the same options:
```yaml
targets:
$default:
builders:
drift_dev:
# disable drift's default builder, we're using the modular setup
# instead.
enabled: false
# Instead, enable drift_dev:analyzer and drift_dev:modular manually:
drift_dev:analyzer:
enabled: true
options: &options
# Drift build options, as per https://drift.simonbinder.eu/docs/advanced-features/builder_options/
store_date_time_values_as_text: true
named_parameters: true
sql:
dialect: sqlite
options:
version: "3.39"
modules: [fts5]
drift_dev:modular:
enabled: true
# We use yaml anchors to give the two builders the same options
options: *options
```
### What gets generated
With modular generation, drift generates standalone Dart libraries (Dart files
without a `part of` statement). This also means that you no longer need `part`
statements in your sources. Instead, you import the generated `.drift.dart`
files.
When it comes to using the generated code, not much is different: The API for
the database and DAOs stays mostly the same.
A big exception are how `.drift` files are handled in the modular generation
mode. In the default builder, all queries in all drift files are generated as
methods on the database.
With modular code generation, drift generates an implicit database accessor
reachable through getters from the database class. Consider a file `user.drift`
like this:
```sql
CREATE TABLE users (
id INTEGER NOT NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
name TEXT NOT NULL,
is_admin BOOLEAN NOT NULL DEFAULT FALSE
);
findUsers($predicate = TRUE): SELECT * FROM users WHERE $predicate;
```
If such a `users.drift` file is included from a database, we no longer generate
a `findUsers` method for the database itself.
Instead, a `users.drift.dart` file contains a [database accessor]({{ '../Dart API/daos.md' | pageUrl }}) called `UsersDrift` which is implicitly added to the database.
To call `findUsers`, you'd now call `database.usersDrift.findUsers()`.

125
docs/pages/docs/Generation options/modular.md Normal file
View File

@ -0,0 +1,125 @@
---
data:
title: "Modular code generation"
description: Make drift generate code in multiple files.
template: layouts/docs/single
---
By default, drift generates code from a single entrypoint - all tables, views
and queries for a database are generated into a single part file.
For larger projects, this file can become quite large, slowing down builds and
the analyzer when it is re-generated.
Drift supports an alternative and modular code-generation mode intended as an
alternative for larger projects.
With this setup, drift generates multiple files and automatically manages
imports between them.
As a motivating example, consider a large drift project with many tables or
views being split across different files:
```
lib/src/database/
├── database.dart
├── tables/
│ ├── users.drift
│ ├── settings.drift
│ ├── groups.drift
│ └── search.drift
└── views/
├── friends.drift
└── categories.dart
```
While a modular structure (with `import`s in drift files) is helpful to structure
sources, drift still generates everything into a single `database.g.dart` file.
With a growing number of tables and queries, drift may need to generate tens of
thousands of lines of code for data classes, companions and query results.
With its modular generation mode, drift instead generates sources for each input
file, like this:
```
lib/src/database/
├── database.dart
├── database.drift.dart
├── tables/
│ ├── users.drift
│ ├── users.drift.dart
│ ├── settings.drift
│ ├── settings.drift.dart
│ └── ...
└── views/
├── friends.drift
├── friends.drift.dart
├── categories.dart
└── categories.drift.dart
```
## Enabling modular code generation
_Note_: A small example using modular code generation is also part of [drift's repository](https://github.com/simolus3/drift/tree/develop/examples/modular).
As drift's modular code generation mode generates different file patterns than
the default builder, it needs to be enabled explicitly. For this, create a
`build.yaml` file in which you disable the default `drift_dev` build and enable
the two builders for modular generation: `drift_dev:analyzer` and
`drift_dev:modular`. They should both get the same options:
```yaml
targets:
$default:
builders:
drift_dev:
# disable drift's default builder, we're using the modular setup
# instead.
enabled: false
# Instead, enable drift_dev:analyzer and drift_dev:modular manually:
drift_dev:analyzer:
enabled: true
options: &options
# Drift build options, as per https://drift.simonbinder.eu/docs/advanced-features/builder_options/
store_date_time_values_as_text: true
named_parameters: true
sql:
dialect: sqlite
options:
version: "3.39"
modules: [fts5]
drift_dev:modular:
enabled: true
# We use yaml anchors to give the two builders the same options
options: *options
```
## What gets generated
With modular generation, drift generates standalone Dart libraries (Dart files
without a `part of` statement). This also means that you no longer need `part`
statements in your sources. Instead, you import the generated `.drift.dart`
files.
When it comes to using the generated code, not much is different: The API for
the database and DAOs stays mostly the same.
A big exception are how `.drift` files are handled in the modular generation
mode. In the default builder, all queries in all drift files are generated as
methods on the database.
With modular code generation, drift generates an implicit database accessor
reachable through getters from the database class. Consider a file `user.drift`
like this:
```sql
CREATE TABLE users (
id INTEGER NOT NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
name TEXT NOT NULL,
is_admin BOOLEAN NOT NULL DEFAULT FALSE
);
findUsers($predicate = TRUE): SELECT * FROM users WHERE $predicate;
```
If such a `users.drift` file is included from a database, we no longer generate
a `findUsers` method for the database itself.
Instead, a `users.drift.dart` file contains a [database accessor]({{ '../Dart API/daos.md' | pageUrl }}) called `UsersDrift` which is implicitly added to the database.
To call `findUsers`, you'd now call `database.usersDrift.findUsers()`.

1
docs/pages/docs/Migrations/index.md
View File

@ -2,6 +2,7 @@
data:
title: Migrations
description: Tooling and APIs to safely change the schema of your database.
weight: 4
template: layouts/docs/list
aliases:
- /migrations

7
docs/pages/docs/Platforms/index.md
View File

@ -2,6 +2,7 @@
data:
title: "Supported platforms"
description: All platforms supported by drift, and how to use them
weight: 8
template: layouts/docs/list
---
@ -24,7 +25,7 @@ This table list all supported drift implementations and on which platforms they
| Implementation | Supported platforms | Notes |
|----------------|---------------------|-------|
| `SqfliteQueryExecutor` from `package:drift_sqflite` | Android, iOS | Uses platform channels, Flutter only, no isolate support, doesn't support `flutter test`. Formerly known as `moor_flutter` |
| `NativeDatabase` from `package:drift/native.dart` | Android, iOS, Windows, Linux, macOS | No further setup is required for Flutter users. For support outside of Flutter, or in `flutter test`, see the [desktop](#desktop) section below. Usage in a [isolate]({{ '../Advanced Features/isolates.md' | pageUrl }}) is recommended. Formerly known as `package:moor/ffi.dart`. |
| `NativeDatabase` from `package:drift/native.dart` | Android, iOS, Windows, Linux, macOS | No further setup is required for Flutter users. For support outside of Flutter, or in `flutter test`, see the [desktop](#desktop) section below. Usage in a [isolate]({{ '../isolates.md' | pageUrl }}) is recommended. Formerly known as `package:moor/ffi.dart`. |
| `WasmDatabase` from `package:drift/wasm.dart` | Web | Works with or without Flutter. A bit of [additional setup]({{ 'web.md' | pageUrl }}) is required. |
| `WebDatabase` from `package:drift/web.dart` | Web | Deprecated in favor of `WasmDatabase`. |
@ -139,11 +140,11 @@ install the dynamic library for `sqlite` next to your application executable.
This example shows how to do that on Linux, by using a custom `sqlite3.so` that we assume
lives next to your application:
{% assign snippets = 'package:drift_docs/snippets/platforms.dart.excerpt.json' | readString | json_decode %}
{% assign snippets = 'package:drift_docs/snippets/platforms/platforms.dart.excerpt.json' | readString | json_decode %}
{% include "blocks/snippet" snippets = snippets %}
Be sure to use drift _after_ you set the platform-specific overrides.
When you use drift in [another isolate]({{ '../Advanced Features/isolates.md' | pageUrl }}),
When you use drift in [another isolate]({{ '../isolates.md' | pageUrl }}),
you'll also need to apply the opening overrides on that background isolate.
You can call them in the isolate's entrypoint before using any drift apis.

6
docs/pages/docs/Platforms/vm.md
View File

@ -112,7 +112,7 @@ The chosen options help reduce binary size by removing features not used by drif
- __SQLITE_DQS=0__: This will make sqlite not accept double-quoted strings (and instead parse them as identifiers). This matches
the behavior of drift and compiled queries
- __SQLITE_THREADSAFE=0__: Since the majority of Flutter apps only use one isolate, thread safety is turned off. Note that you
can still use the [isolate api]({{"../Advanced Features/isolates.md" | pageUrl}}) for background operations. As long as all
can still use the [isolate api]({{"../isolates.md" | pageUrl}}) for background operations. As long as all
database accesses happen from the same thread, there's no problem.
- SQLITE_DEFAULT_MEMSTATUS=0: The `sqlite3_status()` interfaces are not exposed by drift, so there's no point of having them.
- SQLITE_MAX_EXPR_DEPTH=0: Disables maximum depth when sqlite parses expressions, which can make the parser faster.
@ -141,8 +141,8 @@ The `NativeDatabase` includes additional sql functions not available in standard
Note that `NaN`, `-infinity` or `+infinity` are represented as `NULL` in sql.
When enabling the `moor_ffi` module in your [build options]({{ "../Advanced Features/builder_options.md#available-extensions" | pageUrl }}),
the generator will allow you to use those functions in drift files or compiled queries.
When enabling the `moor_ffi` module in your [build options]({{ "../Generation options/index.md#available-extensions" | pageUrl }}),
the generator will allow you to use those functions in drift files or compiled queries.
To use those methods from Dart, you need to import `package:drift/extensions/native.dart`.
You can then use the additional functions like this:

2
docs/pages/docs/Platforms/web.md
View File

@ -382,7 +382,7 @@ you can connect like this:
You can then open a drift database with that connection.
For more information on the `DatabaseConnection` class, see the documentation on
[isolates]({{ "../Advanced Features/isolates.md" | pageUrl }}).
[isolates]({{ "../isolates.md" | pageUrl }}).
A small, but working example is available under [examples/web_worker_example](https://github.com/simolus3/drift/tree/develop/examples/web_worker_example)
in the drift repository.

14
docs/pages/docs/SQL API/drift_files.md
View File

@ -81,7 +81,7 @@ named parameters. To do so, add a `REQUIRED` keyword:
{% include "blocks/snippet" snippets = small name = "q3" %}
Note that this only has an effect when the `named_parameters`
[build option]({{ '../Advanced Features/builder_options.md' | pageUrl }}) is
[build option]({{ '../Generation options/index.md' | pageUrl }}) is
enabled. Further, non-nullable variables are required by default.
### Arrays
@ -138,7 +138,7 @@ CREATE TABLE tasks (
);
```
More information on storing enums is available [in the page on type converters]({{ '../Advanced Features/type_converters.md#using-converters-in-moor' | pageUrl }}).
More information on storing enums is available [in the page on type converters]({{ '../type_converters.md#using-converters-in-moor' | pageUrl }}).
Instead of using an integer mapping enums by their index, you can also store them
by their name. For this, use `ENUMNAME(...)` instead of `ENUM(...)`.
@ -320,7 +320,7 @@ default SQL value (here, `TRUE`) when not explicitly set.
### Type converters
You can import and use [type converters]({{ "../Advanced Features/type_converters.md" | pageUrl }})
You can import and use [type converters]({{ "../type_converters.md" | pageUrl }})
written in Dart in a drift file. Importing a Dart file works with a regular `import` statement.
To apply a type converter on a column definition, you can use the `MAPPED BY` column constraints:
@ -346,9 +346,9 @@ FROM users;
```
More details on type converts in drift files are available
[here]({{ "../Advanced Features/type_converters.md#using-converters-in-moor" | pageUrl }}).
[here]({{ "../type_converters.md#using-converters-in-moor" | pageUrl }}).
When using type converters, we recommend the [`apply_converters_on_variables`]({{ "../Advanced Features/builder_options.md" | pageUrl }})
When using type converters, we recommend the [`apply_converters_on_variables`]({{ "../Generation options/index.md" | pageUrl }})
build option. This will also apply the converter from Dart to SQL, for instance if used on variables: `SELECT * FROM users WHERE preferences = ?`.
With that option, the variable will be inferred to `Preferences` instead of `String`.
@ -380,7 +380,7 @@ CREATE TABLE users (
When using custom row classes defined in another Dart file, you also need to import that file into the file where you define
the database.
For more general information on this feature, please check [this page]({{ '../Advanced Features/custom_row_classes.md' | pageUrl }}).
For more general information on this feature, please check [this page]({{ '../custom_row_classes.md' | pageUrl }}).
Custom row classes can be applied to `SELECT` queries defined a `.drift` file. To use a custom row class, the `WITH` syntax
can be added after the name of the query.
@ -421,7 +421,7 @@ Internally, drift will then generate query code to map the row to an instance of
`UserWithFriends` class.
For a more complete overview of using custom row classes for queries, see
[the section for queries]({{ '../Advanced Features/custom_row_classes.md#queries' | pageUrl }}).
[the section for queries]({{ '../custom_row_classes.md#queries' | pageUrl }}).
### Dart documentation comments

8
docs/pages/docs/SQL API/extensions.md
View File

@ -13,12 +13,12 @@ though, so it makes a pessimistic assumption of using an old sqlite3 version
without any enabled extensions by default.
When using a package like `sqlite3_flutter_libs`, you get the latest sqlite3
version with the json1 and fts5 extensions enabled. You can inform the generator
about this by using [build options]({{ "../Advanced Features/builder_options.md" | pageUrl }}).
about this by using [build options]({{ "../Generation options/index.md" | pageUrl }}).
## json1
To enable the json1 extension in drift files and compiled queries, modify your
[build options]({{ "../Advanced Features/builder_options.md" | pageUrl }}) to include
[build options]({{ "../Generation options/index.md" | pageUrl }}) to include
`json1` in the `sqlite_module` section.
The sqlite extension doesn't require any special tables and works on all text columns. In drift
@ -56,8 +56,8 @@ You can learn more about the json1 extension on [sqlite.org](https://www.sqlite.
## fts5
The fts5 extension provides full-text search capabilities in sqlite tables.
To enable the fts5 extension in drift files and compiled queries, modify the
[build options]({{ "../Advanced Features/builder_options.md" | pageUrl }}) to include
To enable the fts5 extension in drift files and compiled queries, modify the
[build options]({{ "../Generation options/index.md" | pageUrl }}) to include
`fts5` in the `sqlite_module` section.
Just like you'd expect when using sqlite, you can create a fts5 table in a drift file

4
docs/pages/docs/SQL API/index.md
View File

@ -1,7 +1,7 @@
---
data:
title: SQL API
description: Define your database and queries in SQL instead.
title: Verified SQL
description: Define your database and queries in SQL without giving up on type-safety.
weight: 3
template: layouts/docs/list
---

1
docs/pages/docs/community_tools.md
View File

@ -1,6 +1,7 @@
---
data:
title: "Community"
weight: 50
description: Packages contributed by the community
template: layouts/docs/single
---

6
docs/pages/docs/Advanced Features/custom_row_classes.md → docs/pages/docs/custom_row_classes.md
View File

@ -1,12 +1,12 @@
---
data:
title: "Custom row classes"
weight: 6
description: >-
Use your own classes as data classes for drift tables
template: layouts/docs/single
---
For each table declared in Dart or in a drift file, `drift_dev` generates a row class (sometimes also referred to as _data class_)
to hold a full row and a companion class for updates and inserts.
This works well for most cases: Drift knows what columns your table has, and it can generate a simple class for all of that.
@ -167,10 +167,10 @@ For your convenience, drift is using different generation strategies even for qu
an existing row class. It is helpful to enumerate them because they affect the allowed type for
fields in existing types as well.
1. Nested tables: When the [`SELECT table.**` syntax]({{ '../SQL API/drift_files.md#nested-results' | pageUrl }})
1. Nested tables: When the [`SELECT table.**` syntax]({{ 'SQL API/drift_files.md#nested-results' | pageUrl }})
is used in a query, drift will pack columns from `table` into a nested object instead of generating fields
for every column.
2. Nested list results: The [`LIST()` macro]({{ '../SQL API/drift_files.md#list-subqueries' | pageUrl }})
2. Nested list results: The [`LIST()` macro]({{ 'SQL API/drift_files.md#list-subqueries' | pageUrl }})
can be used to expose results of a subquery as a list.
3. Single-table results: When a select statement reads all columns from a table (and no additional columns),
like in `SELECT * FROM table`, drift will use the data class of the table instead of generating a new one.

4
docs/pages/docs/faq.md
View File

@ -1,7 +1,7 @@
---
data:
title: "Frequently asked questions"
weight: 25
path: faq/
template: layouts/docs/single
---
@ -148,7 +148,7 @@ additionally has an api that lets you write some queries in Dart instead of sql.
A difference between these two is that Floor lets you write your own classes and generates mapping code around that.
By default, drift generates most classes for you, which can make it easier to use, but makes the api less flexible in some
instances.
Drift can also be used with [custom row classes]({{ 'Advanced Features/custom_row_classes.md' | pageUrl }}) though.
Drift can also be used with [custom row classes]({{ 'custom_row_classes.md' | pageUrl }}) though.
### firebase
Both the Realtime Database and Cloud Datastore are easy to use persistence libraries that can sync across devices while

9
docs/pages/docs/index.md
View File

@ -26,4 +26,11 @@ return, drift turns rows into objects of your choice.
And much more! Drift validates data before inserting it, so you can get helpful error messages instead of just an
sql error code. Of course, it supports transactions. And DAOs. And efficient batched insert statements. The list goes on.
Check out these in-depth articles to learn about drift and how to use its features.
## Getting started
To get started with drift, follow the [setup guide]({{ 'setup.md' | pageUrl }}).
It explains everything from setting up the dependencies to writing database classes
and generating code.
It also links a few pages intended for developers getting started with drift, so
that you can explore the areas you're most interested in first.

5
docs/pages/docs/Advanced Features/isolates.md → docs/pages/docs/isolates.md
View File

@ -2,15 +2,18 @@
data:
title: Isolates
description: Accessing drift databases on multiple isolates.
weight: 10
template: layouts/docs/single
path: docs/advanced-features/isolates/
---
{% assign snippets = 'package:drift_docs/snippets/isolates.dart.excerpt.json' | readString | json_decode %}
As sqlite3 is a synchronous C library, accessing the database from the main isolate
can cause blocking IO operations that lead to reduced responsiveness of your
application.
To resolve this problem, drift can spawn a long-running isolate to run SQL statements.
When following the recommended [getting started guide]({{ '../setup.md' | pageUrl }})
When following the recommended [getting started guide]({{ 'setup.md' | pageUrl }})
and using `NativeDatabase.createInBackground`, you automatically benefit from an isolate
drift manages for you without needing additional setup.
This page describes when advanced isolate setups are necessary, and how to approach them.

1
docs/pages/docs/testing.md
View File

@ -2,6 +2,7 @@
data:
title: "Testing"
description: Guide on writing unit tests for drift databases
weight: 10
template: layouts/docs/single
---

4
docs/pages/docs/Advanced Features/type_converters.md → docs/pages/docs/type_converters.md
View File

@ -1,9 +1,11 @@
---
data:
title: "Type converters"
weight: 5
description: Store more complex data in columns with type converters
aliases:
- /type_converters
path: /docs/advanced_features/type_converters/
template: layouts/docs/single
---
@ -131,7 +133,7 @@ CREATE TABLE users (
);
```
When using type converters in drift files, we recommend the [`apply_converters_on_variables`]({{ "builder_options.md" | pageUrl }})
When using type converters in drift files, we recommend the [`apply_converters_on_variables`]({{ "Generation options/index.md" | pageUrl }})
build option. This will also apply the converter from Dart to SQL, for instance if used on variables: `SELECT * FROM users WHERE preferences = ?`.
With that option, the variable will be inferred to `Preferences` instead of `String`.

2
docs/pages/docs/upgrading.md
View File

@ -191,7 +191,7 @@ If you opt for a rename, also update your imports and `include:` parameters in d
#### Build configuration
When configuring moor builders for [options]({{ 'Advanced Features/builder_options.md' | pageUrl }}), you have to update your `build.yaml` files to reflect the new builder keys:
When configuring moor builders for [options]({{ 'Generation options/index.md' | pageUrl }}), you have to update your `build.yaml` files to reflect the new builder keys:
| Moor builder key | Drift builder key |
| ------------------------------------------- | ------------------------------ |