More guides for moor 2.0

docs/content/en/docs/Getting started/_index.md

@@ -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

docs/content/en/docs/Getting started/starting_with_sql.md

@@ -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.

docs/content/en/docs/Using SQL/moor_files.md

@@ -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';
 

docs/content/en/docs/Using SQL/sql_ide.md

@@ -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,
+3. Finally, close and reopen your IDE so that the analysis server is restarted. The analysis server will
-   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
    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.

docs/content/en/v2/index.md

@@ -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" %}}
+{{% blocks/feature icon="fas fa-database" title="Pure SQL API" %}}
-The new type inference engine provides more accurate results on complex expressions like window
+The new `.moor` files have been updated and can now hold both `CREATE TABLE` statements
-functions. We also generate simpler methods for queries that only return one column.
+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 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 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 >}}

moor_flutter/pubspec.lock

@@ -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