From e0593136492bec16e84d21ea27cc6f18d7f9ba5a Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Sun, 17 Sep 2023 19:01:58 +0200 Subject: [PATCH] Rename "Using SQL" to "SQL API" --- .../snippets/{ => platforms}/encryption.dart | 0 .../{engines => platforms}/new_connect.dart | 0 .../{engines => platforms}/stable_worker.dart | 0 .../snippets/{engines => platforms}/web.dart | 0 .../{engines => platforms}/workers.dart | 0 .../docs/Advanced Features/builder_options.md | 2 +- .../Advanced Features/custom_row_classes.md | 4 +- docs/pages/docs/Dart API/expressions.md | 2 +- .../docs/Getting started/starting_with_sql.md | 107 ------------------ docs/pages/docs/Platforms/encryption.md | 2 +- docs/pages/docs/Platforms/web.md | 8 +- .../{Using SQL => SQL API}/custom_queries.md | 0 .../{Using SQL => SQL API}/drift_files.md | 0 .../docs/{Using SQL => SQL API}/extensions.md | 15 ++- docs/pages/docs/SQL API/index.md | 46 +++++++- .../docs/{Using SQL => SQL API}/sql_ide.md | 0 docs/pages/docs/Using SQL/index.md | 12 -- docs/pages/docs/faq.md | 2 +- docs/pages/index.html | 4 +- docs/pages/v2.html | 10 +- 20 files changed, 72 insertions(+), 142 deletions(-) rename docs/lib/snippets/{ => platforms}/encryption.dart (100%) rename docs/lib/snippets/{engines => platforms}/new_connect.dart (100%) rename docs/lib/snippets/{engines => platforms}/stable_worker.dart (100%) rename docs/lib/snippets/{engines => platforms}/web.dart (100%) rename docs/lib/snippets/{engines => platforms}/workers.dart (100%) delete mode 100644 docs/pages/docs/Getting started/starting_with_sql.md rename docs/pages/docs/{Using SQL => SQL API}/custom_queries.md (100%) rename docs/pages/docs/{Using SQL => SQL API}/drift_files.md (100%) rename docs/pages/docs/{Using SQL => SQL API}/extensions.md (79%) rename docs/pages/docs/{Using SQL => SQL API}/sql_ide.md (100%) delete mode 100644 docs/pages/docs/Using SQL/index.md diff --git a/docs/lib/snippets/encryption.dart b/docs/lib/snippets/platforms/encryption.dart similarity index 100% rename from docs/lib/snippets/encryption.dart rename to docs/lib/snippets/platforms/encryption.dart diff --git a/docs/lib/snippets/engines/new_connect.dart b/docs/lib/snippets/platforms/new_connect.dart similarity index 100% rename from docs/lib/snippets/engines/new_connect.dart rename to docs/lib/snippets/platforms/new_connect.dart diff --git a/docs/lib/snippets/engines/stable_worker.dart b/docs/lib/snippets/platforms/stable_worker.dart similarity index 100% rename from docs/lib/snippets/engines/stable_worker.dart rename to docs/lib/snippets/platforms/stable_worker.dart diff --git a/docs/lib/snippets/engines/web.dart b/docs/lib/snippets/platforms/web.dart similarity index 100% rename from docs/lib/snippets/engines/web.dart rename to docs/lib/snippets/platforms/web.dart diff --git a/docs/lib/snippets/engines/workers.dart b/docs/lib/snippets/platforms/workers.dart similarity index 100% rename from docs/lib/snippets/engines/workers.dart rename to docs/lib/snippets/platforms/workers.dart diff --git a/docs/pages/docs/Advanced Features/builder_options.md b/docs/pages/docs/Advanced Features/builder_options.md index 0d665c39a..d8466e98f 100644 --- a/docs/pages/docs/Advanced Features/builder_options.md +++ b/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. diff --git a/docs/pages/docs/Advanced Features/custom_row_classes.md b/docs/pages/docs/Advanced Features/custom_row_classes.md index 51e989adf..93390a8a5 100644 --- a/docs/pages/docs/Advanced Features/custom_row_classes.md +++ b/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. diff --git a/docs/pages/docs/Dart API/expressions.md b/docs/pages/docs/Dart API/expressions.md index 328aca8dc..a1cb2e34a 100644 --- a/docs/pages/docs/Dart API/expressions.md +++ b/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. diff --git a/docs/pages/docs/Getting started/starting_with_sql.md b/docs/pages/docs/Getting started/starting_with_sql.md deleted file mode 100644 index 05b4eb3a5..000000000 --- a/docs/pages/docs/Getting started/starting_with_sql.md +++ /dev/null @@ -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 ` 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 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>`) - or as an auto-updating stream (by using `.watch` instead of `.get()`). - - a `Selectable 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 %} diff --git a/docs/pages/docs/Platforms/encryption.md b/docs/pages/docs/Platforms/encryption.md index fdad3f69c..79b466e15 100644 --- a/docs/pages/docs/Platforms/encryption.md +++ b/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 diff --git a/docs/pages/docs/Platforms/web.md b/docs/pages/docs/Platforms/web.md index cebe8da44..93732dcb3 100644 --- a/docs/pages/docs/Platforms/web.md +++ b/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" %} diff --git a/docs/pages/docs/Using SQL/custom_queries.md b/docs/pages/docs/SQL API/custom_queries.md similarity index 100% rename from docs/pages/docs/Using SQL/custom_queries.md rename to docs/pages/docs/SQL API/custom_queries.md diff --git a/docs/pages/docs/Using SQL/drift_files.md b/docs/pages/docs/SQL API/drift_files.md similarity index 100% rename from docs/pages/docs/Using SQL/drift_files.md rename to docs/pages/docs/SQL API/drift_files.md diff --git a/docs/pages/docs/Using SQL/extensions.md b/docs/pages/docs/SQL API/extensions.md similarity index 79% rename from docs/pages/docs/Using SQL/extensions.md rename to docs/pages/docs/SQL API/extensions.md index 934118e7c..1e08cc384 100644 --- a/docs/pages/docs/Using SQL/extensions.md +++ b/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(); - } + } } ``` diff --git a/docs/pages/docs/SQL API/index.md b/docs/pages/docs/SQL API/index.md index 5d251b0ae..ac05ed186 100644 --- a/docs/pages/docs/SQL API/index.md +++ b/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 ` 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. + diff --git a/docs/pages/docs/Using SQL/sql_ide.md b/docs/pages/docs/SQL API/sql_ide.md similarity index 100% rename from docs/pages/docs/Using SQL/sql_ide.md rename to docs/pages/docs/SQL API/sql_ide.md diff --git a/docs/pages/docs/Using SQL/index.md b/docs/pages/docs/Using SQL/index.md deleted file mode 100644 index 2be59fde3..000000000 --- a/docs/pages/docs/Using SQL/index.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/docs/pages/docs/faq.md b/docs/pages/docs/faq.md index d65c6f3d1..e35251992 100644 --- a/docs/pages/docs/faq.md +++ b/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. diff --git a/docs/pages/index.html b/docs/pages/index.html index 53c2aa1d9..b093a712f 100644 --- a/docs/pages/index.html +++ b/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 %} diff --git a/docs/pages/v2.html b/docs/pages/v2.html index 89928f99f..5409bbb23 100644 --- a/docs/pages/v2.html +++ b/docs/pages/v2.html @@ -12,7 +12,7 @@ Get started - + Migrate an existing project @@ -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 %} \ No newline at end of file