mirror of https://github.com/AMT-Cheif/drift.git
Documentation for new moor features
This commit is contained in:
parent
e9cada5e54
commit
22525b24c3
|
@ -0,0 +1,96 @@
|
|||
---
|
||||
title: "Dart tables"
|
||||
description: Further information on Dart tables
|
||||
weight: 150
|
||||
---
|
||||
|
||||
{{% pageinfo %}}
|
||||
__Prefer sql?__: If you prefer, you can also declare tables via `CREATE TABLE` statements.
|
||||
Moor's sql analyzer will generate matching Dart code. [Details]({{< ref "starting_with_sql.md" >}}).
|
||||
{{% /pageinfo %}}
|
||||
|
||||
As shown in the [getting started guide]({{<relref "_index.md">}}), sql tables can be written in Dart:
|
||||
```dart
|
||||
class Todos extends Table {
|
||||
IntColumn get id => integer().autoIncrement()();
|
||||
TextColumn get title => text().withLength(min: 6, max: 32)();
|
||||
TextColumn get content => text().named('body')();
|
||||
IntColumn get category => integer().nullable()();
|
||||
}
|
||||
```
|
||||
|
||||
In this article, we'll cover some advanced features of this syntax.
|
||||
|
||||
## Names
|
||||
|
||||
By default, moor uses the `snake_case` name of the Dart getter in the database. For instance, the
|
||||
table
|
||||
```dart
|
||||
class EnabledCategories extends Table {
|
||||
IntColumn get parentCategory => integer()();
|
||||
// ..
|
||||
}
|
||||
```
|
||||
|
||||
Would be generated as `CREATE TABLE enabled_categories (parent_category INTEGER NOT NULL)`.
|
||||
|
||||
To override the table name, simply override the `tableName` getter. An explicit name for
|
||||
columns can be provided with the `named` method:
|
||||
```dart
|
||||
class EnabledCategories extends Table {
|
||||
String get tableName => 'categories';
|
||||
|
||||
IntColumn get parentCategory => integer().named('parent')();
|
||||
}
|
||||
```
|
||||
|
||||
The updated class would be generated as `CREATE TABLE categories (parent INTEGER NOT NULL)`.
|
||||
|
||||
To update the name of a column when serializing data to json, annotate the getter with
|
||||
[`@JsonKey`](https://pub.dev/documentation/moor/latest/moor_web/JsonKey-class.html).
|
||||
|
||||
## Nullability
|
||||
|
||||
By default, columns may not contain null values. When you forgot to set a value in an insert,
|
||||
an exception will be thrown. When using sql, moor also warns about that at compile time.
|
||||
|
||||
If you do want to make a column nullable, just use `nullable()`:
|
||||
```dart
|
||||
class Items {
|
||||
IntColumn get category => integer().nullable();
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## 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`:
|
||||
|
||||
```dart
|
||||
class Preferences extends Table {
|
||||
TextColumn get name => integer().autoIncrement()();
|
||||
BoolColumn get enabled => boolean().withDefault(const Constant(false))();
|
||||
}
|
||||
```
|
||||
|
||||
When you later use `into(preferences).insert(PreferencesCompanion.forInsert(name: 'foo'));`, the new
|
||||
row will have its `enabled` column set to false (and not to null, as it normally would).
|
||||
|
||||
Of course, constants can only be used for static values. But what if you want to generate a dynamic
|
||||
default value for each column? For that, you can use `clientDefault`. It takes a function returning
|
||||
the desired default value. The function will be called for each insert. For instance, here's an
|
||||
example generating a random Uuid using the `uuid` package:
|
||||
```dart
|
||||
final _uuid = Uuid();
|
||||
|
||||
class Users extends Table {
|
||||
TextColumn get id => text().clientDefault(() => _uuid.v4())();
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Don't know when to use which? Prefer to use `withDefault` when the default value is constant, or something
|
||||
simple like `currentDate`. For more complicated values, like a randomly generated id, you need to use
|
||||
`clientDefault`. Internally, `withDefault` writes the default value into the `CREATE TABLE` statement. This
|
||||
can be more efficient, but doesn't suppport dynamic values.
|
|
@ -78,6 +78,13 @@ with @ or $. The compiler will attempt to infer the variable's type by
|
|||
looking at its context. This lets moor generate typesafe apis for your
|
||||
queries, the variables will be written as parameters to your method.
|
||||
|
||||
When it's ambigous, the analyzer might be unable to resolve the type of
|
||||
a variable. For those scenarios, you can also denote the explicit type
|
||||
of a variable:
|
||||
```sql
|
||||
myQuery(:variable AS TEXT): SELECT :variable;
|
||||
```
|
||||
|
||||
### Arrays
|
||||
If you want to check whether a value is in an array of values, you can
|
||||
use `IN ?`. That's not valid sql, but moor will desugar that at runtime. So, for this query:
|
||||
|
|
|
@ -25,13 +25,13 @@ abstract class DataClass {
|
|||
/// Converts this object into a representation that can be encoded with
|
||||
/// [json]. The [serializer] can be used to configure how individual values
|
||||
/// will be encoded. By default, [MoorRuntimeOptions.defaultSerializer] will
|
||||
/// be used. See [ValueSerializer.defaults()] for details.
|
||||
/// be used. See [ValueSerializer.defaults] for details.
|
||||
Map<String, dynamic> toJson({ValueSerializer serializer});
|
||||
|
||||
/// Converts this object into a json representation. The [serializer] can be
|
||||
/// used to configure how individual values will be encoded. By default,
|
||||
/// [MoorRuntimeOptions.defaultSerializer] will be used. See
|
||||
/// [ValueSerializer.defaults()] for details.
|
||||
/// [ValueSerializer.defaults] for details.
|
||||
String toJsonString({ValueSerializer serializer}) {
|
||||
return json.encode(toJson(serializer: serializer));
|
||||
}
|
||||
|
@ -87,8 +87,13 @@ abstract class ValueSerializer {
|
|||
/// Constant super-constructor to allow constant child classes.
|
||||
const ValueSerializer();
|
||||
|
||||
/// The default serializer encodes date times as a unix-timestamp in
|
||||
/// milliseconds.
|
||||
/// The builtin default serializer.
|
||||
///
|
||||
/// This serializer won't transform numbers or strings. Date times will be
|
||||
/// encoded as a unix-timestamp.
|
||||
///
|
||||
/// To override the default serializer moor uses, you can change the
|
||||
/// [MoorRuntimeOptions.defaultSerializer] field.
|
||||
const factory ValueSerializer.defaults() = _DefaultValueSerializer;
|
||||
|
||||
/// Converts the [value] to something that can be passed to
|
||||
|
|
Loading…
Reference in New Issue