mirror of https://github.com/AMT-Cheif/drift.git
More guides for moor 2.0
This commit is contained in:
Simon Binder
parent
869aaada90
commit
742cec4d0e
|
|
@ -13,7 +13,7 @@ how to get started. You can watch it [here](https://youtu.be/zpWsedYMczM).
|
|||
|
||||
|
||||
## Adding the dependency
|
||||
First, let's add moor to your project's `pubspec.yaml`.
|
||||
First, lets 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)
|
||||
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -0,0 +1,138 @@
|
|||
---
|
||||
title: "Getting started with sql"
|
||||
weight: 5
|
||||
description: Learn how to get started with the SQL version of moor, or how to migrate an existing project to moor.
|
||||
---
|
||||
|
||||
The regular [getting started guide]({{< relref "_index.md" >}}) explains how to get started with moor by
|
||||
declaring both tables and queries in Dart. This version will focus on how to use moor with SQL instead.
|
||||
|
||||
## Adding the dependency
|
||||
First, lets 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)
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
moor_flutter: # use the latest version
|
||||
|
||||
dev_dependencies:
|
||||
moor_generator: # use the latest version
|
||||
build_runner:
|
||||
```
|
||||
|
||||
The `moor_flutter` package will execute sql at runtime, while the
|
||||
`moor_generator` will generate typesafe Dart based on your SQL queries.
|
||||
|
||||
## Declaring tables and queries
|
||||
|
||||
To declare tables and queries in sql, create a file called `tables.moor`
|
||||
next to your Dart files (for instance in `lib/database/tables.moor`).
|
||||
|
||||
You can put the `CREATE TABLE` statements for your queries in there.
|
||||
The following example creates two tables to model a todo-app. If you're
|
||||
migrating an existing project to moor, you would put the `CREATE TABLE`
|
||||
for your tables in there.
|
||||
```sql
|
||||
-- this is the tables.moor file
|
||||
CREATE TABLE todos (
|
||||
id INT NOT NULL PRIMARY KEY AUTOINCREMENT,
|
||||
title TEXT,
|
||||
body TEXT,
|
||||
category INT REFERENCES categories (id)
|
||||
);
|
||||
|
||||
CREATE TABLE categories (
|
||||
id INT NOT NULL PRIMARY KEY AUTOINCREMENT,
|
||||
description TEXT,
|
||||
) AS Category; -- see the explanation on "AS Category" below
|
||||
|
||||
/* after declaring your tables, you can put queries in here. Just
|
||||
write the name of the query, a colon (:) and the SQL: */
|
||||
todosInCategory: SELECT * FROM todos WHERE category = ?;
|
||||
|
||||
/* Here's a more complex query: It counts the amount of entries per
|
||||
category, including those entries which aren't in any category at all. */
|
||||
countEntries:
|
||||
SELECT
|
||||
c.desc,
|
||||
(SELECT COUNT(*) FROM todos WHERE category = c.id) AS amount
|
||||
FROM categories c
|
||||
UNION ALL
|
||||
SELECT null, (SELECT COUNT(*) FROM todos WHERE category IS NULL)
|
||||
```
|
||||
|
||||
{{% alert title="On that AS Category" %}}
|
||||
Moor will generate Dart classes for your tables, and the name of those
|
||||
classes is based on the table name. By default, moor just strips away
|
||||
the trailing `s` from your table. That works for most cases, but in some
|
||||
(like the `categories` table above), it doesn't. We'd like to have a
|
||||
`Category` class (and not `Categorie`) generated, so we tell moor to
|
||||
generate a different name with the `AS <name>` declaration at the end.
|
||||
{{% /alert %}}
|
||||
|
||||
## Generating matching code
|
||||
|
||||
After you declared the tables, lets generate some Dart code to actually
|
||||
run them. Moor needs to know which tables are used in a database, so we
|
||||
have to write a small Dart class that moor will then read. Lets create
|
||||
a file called `database.dart` next to the `tables.moor` file you wrote
|
||||
in the previous step.
|
||||
|
||||
```dart
|
||||
import 'package:moor_flutter/moor_flutter.dart';
|
||||
|
||||
part 'database.g.dart';
|
||||
|
||||
@UseMoor(
|
||||
include: {'tables.moor'},
|
||||
)
|
||||
class AppDb extends _$AppDb {
|
||||
AppDb() : super(FlutterQueryExecutor.inDatabaseFolder('app.db'));
|
||||
|
||||
@override
|
||||
int get schemaVersion => 1;
|
||||
}
|
||||
```
|
||||
|
||||
To generate the `database.g.dart` file which contains the `_$AppDb`
|
||||
superclass, run `flutter pub run build_runner build` on the command
|
||||
line.
|
||||
|
||||
## What moor generates
|
||||
|
||||
Let's take a look at what moor generated during the build:
|
||||
|
||||
- Generated data classes (`Todo` and `Category`) - these hold a single
|
||||
row from the respective table.
|
||||
- Companion versions of these classes. Those are only relevant when
|
||||
using the Dart apis of moor, you can [learn more here]({{< relref "writing_queries.md#inserts" >}}).
|
||||
- A `CountEntriesResult` class, it holds the result rows when running the
|
||||
`countEntries` query.
|
||||
- A `_$AppDb` superclass. It takes care of creating the tables when
|
||||
the database file is first opened. It also contains typesafe methods
|
||||
for the queries declared in the `tables.moor` file:
|
||||
- a `Selectable<Todo> todosInCategory(int)` method, which runs the
|
||||
`todosInCategory` query declared above. Moor has determined that the
|
||||
type of the variable in that query is `int`, because that's the type
|
||||
of the `category` column we're comparing it to.
|
||||
The method returns a `Selectable` to indicate that it can both be
|
||||
used as a regular query (`Selectable.get` returns a `Future<List<Todo>>`)
|
||||
or as an auto-updating stream (by using `.watch` instead of `.get()`).
|
||||
- a `Selectable<CountEntriesResult> countEntries()` method, which runs
|
||||
the other query when used.
|
||||
|
||||
By the way, you can also put insert, update and delete statements in
|
||||
a `.moor` file - moor will generate matching code for them as well.
|
||||
|
||||
## Learning more
|
||||
|
||||
Know that you know how to use moor together with sql, here are some
|
||||
further guides to help you learn more:
|
||||
|
||||
- The [SQL IDE]({{< relref "../Using SQL/sql_ide.md" >}}) that provides feedback on sql queries right in your editor.
|
||||
- [Transactions]({{< relref "../transactions.md" >}})
|
||||
- [Schema migrations]({{< relref "../Advanced Features/migrations.md" >}})
|
||||
- Writing [queries]({{< relref "writing_queries.md" >}}) and
|
||||
[expressions]({{< relref "expressions.md" >}}) in Dart
|
||||
- A more [in-depth guide]({{< relref "../Using SQL/moor_files.md" >}})
|
||||
on `moor` files, which explains `import` statements and the Dart-SQL interop.
|
||||
|
|
@ -13,7 +13,7 @@ Moor files are a new feature that lets you write all your database code in SQL -
|
|||
To use this feature, lets create two files: `database.dart` and `tables.moor`. The Dart file only contains the minimum code
|
||||
to setup the database:
|
||||
```dart
|
||||
import 'package:moor/moor.dart';
|
||||
import 'package:moor_flutter/moor_flutter.dart';
|
||||
|
||||
part 'database.g.dart';
|
||||
|
||||
|
|
|
|||
|
|
@ -7,33 +7,55 @@ description: Get real-time feedback as you type sql
|
|||
Moor ships with an experimental analyzer plugin that provides real-time feedback on errors,
|
||||
hints, folding and outline.
|
||||
|
||||
## Using with VS Code
|
||||
## Features
|
||||
|
||||
At the moment, the IDE supports
|
||||
|
||||
- auto-complete to suggest matching keywords as you type
|
||||
- warnings and errors for your queries
|
||||
- navigation (Ctrl click on a reference to see where a column or table is declared)
|
||||
- an outline view highlighting tables and queries
|
||||
- folding inside `CREATE TABLE` statements and import-blocks
|
||||
|
||||
We would very much like to support syntax highlighting, but sadly VS Code doesn't support
|
||||
that. Please upvote [this issue](https://github.com/microsoft/vscode/issues/585) to help
|
||||
us here.
|
||||
|
||||
## Setup
|
||||
To use the plugin, you need a supported editor (see below).
|
||||
|
||||
First, tell the Dart analysis server to run the moor plugin. Create a file called
|
||||
`analysis_options.yaml` in your project root, next to your pubspec. It should contain
|
||||
this section:
|
||||
```yaml
|
||||
analyzer:
|
||||
plugins:
|
||||
- moor
|
||||
```
|
||||
|
||||
Then, follow the steps for the IDE you want to use.
|
||||
|
||||
### Using with VS Code
|
||||
|
||||
Make sure that your project depends on moor 2.0 or later. Then
|
||||
|
||||
1. In the preferences, make sure that the `dart.analyzeAngularTemplates` option is
|
||||
set to true.
|
||||
set to true. Contrary to its name, that flag turns on the plugin system, so you
|
||||
don't need to worry about angular.
|
||||
2. Tell Dart Code to analyze moor files as well. Add this to your `settings.json`:
|
||||
```json
|
||||
"dart.additionalAnalyzerFileExtensions": [
|
||||
"moor"
|
||||
]
|
||||
```
|
||||
3. Enable the plugin in Dart: Create a file called `analysis_options.yaml` in your project root,
|
||||
next to your pubspec. It should contain this section:
|
||||
```yaml
|
||||
analyzer:
|
||||
plugins:
|
||||
- moor
|
||||
```
|
||||
4. Finally, close and reopen your IDE so that the analysis server is restarted. The analysis server will
|
||||
3. Finally, close and reopen your IDE so that the analysis server is restarted. The analysis server will
|
||||
then load the moor plugin and start providing analysis results for `.moor` files. Loading the plugin
|
||||
can take some time (around a minute for the first time).
|
||||
|
||||
## Other IDEs
|
||||
### Other IDEs
|
||||
|
||||
Unfortunately, we can't support IntelliJ and Android Studio yet. Please vote on
|
||||
[this issue](https://youtrack.jetbrains.com/issue/WEB-41424) to help us here!
|
||||
|
||||
If you're looking for support for an other IDE that uses the Dart analysis server,
|
||||
please create an issue. We can very probably make that happen.
|
||||
please create an issue. We can probably make that happen.
|
||||
|
|
@ -1,13 +1,20 @@
|
|||
---
|
||||
title: Moor v2
|
||||
title: Version 2.0
|
||||
layout: home
|
||||
---
|
||||
|
||||
{{< blocks/cover title="Moor 2.0: Supercharged SQL for Dart" image_anchor="top" height="min" color="indigo" >}}
|
||||
<div class="mx-auto">
|
||||
<p class="lead mt-5">
|
||||
Learn everything about Dart-SQL interop, the SQL IDE, experimental ffi support and everything new in moor
|
||||
Learn everything about Dart-SQL interop, the SQL IDE, experimental ffi support and all things new in moor
|
||||
</p>
|
||||
|
||||
<a class="btn btn-lg btn-primary mr-3 mb-4" href="{{< relref "/docs" >}}">
|
||||
Get started <i class="fas fa-arrow-alt-circle-right ml-2"></i>
|
||||
</a>
|
||||
<a class="btn btn-lg btn-secondary mr-3 mb-4" href="{{< relref "/docs/Getting started/starting_with_sql.md" >}}">
|
||||
Migrate an existing project <i class="fas fa-code ml-2 "></i>
|
||||
</a>
|
||||
</div>
|
||||
{{< /blocks/cover >}}
|
||||
|
||||
|
|
@ -21,13 +28,18 @@ more flexibility when writing database code.
|
|||
{{% /blocks/lead %}}
|
||||
|
||||
{{< blocks/section color="light" >}}
|
||||
{{% blocks/feature icon="fas fa-puzzle-piece" title="Improved type inference" %}}
|
||||
The new type inference engine provides more accurate results on complex expressions like window
|
||||
functions. We also generate simpler methods for queries that only return one column.
|
||||
{{% blocks/feature icon="fas fa-database" title="Pure SQL API" %}}
|
||||
The new `.moor` files have been updated and can now hold both `CREATE TABLE` statements
|
||||
and queries you define. Moor will then generate typesafe Dart APIs based on your tables
|
||||
and statements.
|
||||
|
||||
[Get started with SQL and moor]({{< ref "../docs/Getting started/starting_with_sql.md" >}})
|
||||
{{% /blocks/feature %}}
|
||||
{{% blocks/feature icon="fas fa-database" title="Parser improvements" %}}
|
||||
{{% blocks/feature icon="fas fa-plus" title="Analyzer improvements" %}}
|
||||
We now support more advanced features like compound select statements and window functions,
|
||||
including detailed static analysis and lints.
|
||||
including detailed static analysis and lints. The updated type inference engine provides
|
||||
better results on complex expressions. We also generate simpler methods for queries that only
|
||||
return one column.
|
||||
{{% /blocks/feature %}}
|
||||
{{% blocks/feature icon="fas fa-code-branch" title="Dart-SQL interop" %}}
|
||||
Declare tables in Dart, write your queries in SQL. Or do it the other way around. Or do it all in Dart.
|
||||
|
|
@ -95,7 +107,8 @@ _Please not that the package is still in preview_
|
|||
{{< blocks/section color="dark" type="section" >}}
|
||||
## Try moor now
|
||||
|
||||
- To get started with moor, follow our [getting started guide](ref "../docs/Getting started/_index.md") here.
|
||||
- To get started with SQL in moor, or to migrate an project to moor, follow our __TODO: Write migration guide__
|
||||
- To get started with moor, follow our [getting started guide]({{< ref "../docs/Getting started/_index.md" >}}) here.
|
||||
- To get started with SQL in moor, or to migrate an existing project to moor, follow our
|
||||
[migration guide]({{< ref "../docs/Getting started/starting_with_sql.md" >}})
|
||||
|
||||
{{< /blocks/section >}}
|
||||
|
|
@ -29,6 +29,13 @@ packages:
|
|||
url: "https://pub.dartlang.org"
|
||||
source: hosted
|
||||
version: "1.14.11"
|
||||
convert:
|
||||
dependency: transitive
|
||||
description:
|
||||
name: convert
|
||||
url: "https://pub.dartlang.org"
|
||||
source: hosted
|
||||
version: "2.1.1"
|
||||
flutter:
|
||||
dependency: "direct main"
|
||||
description: flutter
|
||||
|
|
|
|||
Loading…
Reference in New Issue