Rename "Using SQL" to "SQL API"

docs/pages/docs/Advanced Features/builder_options.md

@@ -67,7 +67,7 @@ At the moment, drift supports these options:
  to `null`.
 * `named_parameters`: Generates named parameters for named variables in SQL queries.
 * `named_parameters_always_required`: All named parameters (generated if `named_parameters` option is `true`) will be required in Dart.
-* `scoped_dart_components` (defaults to `true`): Generates a function parameter for [Dart placeholders]({{ '../Using SQL/drift_files.md#dart-components-in-sql' | pageUrl }}) in SQL.
+* `scoped_dart_components` (defaults to `true`): Generates a function parameter for [Dart placeholders]({{ '../SQL API/drift_files.md#dart-components-in-sql' | pageUrl }}) in SQL.
  The function has a parameter for each table that is available in the query, making it easier to get aliases right when using
  Dart placeholders.
 * `store_date_time_values_as_text`: Whether date-time columns should be stored as ISO 8601 string instead of a unix timestamp.

docs/pages/docs/Advanced Features/custom_row_classes.md

@@ -167,10 +167,10 @@ For your convenience, drift is using different generation strategies even for qu
 an existing row class. It is helpful to enumerate them because they affect the allowed type for
 fields in existing types as well.
 
-1. Nested tables: When the [`SELECT table.**` syntax]({{ '../Using SQL/drift_files.md#nested-results' | pageUrl }})
+1. Nested tables: When the [`SELECT table.**` syntax]({{ '../SQL API/drift_files.md#nested-results' | pageUrl }})
  is used in a query, drift will pack columns from `table` into a nested object instead of generating fields
  for every column.
-2. Nested list results: The [`LIST()` macro]({{ '../Using SQL/drift_files.md#list-subqueries' | pageUrl }})
+2. Nested list results: The [`LIST()` macro]({{ '../SQL API/drift_files.md#list-subqueries' | pageUrl }})
  can be used to expose results of a subquery as a list.
 3. Single-table results: When a select statement reads all columns from a table (and no additional columns),
  like in `SELECT * FROM table`, drift will use the data class of the table instead of generating a new one.

docs/pages/docs/Dart API/expressions.md

@@ -259,4 +259,4 @@ select(users)..where((u) => inactive);
 _Note_: It's easy to write invalid queries by using `CustomExpressions` too much. If you feel like
 you need to use them because a feature you use is not available in drift, consider creating an issue
 to let us know. If you just prefer sql, you could also take a look at
-[compiled sql]({{ "../Using SQL/custom_queries.md" | pageUrl }}) which is typesafe to use.
+[compiled sql]({{ "../SQL API/custom_queries.md" | pageUrl }}) which is typesafe to use.

docs/pages/docs/Platforms/encryption.md

@@ -5,7 +5,7 @@ data:
 template: layouts/docs/single
 ---
 
-{% assign snippets = 'package:drift_docs/snippets/encryption.dart.excerpt.json' | readString | json_decode %}
+{% assign snippets = 'package:drift_docs/snippets/platforms/encryption.dart.excerpt.json' | readString | json_decode %}
 
 There are two ways to use drift on encrypted databases.
 The `encrypted_drift` package is similar to `drift_sqflite` and uses a platform plugin written in

docs/pages/docs/Platforms/web.md

@@ -12,7 +12,7 @@ The `WasmDatabase.open` API is the preferred way to run drift on the web. While
 APIs continue to work, using the stable API will bring performance and safety benefits.
 {% endblock %}
 
-{% assign snippets = "package:drift_docs/snippets/engines/web.dart.excerpt.json" | readString | json_decode %}
+{% assign snippets = "package:drift_docs/snippets/platforms/web.dart.excerpt.json" | readString | json_decode %}
 
 Using modern browser APIs such as WebAssembly and the Origin-Private File System API,
 you can use drift databases for the web version of your Flutter and Dart applications.
@@ -253,7 +253,7 @@ If you want to instead compile these yourself, this section describes how to do
 The web worker is written in Dart - the entrypoint is stable and part of drift's public API.
 To compile a worker suitable for `WasmDatabase.open`, create a new Dart file that calls `WasmDatabase.workerMainForOpen`:
 
