Skip to content
Permalink
Browse files

More guides for moor 2.0

  • Loading branch information...
simolus3 committed Oct 1, 2019
1 parent 869aaad commit 742cec4d0e139fe8c45c9f11565fcc09b9c7833f
@@ -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 [![Flutter version](https://img.shields.io/pub/v/moor_flutter.svg)](https://pub.dartlang.org/packages/moor_flutter) and the current version of `moor_generator` is [![Generator version](https://img.shields.io/pub/v/moor_generator.svg)](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 [![Flutter version](https://img.shields.io/pub/v/moor_flutter.svg)](https://pub.dartlang.org/packages/moor_flutter) and the current version of `moor_generator` is [![Generator version](https://img.shields.io/pub/v/moor_generator.svg)](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

0 comments on commit 742cec4

Please sign in to comment.
You can’t perform that action at this time.