mirror of https://github.com/AMT-Cheif/drift.git
Move the existing documentation and more to docsy
This commit is contained in:
Simon Binder
parent
03eaae4a60
commit
b2a06cbe1c
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
title: "Advanced features"
|
||||
description: Learn about some advanced features of moor
|
||||
---
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
title: "DAOs"
|
||||
description: Keep your database code modular with DAOs
|
||||
aliases:
|
||||
- /daos/
|
||||
---
|
||||
|
||||
When you have a lot of queries, putting them all into one class might become
|
||||
tedious. You can avoid this by extracting some queries into classes that are
|
||||
available from your main database class. Consider the following code:
|
||||
```dart
|
||||
part 'todos_dao.g.dart';
|
||||
|
||||
// the _TodosDaoMixin will be created by moor. It contains all the necessary
|
||||
// fields for the tables. The <MyDatabase> type annotation is the database class
|
||||
// that should use this dao.
|
||||
@UseDao(tables: [Todos])
|
||||
class TodosDao extends DatabaseAccessor<MyDatabase> with _$TodosDaoMixin {
|
||||
// this constructor is required so that the main database can create an instance
|
||||
// of this object.
|
||||
TodosDao(MyDatabase db) : super(db);
|
||||
|
||||
Stream<List<TodoEntry>> todosInCategory(Category category) {
|
||||
if (category == null) {
|
||||
return (select(todos)..where((t) => isNull(t.category))).watch();
|
||||
} else {
|
||||
return (select(todos)..where((t) => t.category.equals(category.id)))
|
||||
.watch();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
If we now change the annotation on the `MyDatabase` class to `@UseMoor(tables: [Todos, Categories], daos: [TodosDao])`
|
||||
and re-run the code generation, a generated getter `todosDao` can be used to access the instance of that dao.
|
||||
|
|
@ -0,0 +1,116 @@
|
|||
---
|
||||
title: "Joins"
|
||||
description: >
|
||||
Use joins to write queries that read from more than one table
|
||||
aliases:
|
||||
- /queries/joins
|
||||
---
|
||||
|
||||
Moor supports sql joins to write queries that operate on more than one table. To use that feature, start
|
||||
a select regular select statement with `select(table)` and then add a list of joins using `.join()`. For
|
||||
inner and left outer joins, a `ON` expression needs to be specified. Here's an example using the tables
|
||||
defined in the [example]({{< ref "docs/Getting Started/_index.md" >}}).
|
||||
|
||||
```dart
|
||||
// we define a data class to contain both a todo entry and the associated category
|
||||
class EntryWithCategory {
|
||||
EntryWithCategory(this.entry, this.category);
|
||||
|
||||
final TodoEntry entry;
|
||||
final Category category;
|
||||
}
|
||||
|
||||
// in the database class, we can then load the category for each entry
|
||||
Stream<List<EntryWithCategory>> entriesWithCategory() {
|
||||
final query = select(todos).join([
|
||||
leftOuterJoin(categories, categories.id.equalsExp(todos.category)),
|
||||
]);
|
||||
|
||||
// see next section on how to parse the result
|
||||
}
|
||||
```
|
||||
|
||||
## Parsing results
|
||||
Calling `get()` or `watch` on a select statement with join returns a `Future` or `Stream` of
|
||||
`List<TypedResult>` respectively. Each `TypedResult` represents a row from which data can be
|
||||
read. It contains a `rawData` getter to obtain the raw columns. But more importantly, the
|
||||
`readTable` method can be used to read a data class from a table.
|
||||
|
||||
In the example query above, we can read the todo entry and the category from each row like this:
|
||||
```dart
|
||||
return query.watch().map((rows) {
|
||||
return rows.map((row) {
|
||||
return EntryWithCategory(
|
||||
row.readTable(todos),
|
||||
row.readTable(categories),
|
||||
);
|
||||
}).toList();
|
||||
});
|
||||
```
|
||||
|
||||
_Note_: `readTable` returns `null` when an entity is not present in the row. For instance, todo entries
|
||||
might not be in any category. If we a row without a category, `row.readTable(categories)` would return `null`.
|
||||
## Aliases
|
||||
Sometimes, a query references a table more than once. Consider the following example to store saved routes for a
|
||||
navigation system:
|
||||
```dart
|
||||
class GeoPoints extends Table {
|
||||
IntColumn get id => integer().autoIncrement()();
|
||||
TextColumn get name => text()();
|
||||
TextColumn get latitude => text()();
|
||||
TextColumn get longitude => text()();
|
||||
}
|
||||
|
||||
class Routes extends Table {
|
||||
|
||||
IntColumn get id => integer().autoIncrement()();
|
||||
TextColumn get name => text()();
|
||||
|
||||
// contains the id for the start and destination geopoint.
|
||||
IntColumn get start => integer()();
|
||||
IntColumn get destination => integer()();
|
||||
}
|
||||
```
|
||||
|
||||
Now, let's say we wanted to also load the start and destination `GeoPoint` object for each route. We'd have to use
|
||||
a join on the `geo-points` table twice: For the start and destination point. To express that in a query, aliases
|
||||
can be used:
|
||||
```dart
|
||||
class RouteWithPoints {
|
||||
final Route route;
|
||||
final GeoPoint start;
|
||||
final GeoPoint destination;
|
||||
|
||||
RouteWithPoints({this.route, this.start, this.destination});
|
||||
}
|
||||
|
||||
// inside the database class:
|
||||
Future<List<RouteWithPoints>> loadRoutes() async {
|
||||
// create aliases for the geoPoints table so that we can reference it twice
|
||||
final start = alias(geoPoints, 's');
|
||||
final destination = alias(geoPoints, 'd');
|
||||
|
||||
final rows = await select(routes).join([
|
||||
innerJoin(start, start.id.equalsExp(routes.start)),
|
||||
innerJoin(destination, destination.id.equalsExp(routes.destination)),
|
||||
]).get();
|
||||
|
||||
return rows.map((resultRow) {
|
||||
return RouteWithPoints(
|
||||
route: resultRow.readTable(routes),
|
||||
start: resultRow.readTable(start),
|
||||
destination: resultRow.readTable(destination),
|
||||
);
|
||||
}).toList();
|
||||
}
|
||||
```
|
||||
The generated statement then looks like this:
|
||||
```sql
|
||||
SELECT
|
||||
routes.id, routes.name, routes.start, routes.destination,
|
||||
s.id, s.name, s.latitude, s.longitude,
|
||||
d.id, d.name, d.latitude, d.longitude
|
||||
FROM routes
|
||||
INNER JOIN geo_points s ON s.id = routes.start
|
||||
INNER JOIN geo_points d ON d.id = routes.destination
|
||||
```
|
||||
|
|
@ -0,0 +1,83 @@
|
|||
---
|
||||
title: "Migrations"
|
||||
description: >
|
||||
Define what happens when your database gets created or updated
|
||||
aliases:
|
||||
- /migrations
|
||||
---
|
||||
|
||||
Moor provides a migration API that can be used to gradually apply schema changes after bumping
|
||||
the `schemaVersion` getter inside the `Database` class. To use it, override the `migration`
|
||||
getter. Here's an example: Let's say you wanted to add a due date to your todo entries:
|
||||
```dart
|
||||
class Todos extends Table {
|
||||
IntColumn get id => integer().autoIncrement()();
|
||||
TextColumn get title => text().withLength(min: 6, max: 10)();
|
||||
TextColumn get content => text().named('body')();
|
||||
IntColumn get category => integer().nullable()();
|
||||
DateTimeColumn get dueDate => dateTime().nullable()(); // new, added column
|
||||
}
|
||||
```
|
||||
We can now change the `database` class like this:
|
||||
```dart
|
||||
@override
|
||||
int get schemaVersion => 2; // bump because the tables have changed
|
||||
|
||||
@override
|
||||
MigrationStrategy get migration => MigrationStrategy(
|
||||
onCreate: (Migrator m) {
|
||||
return m.createAllTables();
|
||||
},
|
||||
onUpgrade: (Migrator m, int from, int to) async {
|
||||
if (from == 1) {
|
||||
// we added the dueDate property in the change from version 1
|
||||
await m.addColumn(todos, todos.dueDate);
|
||||
}
|
||||
}
|
||||
);
|
||||
|
||||
// rest of class can stay the same
|
||||
```
|
||||
You can also add individual tables or drop them - see the reference of [Migrator](https://pub.dev/documentation/moor/latest/moor/Migrator-class.html)
|
||||
for all the available options. You can't use the high-level query API in migrations - calling `select` or similar
|
||||
methods will throw.
|
||||
|
||||
`sqlite` can feel a bit limiting when it comes to migrations - there only are methods to create tables and columns.
|
||||
Existing columns can't be altered or removed. A workaround is described [here](https://stackoverflow.com/a/805508), it
|
||||
can be used together with [`issueCustomQuery`](https://pub.dev/documentation/moor/latest/moor/Migrator/issueCustomQuery.html)
|
||||
to run the statements.
|
||||
|
||||
## Post-migration callbacks
|
||||
Starting from moor 1.5, you can use the `beforeOpen` parameter in the `MigrationStrategy` which will be called after
|
||||
migrations, but after any other queries are run. You could use it to populate data after the database has been created:
|
||||
```dart
|
||||
beforeOpen: (db, details) async {
|
||||
if (details.wasCreated) {
|
||||
final workId = await db.into(categories).insert(Category(description: 'Work'));
|
||||
|
||||
await db.into(todos).insert(TodoEntry(
|
||||
content: 'A first todo entry',
|
||||
category: null,
|
||||
targetDate: DateTime.now(),
|
||||
));
|
||||
|
||||
await db.into(todos).insert(
|
||||
TodoEntry(
|
||||
content: 'Rework persistence code',
|
||||
category: workId,
|
||||
targetDate: DateTime.now().add(const Duration(days: 4)),
|
||||
));
|
||||
}
|
||||
},
|
||||
```
|
||||
You could also activate pragma statements that you need:
|
||||
```dart
|
||||
beforeOpen: (db, details) async {
|
||||
if (details.wasCreated) {
|
||||
// ...
|
||||
}
|
||||
await db.customStatement('PRAGMA foreign_keys = ON');
|
||||
}
|
||||
```
|
||||
It is important that you run these queries on `db` explicitly. Failing to do so causes a deadlock which prevents the
|
||||
database from being opened.
|
||||
|
|
@ -1,17 +0,0 @@
|
|||
|
||||
---
|
||||
title: "Examples"
|
||||
linkTitle: "Examples"
|
||||
weight: 3
|
||||
date: 2017-01-05
|
||||
description: >
|
||||
See your project in action!
|
||||
---
|
||||
|
||||
{{% pageinfo %}}
|
||||
This is a placeholder page that shows you how to use this template site.
|
||||
{{% /pageinfo %}}
|
||||
|
||||
Do you have any example **applications** or **code** for your users in your repo or elsewhere? Link to your examples here.
|
||||
|
||||
|
||||
|
|
@ -3,34 +3,89 @@ title: "Getting Started"
|
|||
linkTitle: "Getting Started"
|
||||
weight: 2
|
||||
description: >
|
||||
What does your user need to know to try your project?
|
||||
Simple guide to get a moor project up and running
|
||||
|
||||
aliases:
|
||||
- /getting-started/ # Used to have this url
|
||||
---
|
||||
|
||||
{{% pageinfo %}}
|
||||
This is a placeholder page that shows you how to use this template site.
|
||||
{{% /pageinfo %}}
|
||||
_Note:_ If you prefer a tutorial video, Reso Coder has made a detailed video explaining
|
||||
how to get started. You can watch it [here](https://youtu.be/zpWsedYMczM).
|
||||
|
||||
Information in this section helps your user try your project themselves.
|
||||
|
||||
* What do your users need to do to start using your project? This could include downloading/installation instructions, including any prerequisites or system requirements.
|
||||
## Adding the dependency
|
||||
First, let's add moor to your project's `pubspec.yaml`.
|
||||
At the moment, the current version of `moor_flutter` is [](https://pub.dartlang.org/packages/moor_flutter) and the current version of `moor_generator` is [](https://pub.dartlang.org/packages/moor_generator)
|
||||
|
||||
* Introductory “Hello World” example, if appropriate. More complex tutorials should live in the Tutorials section.
|
||||
```yaml
|
||||
dependencies:
|
||||
moor_flutter: # use the latest version
|
||||
|
||||
Consider using the headings below for your getting started page. You can delete any that are not applicable to your project.
|
||||
dev_dependencies:
|
||||
moor_generator: # use the latest version
|
||||
build_runner:
|
||||
```
|
||||
We're going to use the `moor_flutter` library to specify tables and access the database. The
|
||||
`moor_generator` library will take care of generating the necessary code so the
|
||||
library knows what your table structure looks like.
|
||||
|
||||
## Prerequisites
|
||||
### Declaring tables
|
||||
Using moor, you can model the structure of your tables with simple dart code:
|
||||
```dart
|
||||
import 'package:moor_flutter/moor_flutter.dart';
|
||||
|
||||
Are there any system requirements for using your project? What languages are supported (if any)? Do users need to already have any software or tools installed?
|
||||
// assuming that your file is called filename.dart. This will give an error at first,
|
||||
// but it's needed for moor to know about the generated code
|
||||
part 'filename.g.dart';
|
||||
|
||||
## Installation
|
||||
// this will generate a table called "todos" for us. The rows of that table will
|
||||
// be represented by a class called "Todo".
|
||||
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()();
|
||||
}
|
||||
|
||||
Where can your user find your project code? How can they install it (binaries, installable package, build from source)? Are there multiple options/versions they can install and how should they choose the right one for them?
|
||||
// This will make moor generate a class called "Category" to represent a row in this table.
|
||||
// By default, "Categorie" would have been used because it only strips away the trailing "s"
|
||||
// in the table name.
|
||||
@DataClassName("Category")
|
||||
class Categories extends Table {
|
||||
|
||||
IntColumn get id => integer().autoIncrement()();
|
||||
TextColumn get description => text()();
|
||||
}
|
||||
|
||||
## Setup
|
||||
// this annotation tells moor to prepare a database class that uses both of the
|
||||
// tables we just defined. We'll see how to use that database class in a moment.
|
||||
@UseMoor(tables: [Todos, Categories])
|
||||
class MyDatabase {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
Is there any initial setup users need to do after installation to try your project?
|
||||
__⚠️ Note:__ The column definitions, the table name and the primary key must be known at
|
||||
compile time. For column definitions and the primary key, the function must use the `=>`
|
||||
operator and can't contain anything more than what's included in the documentation and the
|
||||
examples. Otherwise, the generator won't be able to know what's going on.
|
||||
|
||||
## Try it out!
|
||||
|
||||
Can your users test their installation, for example by running a commmand or deploying a Hello World example?
|
||||
## Generating the code
|
||||
Moor integrates with Dart's `build` system, so you can generate all the code needed with
|
||||
`flutter packages pub run build_runner build`. If you want to continuously rebuild the generated code
|
||||
whever you change your code, run `flutter packages pub run build_runner watch` instead.
|
||||
After running either command once, the moor generator will have created a class for your
|
||||
database and data classes for your entities. To use it, change the `MyDatabase` class as
|
||||
follows:
|
||||
```dart
|
||||
@UseMoor(tables: [Todos, Categories])
|
||||
class MyDatabase extends _$MyDatabase {
|
||||
// we tell the database where to store the data with this constructor
|
||||
MyDatabase() : super(FlutterQueryExecutor.inDatabaseFolder(path: 'db.sqlite'));
|
||||
|
||||
// you should bump this number whenever you change or add a table definition. Migrations
|
||||
// are covered later in this readme.
|
||||
@override
|
||||
int get schemaVersion => 1;
|
||||
}
|
||||
```
|
||||
|
|
@ -1,239 +0,0 @@
|
|||
---
|
||||
title: "Example Page"
|
||||
linkTitle: "Example Page"
|
||||
date: 2017-01-05
|
||||
description: >
|
||||
A short lead descripton about this content page. It can be **bold** or _italic_ and can be split over multiple paragraphs.
|
||||
---
|
||||
|
||||
{{% pageinfo %}}
|
||||
This is a placeholder page. Replace it with your own content.
|
||||
{{% /pageinfo %}}
|
||||
|
||||
|
||||
Text can be **bold**, _italic_, or ~~strikethrough~~. [Links](https://gohugo.io) should be blue with no underlines (unless hovered over).
|
||||
|
||||
There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.
|
||||
|
||||
90's four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps **kale chips**.
|
||||
|
||||
> There should be no margin above this first sentence.
|
||||
>
|
||||
> Blockquotes should be a lighter gray with a border along the left side in the secondary color.
|
||||
>
|
||||
> There should be no margin below this final sentence.
|
||||
|
||||
## First Header 2
|
||||
|
||||
This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier **craft beer**. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven't heard of them copper mug, crucifix green juice vape *single-origin coffee* brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!
|
||||
|
||||
Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.
|
||||
|
||||
On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.
|
||||
|
||||
Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. **I love this life we live in**.
|
||||
|
||||
|
||||
## Second Header 2
|
||||
|
||||
> This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.
|
||||
|
||||
### Header 3
|
||||
|
||||
```
|
||||
This is a code block following a header.
|
||||
```
|
||||
|
||||
Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.
|
||||
|
||||
#### Header 4
|
||||
|
||||
* This is an unordered list following a header.
|
||||
* This is an unordered list following a header.
|
||||
* This is an unordered list following a header.
|
||||
|
||||
##### Header 5
|
||||
|
||||
1. This is an ordered list following a header.
|
||||
2. This is an ordered list following a header.
|
||||
3. This is an ordered list following a header.
|
||||
|
||||
###### Header 6
|
||||
|
||||
| What | Follows |
|
||||
|-----------|-----------------|
|
||||
| A table | A header |
|
||||
| A table | A header |
|
||||
| A table | A header |
|
||||
|
||||
----------------
|
||||
|
||||
There's a horizontal rule above and below this.
|
||||
|
||||
----------------
|
||||
|
||||
Here is an unordered list:
|
||||
|
||||
* Liverpool F.C.
|
||||
* Chelsea F.C.
|
||||
* Manchester United F.C.
|
||||
|
||||
And an ordered list:
|
||||
|
||||
1. Michael Brecker
|
||||
2. Seamus Blake
|
||||
3. Branford Marsalis
|
||||
|
||||
And an unordered task list:
|
||||
|
||||
- [x] Create a Hugo theme
|
||||
- [x] Add task lists to it
|
||||
- [ ] Take a vacation
|
||||
|
||||
And a "mixed" task list:
|
||||
|
||||
- [ ] Pack bags
|
||||
- ?
|
||||
- [ ] Travel!
|
||||
|
||||
And a nested list:
|
||||
|
||||
* Jackson 5
|
||||
* Michael
|
||||
* Tito
|
||||
* Jackie
|
||||
* Marlon
|
||||
* Jermaine
|
||||
* TMNT
|
||||
* Leonardo
|
||||
* Michelangelo
|
||||
* Donatello
|
||||
* Raphael
|
||||
|
||||
Definition lists can be used with Markdown syntax. Definition headers are bold.
|
||||
|
||||
Name
|
||||
: Godzilla
|
||||
|
||||
Born
|
||||
: 1952
|
||||
|
||||
Birthplace
|
||||
: Japan
|
||||
|
||||
Color
|
||||
: Green
|
||||
|
||||
|
||||
----------------
|
||||
|
||||
Tables should have bold headings and alternating shaded rows.
|
||||
|
||||
| Artist | Album | Year |
|
||||
|-------------------|-----------------|------|
|
||||
| Michael Jackson | Thriller | 1982 |
|
||||
| Prince | Purple Rain | 1984 |
|
||||
| Beastie Boys | License to Ill | 1986 |
|
||||
|
||||
If a table is too wide, it should scroll horizontally.
|
||||
|
||||
| Artist | Album | Year | Label | Awards | Songs |
|
||||
|-------------------|-----------------|------|-------------|----------|-----------|
|
||||
| Michael Jackson | Thriller | 1982 | Epic Records | Grammy Award for Album of the Year, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Selling Album, Grammy Award for Best Engineered Album, Non-Classical | Wanna Be Startin' Somethin', Baby Be Mine, The Girl Is Mine, Thriller, Beat It, Billie Jean, Human Nature, P.Y.T. (Pretty Young Thing), The Lady in My Life |
|
||||
| Prince | Purple Rain | 1984 | Warner Brothers Records | Grammy Award for Best Score Soundtrack for Visual Media, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Soundtrack/Cast Recording, Grammy Award for Best Rock Performance by a Duo or Group with Vocal | Let's Go Crazy, Take Me With U, The Beautiful Ones, Computer Blue, Darling Nikki, When Doves Cry, I Would Die 4 U, Baby I'm a Star, Purple Rain |
|
||||
| Beastie Boys | License to Ill | 1986 | Mercury Records | noawardsbutthistablecelliswide | Rhymin & Stealin, The New Style, She's Crafty, Posse in Effect, Slow Ride, Girls, (You Gotta) Fight for Your Right, No Sleep Till Brooklyn, Paul Revere, Hold It Now, Hit It, Brass Monkey, Slow and Low, Time to Get Ill |
|
||||
|
||||
----------------
|
||||
|
||||
Code snippets like `var foo = "bar";` can be shown inline.
|
||||
|
||||
Also, `this should vertically align` ~~`with this`~~ ~~and this~~.
|
||||
|
||||
Code can also be shown in a block element.
|
||||
|
||||
```
|
||||
foo := "bar";
|
||||
bar := "foo";
|
||||
```
|
||||
|
||||
Code can also use syntax highlighting.
|
||||
|
||||
```go
|
||||
func main() {
|
||||
input := `var foo = "bar";`
|
||||
|
||||
lexer := lexers.Get("javascript")
|
||||
iterator, _ := lexer.Tokenise(nil, input)
|
||||
style := styles.Get("github")
|
||||
formatter := html.New(html.WithLineNumbers())
|
||||
|
||||
var buff bytes.Buffer
|
||||
formatter.Format(&buff, style, iterator)
|
||||
|
||||
fmt.Println(buff.String())
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
|
||||
```
|
||||
|
||||
Inline code inside table cells should still be distinguishable.
|
||||
|
||||
| Language | Code |
|
||||
|-------------|--------------------|
|
||||
| Javascript | `var foo = "bar";` |
|
||||
| Ruby | `foo = "bar"{` |
|
||||
|
||||
----------------
|
||||
|
||||
Small images should be shown at their actual size.
|
||||
|
||||
|
||||
|
||||
Large images should always scale down and fit in the content container.
|
||||
|
||||
|
||||
|
||||
_The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA._
|
||||
|
||||
|
||||
## Components
|
||||
|
||||
### Alerts
|
||||
|
||||
{{< alert >}}This is an alert.{{< /alert >}}
|
||||
{{< alert title="Note" >}}This is an alert with a title.{{< /alert >}}
|
||||
{{% alert title="Note" %}}This is an alert with a title and **Markdown**.{{% /alert %}}
|
||||
{{< alert color="success" >}}This is a successful alert.{{< /alert >}}
|
||||
{{< alert color="warning" >}}This is a warning.{{< /alert >}}
|
||||
{{< alert color="warning" title="Warning" >}}This is a warning with a title.{{< /alert >}}
|
||||
|
||||
|
||||
## Another Heading
|
||||
|
||||
Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.
|
||||
|
||||
### This Document
|
||||
|
||||
Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam *eripitur*? Sitim noceat signa *probat quidem*. Sua longis *fugatis* quidem genae.
|
||||
|
||||
|
||||
### Pixel Count
|
||||
|
||||
Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.
|
||||
|
||||
### Contact Info
|
||||
|
||||
Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.
|
||||
|
||||
|
||||
### External Links
|
||||
|
||||
Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.
|
||||
|
||||
|
||||
|
||||
```
|
||||
This is the final element on the page and there should be no margin below this.
|
||||
```
|
||||
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
title: "Writing queries"
|
||||
linkTitle: "Writing queries"
|
||||
description: >
|
||||
Learn how to write database queries in pure Dart with moor
|
||||
aliases:
|
||||
- /queries/
|
||||
---
|
||||
|
||||
{{% pageinfo %}}
|
||||
__Note__: This assumes that you already completed [the setup]({{< ref "_index.md" >}}).
|
||||
{{% /pageinfo %}}
|
||||
|
||||
For each table you've specified in the `@UseMoor` annotation on your database class,
|
||||
a corresponding getter for a table will be generated. That getter can be used to
|
||||
run statements:
|
||||
```dart
|
||||
// inside the database class, the `todos` getter has been created by moor.
|
||||
@UseMoor(tables: [Todos, Categories])
|
||||
class MyDatabase extends _$MyDatabase {
|
||||
|
||||
// the schemaVersion getter and the constructor from the previous page
|
||||
// have been omitted.
|
||||
|
||||
// loads all todo entries
|
||||
Future<List<Todo>> get allTodoEntries => select(todos).get();
|
||||
|
||||
// watches all todo entries in a given category. The stream will automatically
|
||||
// emit new items whenever the underlying data changes.
|
||||
Stream<List<TodoEntry>> watchEntriesInCategory(Category c) {
|
||||
return (select(todos)..where((t) => t.category.equals(c.id))).watch();
|
||||
}
|
||||
}
|
||||
```
|
||||
## Select statements
|
||||
You can create `select` statements by starting them with `select(tableName)`, where the
|
||||
table name
|
||||
is a field generated for you by moor. Each table used in a database will have a matching field
|
||||
to run queries against. Any query can be run once with `get()` or be turned into an auto-updating
|
||||
stream using `watch()`.
|
||||
### Where
|
||||
You can apply filters to a query by calling `where()`. The where method takes a function that
|
||||
should map the given table to an `Expression` of boolean. A common way to create such expression
|
||||
is by using `equals` on expressions. Integer columns can also be compared with `isBiggerThan`
|
||||
and `isSmallerThan`. You can compose expressions using `and(a, b), or(a, b)` and `not(a)`.
|
||||
### Limit
|
||||
You can limit the amount of results returned by calling `limit` on queries. The method accepts
|
||||
the amount of rows to return and an optional offset.
|
||||
### Ordering
|
||||
You can use the `orderBy` method on the select statement. It expects a list of functions that extract the individual
|
||||
ordering terms from the table.
|
||||
```dart
|
||||
Future<List<TodoEntry>> sortEntriesAlphabetically() {
|
||||
return (select(todos)..orderBy([(t) => OrderingTerm(expression: t.title)])).get();
|
||||
}
|
||||
```
|
||||
You can also reverse the order by setting the `mode` property of the `OrderingTerm` to
|
||||
`OrderingMode.desc`.
|
||||
## Updates and deletes
|
||||
You can use the generated classes to update individual fields of any row:
|
||||
```dart
|
||||
Future moveImportantTasksIntoCategory(Category target) {
|
||||
// for updates, we use the "companion" version of a generated class. This wraps the
|
||||
// fields in a "Value" type which can be set to be absent using "Value.absent()". This
|
||||
// allows us to separate between "SET category = NULL" (`category: Value(null)`) and not
|
||||
// updating the category at all: `category: Value.absent()`.
|
||||
return (update(todos)
|
||||
..where((t) => t.title.like('%Important%'))
|
||||
).write(TodosCompanion(
|
||||
category: Value(target.id),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
Future update(TodoEntry entry) {
|
||||
// using replace will update all fields from the entry that are not marked as a primary key.
|
||||
// it will also make sure that only the entry with the same primary key will be updated.
|
||||
// Here, this means that the row that has the same id as entry will be updated to reflect
|
||||
// the entry's title, content and category. As it set's its where clause automatically, it
|
||||
// can not be used together with where.
|
||||
return update(todos).replace(entry);
|
||||
}
|
||||
|
||||
Future feelingLazy() {
|
||||
// delete the oldest nine tasks
|
||||
return (delete(todos)..where((t) => t.id.isSmallerThanValue(10))).go();
|
||||
}
|
||||
```
|
||||
__⚠️ Caution:__ If you don't explicitly add a `where` clause on updates or deletes,
|
||||
the statement will affect all rows in the table!
|
||||
|
||||
## Inserts
|
||||
You can very easily insert any valid object into tables. As some values can be absent
|
||||
(like default values that we don't have to set explicitly), we again use the
|
||||
companion version.
|
||||
```dart
|
||||
// returns the generated id
|
||||
Future<int> addTodoEntry(TodosCompanion entry) {
|
||||
return into(todos).insert(entry);
|
||||
}
|
||||
```
|
||||
All row classes generated will have a constructor that can be used to create objects:
|
||||
```dart
|
||||
addTodoEntry(
|
||||
TodosCompanion(
|
||||
title: Value('Important task'),
|
||||
content: Value('Refactor persistence code'),
|
||||
),
|
||||
);
|
||||
```
|
||||
If a column is nullable or has a default value (this includes auto-increments), the field
|
||||
can be omitted. All other fields must be set and non-null. The `insert` method will throw
|
||||
otherwise.
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
---
|
||||
title: "Other engines"
|
||||
weight: 100
|
||||
description: Use moor on the web or other platforms
|
||||
---
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
title: Encryption
|
||||
description: Use moor on encrypted databases
|
||||
---
|
||||
|
||||
{{% alert title="Security notice" color="warning" %}}
|
||||
> This feature uses an external library for all the encryption work. Importing
|
||||
that library as described here would always pull the latest version from git
|
||||
when running `pub upgrade`. If you want to be sure that you're using a safe version
|
||||
that you can trust, consider pulling `sqflite_sqlcipher` and `encrypted_moor` once
|
||||
and then include your local version via a path in the pubspec.
|
||||
{{% /alert %}}
|
||||
|
||||
Starting from 1.7, we have a version of moor that can work with encrypted databases by using the
|
||||
[sqflite_sqlcipher](https://github.com/davidmartos96/sqflite_sqlcipher) library
|
||||
by [@davidmartos96](https://github.com/davidmartos96). To use it, you need to
|
||||
remove the dependency on `moor_flutter` from your `pubspec.yaml` and replace it
|
||||
with this:
|
||||
```yaml
|
||||
dependencies:
|
||||
moor: "$latest version"
|
||||
encrypted_moor:
|
||||
git:
|
||||
url: https://github.com/simolus3/moor.git
|
||||
path: extras/encryption
|
||||
```
|
||||
|
||||
Instead of importing `package:moor_flutter/moor_flutter` in your apps, you would then import
|
||||
both `package:moor/moor.dart` and `package:encrypted_moor/encrypted_moor.dart`.
|
||||
|
||||
Finally, you can replace `FlutterQueryExecutor` with an `EncryptedExecutor`.
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Dart VM
|
||||
description: An upcoming version will have a version for the Dart VM
|
||||
---
|
||||
|
||||
An upcoming version of moor will have first class support for the Dart VM,
|
||||
so you can use moor on Desktop Flutter applications or Dart apps.
|
||||
|
||||
We're going to use the `dart:ffi` feature for that, which itself is an
|
||||
experimental state at the moment. We already have a version of moor that
|
||||
runs on the Dart VM (see [#76](https://github.com/simolus3/moor/issues/76))
|
||||
and we're going to release it when `dart:ffi` becomes stable.
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
title: Web support
|
||||
url: /web
|
||||
---
|
||||
|
||||
Starting from moor `1.6`, you can experimentally use moor in Dart webapps. Moor web supports
|
||||
Flutter Web, AngularDart, plain `dart:html` or any other web framework.
|
||||
|
||||
## Getting started
|
||||
Instead of depending on `moor_flutter` in your pubspec, you need to depend on on `moor` directly. Apart from that, you can
|
||||
follow the [getting started guide]({{ site.common_links.getting_started | absolute_url }}).
|
||||
Also, instead of using a `FlutterQueryExecutor` in your database classes, you can use a `WebDatabase` executor:
|
||||
```dart
|
||||
import 'package:moor/moor_web.dart';
|
||||
|
||||
@UseMoor(tables: [Todos, Categories])
|
||||
class MyDatabase extends _$MyDatabase {
|
||||
// here, "app" is the name of the database - you can choose any name you want
|
||||
MyDatabase() : super(WebDatabase('app'));
|
||||
```
|
||||
|
||||
Moor web is built on top of the [sql.js](https://github.com/kripken/sql.js/) library, which you need to include:
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<script defer src="sql-wasm.js"></script>
|
||||
<script defer src="main.dart.js" type="application/javascript"></script>
|
||||
</head>
|
||||
<body></body>
|
||||
</html>
|
||||
```
|
||||
You can grab the latest version of `sql-wasm.js` and `sql-wasm.wasm` [here](https://github.com/kripken/sql.js/tree/master/dist)
|
||||
and copy them into your `web` folder.
|
||||
|
||||
## Gotchas
|
||||
The database implementation uses WebAssembly, which needs to be supported by your browser.
|
||||
Also, make sure that your webserver serves the `.wasm` file as `application/wasm`, browsers
|
||||
won't accept it otherwise.
|
||||
|
||||
## Sharing code between native apps and web
|
||||
If you want to share your database code between native applications and webapps, just import the
|
||||
basic `moor` library and make the `QueryExecutor` configurable:
|
||||
```dart
|
||||
// don't import moor_web.dart or moor_flutter/moor_flutter.dart in shared code
|
||||
import 'package:moor/moor.dart';
|
||||
|
||||
@UseMoor(/* ... */)
|
||||
class SharedDatabase extends _$MyDatabase {
|
||||
SharedDatabase(QueryExecutor e): super(e);
|
||||
}
|
||||
```
|
||||
With native Flutter, you can create an instance of your database with
|
||||
```dart
|
||||
import 'package:moor_flutter/moor_flutter.dart';
|
||||
SharedDatabase constructDb() {
|
||||
return SharedDatabase(FlutterQueryExecutor.inDatabaseFolder(path: 'db.sqlite'));
|
||||
}
|
||||
```
|
||||
On the web, you can use
|
||||
```dart
|
||||
import 'package:moor/moor_web.dart';
|
||||
SharedDatabase constructDb() {
|
||||
return SharedDatabase(WebDatabse('db'));
|
||||
}
|
||||
```
|
||||
|
||||
## Debugging
|
||||
You can see all queries sent from moor to the underlying database engine by enabling the `logStatements`
|
||||
parameter on the `WebDatabase` - they will appear in the console.
|
||||
When you have assertions enabled (e.g. in debug mode), moor will expose the underlying
|
||||
[database](http://kripken.github.io/sql.js/documentation/#http://kripken.github.io/sql.js/documentation/class/Database.html)
|
||||
object via `window.db`. If you need to quickly run a query to check the state of the database, you can use
|
||||
`db.exec(sql)`.
|
||||
If you need to delete your databases, there stored using local storage. You can clear all your data with `localStorage.clear()`.
|
||||
|
||||
Web support is experimental at the moment, so please [report all issues](https://github.com/simolus3/moor/issues/new) you find.
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
|
||||
---
|
||||
title: "Examples"
|
||||
linkTitle: "Examples"
|
||||
weight: 3
|
||||
description: Example apps using moor
|
||||
---
|
||||
|
||||
|
||||
We have an [example in the repo](https://github.com/simolus3/moor/tree/master/moor_flutter/example), it's a simple todo list app,
|
||||
written with moor.
|
||||
|
||||
The [HackerNews reader app](https://github.com/filiph/hn_app) from the [Boring Flutter Show](https://www.youtube.com/playlist?list=PLjxrf2q8roU3ahJVrSgAnPjzkpGmL9Czl) also uses moor to keep a list of favorite articles.
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: "Frequently asked questions"
|
||||
|
||||
url: /faq/
|
||||
---
|
||||
|
||||
|
||||
## Using the database
|
||||
If you've created a `MyDatabase` class by following the [getting started guide]({{site.url}}/getting-started/), you
|
||||
still need to somehow obtain an instance of it. It's recommended to only have one (singleton) instance of your database,
|
||||
so you could store that instance in a global variable:
|
||||
|
||||
### Vanilla flutter
|
||||
```dart
|
||||
MyDatabase database;
|
||||
|
||||
void main() {
|
||||
database = MyDatabase();
|
||||
runApp(MyFlutterApp());
|
||||
}
|
||||
```
|
||||
It would be cleaner to use `InheritedWidgets` for that, and the `provider` package helps here:
|
||||
|
||||
### Provider
|
||||
If you're using the [provider](https://pub.dev/packages/provider) package, you can wrap your top-level widget in a
|
||||
provider that manages the database instance:
|
||||
```dart
|
||||
void main() {
|
||||
runApp(
|
||||
Provider<MyDatabase>(
|
||||
builder: (context) => MyDatabase(),
|
||||
child: MyFlutterApp(),
|
||||
dispose: (context, db) => db.close(),
|
||||
),
|
||||
);
|
||||
}
|
||||
```
|
||||
Your widgets would then have access to the database using `Provider.of<MyDatabase>(context)`.
|
||||
|
||||
### A more complex architecture
|
||||
If you're strict on keeping your business logic out of the widget layer, you probably use some dependency injection
|
||||
framework like `kiwi` or `get_it` to instantiate services and view models. Creating a singleton instance of `MyDatabase`
|
||||
in your favorite dependency injection framework for flutter hence solves this problem for you.
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
title: "Transactions"
|
||||
description: Run multiple queries atomically
|
||||
|
||||
aliases:
|
||||
- /transactions/
|
||||
---
|
||||
|
||||
Moor has support for transactions and allows multiple queries to run atomically,
|
||||
so that none of their changes is visible to the main database until the transaction
|
||||
is finished.
|
||||
To begin a transaction, call the `transaction` method on your database or a DAO.
|
||||
It takes a function as an argument that will be run transactionally. In the
|
||||
following example, which deals with deleting a category, we move all todo entries
|
||||
in that category back to the default category:
|
||||
```dart
|
||||
Future deleteCategory(Category category) {
|
||||
return transaction((_) async {
|
||||
// first, move the affected todo entries back to the default category
|
||||
await customUpdate(
|
||||
'UPDATE todos SET category = NULL WHERE category = ?',
|
||||
updates: {todos},
|
||||
variables: [Variable.withInt(category.id)],
|
||||
);
|
||||
|
||||
// then, delete the category
|
||||
await delete(categories).delete(category);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
{{% alert title="About that _" color="info" %}}
|
||||
You might have noticed that `_` parameter on the `transaction()` callback. That parameter would
|
||||
be a special version of the database that runs all the methods called on it inside the transaction.
|
||||
In previous moor versions, it was important to call everything on that parameter, e.g.
|
||||
```dart
|
||||
transaction((db) async {
|
||||
await db.delete(categories).delete(category);
|
||||
});
|
||||
```
|
||||
Starting from moor 1.6, this is no longer neccessary, we can figure out that you meant to run that
|
||||
in a transaction because it was called from inside a `transaction` callback. We're going to remove
|
||||
that parameter entirely in moor 2.0.
|
||||
{{% /alert %}}
|
||||
|
||||
## ⚠️ Gotchas
|
||||
There are a couple of things that should be kept in mind when working with transactions:
|
||||
1. __Await all calls__: All queries inside the transaction must be `await`-ed. The transaction
|
||||
will complete when the inner method completes. Without `await`, some queries might be operating
|
||||
on the transaction after it has been closed! This can cause data loss or runtime crashes.
|
||||
2. __No select streams in transactions__: Inside a `transaction` callback, select statements can't
|
||||
be `.watch()`ed. The reasons behind this is that it's unclear how a stream should behave when a
|
||||
transaction completes. Should the stream complete as well? Update to data changes made outside of the
|
||||
transaction? Both seem inconsistent, so moor forbids this.
|
||||
|
||||
## Transactions and query streams
|
||||
Query streams that have been created outside a transaction work nicely together with
|
||||
updates made in a transaction: All changes to tables will only be reported after the
|
||||
transaction completes. Updates inside a transaction don't have an immediate effect on
|
||||
streams, so your data will always be consistent.
|
||||
|
||||
However, as mentioned above, note that streams can't be created inside a `transaction` block.
|
||||
Loading…
Reference in New Issue