-{% assign worker = "package:drift_docs/snippets/engines/stable_worker.dart.excerpt.json" | readString | json_decode %}
+{% assign worker = "package:drift_docs/snippets/platforms/stable_worker.dart.excerpt.json" | readString | json_decode %}
 {% include "blocks/snippet" snippets = worker %}
 
 The JavaScript file included in drift releases is compiled with `dart compile js -O4 web/drift_worker.dart`.
@@ -354,7 +354,7 @@ Drift will automatically migrate data from local storage to `IndexedDb` when it
 
 #### Using web workers
 
-You can offload the database to a background thread by using 
+You can offload the database to a background thread by using
 [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
 Drift also supports [shared workers](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker),
 which allows you to seamlessly synchronize query-streams and updates across multiple tabs!
@@ -369,7 +369,7 @@ A Flutter port of this example is [part of the drift repository](https://github.
 To write a web worker that will serve requests for drift, create a file called `worker.dart` in
 the `web/` folder of your app. It could have the following content:
 
-{% assign workers = 'package:drift_docs/snippets/engines/workers.dart.excerpt.json' | readString | json_decode %}
+{% assign workers = 'package:drift_docs/snippets/platforms/workers.dart.excerpt.json' | readString | json_decode %}
 
 {% include "blocks/snippet" snippets = workers name = "worker" %}
 

docs/pages/docs/Using SQL/extensions.md → docs/pages/docs/SQL API/extensions.md

@@ -2,13 +2,18 @@
 data:
  title: "Supported sqlite extensions"
  weight: 10
- description: Information on json1 and fts5 support in the generator
+ description: Information on json1 and fts5 support in drift files
 template: layouts/docs/single
 ---
 
-_Note_: Since `drift_sqflite` and `moor_flutter` uses the sqlite version shipped on the device, these extensions might not
-be available on all devices. When using these extensions, using a `NativeDatabase` is strongly recommended.
-This enables the extensions listed here on all Android and iOS devices.
+When analyzing `.drift` files, the generator can consider sqlite3 extensions
+that might be present.
+The generator can't know about the sqlite3 library your database is talking to
+though, so it makes a pessimistic assumption of using an old sqlite3 version
+without any enabled extensions by default.
+When using a package like `sqlite3_flutter_libs`, you get the latest sqlite3
+version with the json1 and fts5 extensions enabled. You can inform the generator
+about this by using [build options]({{ "../Advanced Features/builder_options.md" | pageUrl }}).
 
 ## json1
 
@@ -42,7 +47,7 @@ class Database extends _$Database {
  return phoneNumber.equals(number);
  })
  ).get();
