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
|
looking at its context. This lets moor generate typesafe apis for your
|
||||||
queries, the variables will be written as parameters to your method.
|
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
|
### Arrays
|
||||||
If you want to check whether a value is in an array of values, you can
|
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:
|
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
|
/// Converts this object into a representation that can be encoded with
|
||||||
/// [json]. The [serializer] can be used to configure how individual values
|
/// [json]. The [serializer] can be used to configure how individual values
|
||||||
/// will be encoded. By default, [MoorRuntimeOptions.defaultSerializer] will
|
/// 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});
|
Map<String, dynamic> toJson({ValueSerializer serializer});
|
||||||
|
|
||||||
/// Converts this object into a json representation. The [serializer] can be
|
/// Converts this object into a json representation. The [serializer] can be
|
||||||
/// used to configure how individual values will be encoded. By default,
|
/// used to configure how individual values will be encoded. By default,
|
||||||
/// [MoorRuntimeOptions.defaultSerializer] will be used. See
|
/// [MoorRuntimeOptions.defaultSerializer] will be used. See
|
||||||
/// [ValueSerializer.defaults()] for details.
|
/// [ValueSerializer.defaults] for details.
|
||||||
String toJsonString({ValueSerializer serializer}) {
|
String toJsonString({ValueSerializer serializer}) {
|
||||||
return json.encode(toJson(serializer: serializer));
|
return json.encode(toJson(serializer: serializer));
|
||||||
}
|
}
|
||||||
|
@ -87,8 +87,13 @@ abstract class ValueSerializer {
|
||||||
/// Constant super-constructor to allow constant child classes.
|
/// Constant super-constructor to allow constant child classes.
|
||||||
const ValueSerializer();
|
const ValueSerializer();
|
||||||
|
|
||||||
/// The default serializer encodes date times as a unix-timestamp in
|
/// The builtin default serializer.
|
||||||
/// milliseconds.
|
///
|
||||||
|
/// 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;
|
const factory ValueSerializer.defaults() = _DefaultValueSerializer;
|
||||||
|
|
||||||
/// Converts the [value] to something that can be passed to
|
/// Converts the [value] to something that can be passed to
|
||||||
|
|
Loading…
Reference in New Issue