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/Getting started/starting_with_sql.md

@@ -1,107 +0,0 @@
----
-data:
-  title: "Getting started with sql"
-  weight: 5
-  description: Learn how to get started with the SQL version of drift, or how to migrate an existing project to drift.
-template: layouts/docs/single
----
-
-The regular [getting started guide]({{ "../setup.md" | pageUrl }}) explains how to get started with drift by
-declaring both tables and queries in Dart. This version will focus on how to use drift with SQL instead.
-
-A complete cross-platform Flutter app using drift is also available [here](https://github.com/simolus3/drift/tree/develop/examples/app).
-
-## Adding the dependency
-
-{% include "partials/dependencies" %}
-
-## Declaring tables and queries
-
-To declare tables and queries in sql, create a file called `tables.drift`
-next to your Dart files (for instance in `lib/database/tables.drift`).
-
-You can put `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 drift, you can just copy the `CREATE TABLE`
-statements you've already written into this file.
-
-{% 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 %}
-
-## Generating matching code
-
-After you declared the tables, lets generate some Dart code to actually
-run them. Drift needs to know which tables are used in a database, so we
-have to write a small Dart class that drift will then read. Lets create
-a file called `database.dart` next to the `tables.drift` file you wrote
-in the previous step.
-
-{% 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.
-
-## What drift generates
-
-Let's take a look at what drift 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 drift, you can [learn more here]({{ "../Dart API/writes.md#inserts" | pageUrl }}).
-- 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.drift` file:
-  - a `Selectable<Todo> todosInCategory(int)` method, which runs the
-    `todosInCategory` query declared above. Drift 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 `.drift` file - drift will generate matching code for them as well.
-
-## Learning more
-
-Now that you know how to use drift together with sql, here are some
-further guides to help you learn more:
-
-- The [SQL IDE]({{ "../Using SQL/sql_ide.md" | pageUrl }}) that provides feedback on sql queries right in your editor.
-- [Transactions]({{ "../Dart API/transactions.md" | pageUrl }})
-- [Schema migrations]({{ "../Migrations/index.md" | pageUrl }})
-- Writing [queries]({{ "../Dart API/select.md" | pageUrl }}) and
-  [expressions]({{ "../Dart API/expressions.md" | pageUrl }}) in Dart
-- A more [in-depth guide]({{ "../Using SQL/drift_files.md" | pageUrl }})
-  on `drift` files, which explains `import` statements and the Dart-SQL interop.
-
-{% block "blocks/alert" title="Using the database" %}
-The database class from this guide is ready to be used with your app.
-For Flutter apps, a Drift database class is typically instantiated at the top of your widget tree
-and then passed down with `provider` or `riverpod`.
-See [using the database]({{ '../faq.md#using-the-database' | pageUrl }}) for ideas on how to integrate
-Drift into your app's state management.
-
-The setup in this guide uses [platform channels](https://flutter.dev/docs/development/platform-integration/platform-channels),
-which are only available after running `runApp` by default.
-When using drift before your app is initialized, please call `WidgetsFlutterBinding.ensureInitialized()` before using
-the database to ensure that platform channels are ready.
-{% endblock %}

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/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/Using SQL/index.md

@@ -1,12 +0,0 @@
----
-data:
-  title: "Using SQL"
-  weight: 30
-  description: Write typesafe sql with drift
-template: layouts/docs/list
----
-
-Drift lets you express a variety of queries in pure Dart. However, you don't have to miss out
-on its features when you need more complex queries or simply prefer sql. Drift has a builtin
-sql parser and analyzer, so it can generate a typesafe API for sql statements you write.
-It can also warn about errors in your sql at build time.

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 @@ validated and analyzed during build-time, so drift can provide hints about poten
 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 @@ Other database libraries can easily be integrated into drift as well.
 {% 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 @@ path: v2
     <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 @@ path: v2
 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 @@ The new `.moor` files have been updated and can now hold both `CREATE TABLE` sta
 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 @@ Moor 2.0 expands the previous sql parser and analyzer, providing real-time feedb
 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 @@ _Please not that the package is still in preview_
 
 - 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 %}