- } 
+ }
 }
 ```
 

docs/pages/docs/SQL API/index.md

@@ -3,5 +3,49 @@ data:
  title: SQL API
  description: Define your database and queries in SQL instead.
  weight: 3
-template: layouts/docs/single
+template: layouts/docs/list
 ---
+
+Drift provides a [Dart API]({{ '../Dart API/index.md' | pageUrl }}) to define tables and
+to write SQL queries.
+Especially when you are already familiar with SQL, it might be easier to define your
+tables directly in SQL, with `CREATE TABLE` statements.
+Thanks to a powerful SQL parser and analyzer built into drift, you can still run type-safe
+SQL queries with support for auto-updating streams and all the other drift features.
+The validity of your SQL is checked at build time, with drift generating matching methods
+for each table and SQL statement.
+
+## Setup
+
+The basic setup of adding the drift dependencies matches the setup for the Dart APIs. It
+is described in the [setup page]({{ '../setup.md' | pageUrl }}).
+
+What's different is how tables and queries are declared. For SQL to be recognized by drift,
+it needs to be put into a `.drift` file. In this example, we use a `.drift` file next to the
+database class named `tables.drift`:
+
+{% assign drift_snippets = 'package:drift_docs/snippets/drift_files/getting_started/tables.drift.excerpt.json' | readString | json_decode %}
+
+{% include "blocks/snippet" snippets = drift_snippets name = '(full)' %}
+
+{% block "blocks/alert" title="On that AS Category" %}
+Drift will generate Dart classes for your tables, and the name of those
+classes is based on the table name. By default, drift 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 drift to
+generate a different name with the `AS <name>` declaration at the end.
+{% endblock %}
+
+Integrating drift files into the database simple, they just need to be added to the
+`include` parameter of the `@DriftDatabase` annotation. The `tables` parameter can
+be omitted here, since there are no Dart-defined tables to be added to the database.
+
+{% assign dart_snippets = 'package:drift_docs/snippets/drift_files/getting_started/database.dart.excerpt.json' | readString | json_decode %}
+
+{% include "blocks/snippet" snippets = dart_snippets name = '(full)' %}
+
+To generate the `database.g.dart` file which contains the `_$AppDb`
+superclass, run `dart run build_runner build` on the command
+line.
+

docs/pages/docs/faq.md

@@ -142,7 +142,7 @@ result of your queries.
 ### floor
 Floor also has a lot of convenience features like auto-updating queries and schema migrations. Similar to drift, you
 define the structure of your database in Dart. Then, you have write queries in sql - the mapping code if generated
-by floor. Drift has a [similar feature]({{ "Using SQL/custom_queries.md" | pageUrl }}), but it can also verify that your queries are valid at compile time. Drift
+by floor. Drift has a [similar feature]({{ "SQL API/custom_queries.md" | pageUrl }}), but it can also verify that your queries are valid at compile time. Drift
 additionally has an api that lets you write some queries in Dart instead of sql.
 
 A difference between these two is that Floor lets you write your own classes and generates mapping code around that.

docs/pages/index.html

@@ -62,7 +62,7 @@
 code.
 Of course, you can mix SQL and Dart to your liking.
 
-[Using SQL with Drift]({{ 'docs/Using SQL/index.md' | pageUrl }})
+[Using SQL with Drift]({{ 'docs/SQL API/index.md' | pageUrl }})
 {% endblock %}
 {% endblock %}
 
@@ -80,7 +80,7 @@
 {% block "blocks/feature.html" icon="fas fa-star" title="And much more!" %}
 {% block "blocks/markdown.html" %}
 Drift provides auto-updating streams for all your queries, makes dealing with transactions and migrations easy
-and lets your write modular database code with DAOs. We even have a [sql IDE]({{ 'docs/Using SQL/sql_ide.md' | pageUrl }}) builtin to the project.
+and lets your write modular database code with DAOs.
 When using drift, working with databases in Dart is fun!
 {% endblock %}
 {% endblock %}

docs/pages/v2.html

@@ -12,7 +12,7 @@
  <a class="btn btn-lg btn-primary mr-3 mb-4" href="{{ "docs/index.md" | pageUrl }}">
  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="{{ "docs/Getting started/starting_with_sql.md" | pageUrl }}">
+ <a class="btn btn-lg btn-secondary mr-3 mb-4" href="{{ "docs/SQL API/index.md" | pageUrl }}">
  Migrate an existing project <i class="fas fa-code ml-2 "></i>
  </a>
 </div>
@@ -25,7 +25,7 @@
 The rewritten compiler is faster than ever, supports more SQL features and gives you
 more flexibility when writing database code.
 
-[Check the updated documentation]({{ "docs/Using SQL/drift_files.md" | pageUrl }})
+[Check the updated documentation]({{ "docs/SQL API/drift_files.md" | pageUrl }})
 {% endblock %}
 {% endblock %}
 
@@ -35,7 +35,7 @@
 and queries you define. Moor will then generate typesafe Dart APIs based on your tables
 and statements.
 
-[Get started with SQL and moor]({{ "docs/Getting started/starting_with_sql.md" | pageUrl }})
+[Get started with SQL and moor]({{ "docs/SQL API/index.md" | pageUrl }})
 {% endblock %} {% endblock %}
 {% block "blocks/feature" icon="fas fa-plus" title="Analyzer improvements" %} {% block "blocks/markdown" %}
 We now support more advanced features like compound select statements and window functions,
@@ -59,7 +59,7 @@
 SQL queries as you type. Moor plugs right into the Dart analysis server, so you don't have
 to install any additional extensions.
 
-[Learn more about the IDE]({{ "docs/Using SQL/sql_ide.md" | pageUrl }})
+[Learn more about the IDE]({{ "docs/SQL API/sql_ide.md" | pageUrl }})
 {% endblock %} {% endblock %}
 
 {% block "blocks/section" color="dark" %}
@@ -111,6 +111,6 @@
 
 - To get started with moor, follow our [getting started guide]({{ "docs/setup.md" | pageUrl }}) here.
 - To get started with SQL in moor, or to migrate an existing project to moor, follow our
- [migration guide]({{ "docs/Getting started/starting_with_sql.md" | pageUrl }})
+ [migration guide]({{ "docs/SQL API/index.md" | pageUrl }})
 
 {% endblock %} {% endblock %}