mirror of https://github.com/AMT-Cheif/drift.git
Fix grammar mistakes in documentation
This commit is contained in:
parent
f043e2997a
commit
0b0a721164
|
@ -37,7 +37,7 @@ The project is divided into multiple modules:
|
||||||
- `moor_flutter/`: Contains a Flutter implementation for the database.
|
- `moor_flutter/`: Contains a Flutter implementation for the database.
|
||||||
- `drift_dev/`: Creates table, database and dao classes from the table structure and
|
- `drift_dev/`: Creates table, database and dao classes from the table structure and
|
||||||
compiled queries.
|
compiled queries.
|
||||||
- `sqlparser/`: Contains an sql parser and analyzer that is mostly independent of drift,
|
- `sqlparser/`: Contains an SQL parser and analyzer that is mostly independent of drift,
|
||||||
but used by the generator for compiled custom queries.
|
but used by the generator for compiled custom queries.
|
||||||
|
|
||||||
## Concepts
|
## Concepts
|
||||||
|
@ -46,7 +46,7 @@ we generate three classes:
|
||||||
|
|
||||||
1. A class that inherits from `TableInfo` (we call this the "table class"). It contains a structural representation
|
1. A class that inherits from `TableInfo` (we call this the "table class"). It contains a structural representation
|
||||||
of the table, which includes columns (including name, type, constraints...), the primary key and so on. The idea is
|
of the table, which includes columns (including name, type, constraints...), the primary key and so on. The idea is
|
||||||
that, if we have a `TableInfo` instance, we can create all kinds of sql statements.
|
that, if we have a `TableInfo` instance, we can create all kinds of SQL statements.
|
||||||
2. A class to represent a fully loaded row of a table. We call this a "data class" and it inherits from `DataClass`.
|
2. A class to represent a fully loaded row of a table. We call this a "data class" and it inherits from `DataClass`.
|
||||||
3. A class to represent partial data (e.g. for inserts or updates, where not all columns are set). This class was
|
3. A class to represent partial data (e.g. for inserts or updates, where not all columns are set). This class was
|
||||||
introduced in moor 1.5 and is called a "companion".
|
introduced in moor 1.5 and is called a "companion".
|
||||||
|
@ -55,7 +55,7 @@ This approach lets us write a higher-level api that uses the generated `TableInf
|
||||||
write. For instance, the `Migrator` can write `CREATE TABLE` statements from these classes, an `UpdateStatement` will
|
write. For instance, the `Migrator` can write `CREATE TABLE` statements from these classes, an `UpdateStatement` will
|
||||||
write `UPDATE` statements and so on. To write the query, we construct a `GenerationContext`, which contains a string
|
write `UPDATE` statements and so on. To write the query, we construct a `GenerationContext`, which contains a string
|
||||||
buffer to write the query, keeps track of the introduced variables and so on. The idea is that everything that can
|
buffer to write the query, keeps track of the introduced variables and so on. The idea is that everything that can
|
||||||
appear anywhere in a sql statement inherits from `Component` (for instance, `Query`, `Expression`, `Variable`, `Where`,
|
appear anywhere in an SQL statement inherits from `Component` (for instance, `Query`, `Expression`, `Variable`, `Where`,
|
||||||
`OrderBy`). We can then recursively create the query by calling `Component.writeInto` for all subparts of a component.
|
`OrderBy`). We can then recursively create the query by calling `Component.writeInto` for all subparts of a component.
|
||||||
This query is then sent to a `QueryExecutor`, which is responsible for executing it and returning its result. The
|
This query is then sent to a `QueryExecutor`, which is responsible for executing it and returning its result. The
|
||||||
`QueryExecutor` is the only part that is platform specific, everything else is pure Dart that doesn't import any
|
`QueryExecutor` is the only part that is platform specific, everything else is pure Dart that doesn't import any
|
||||||
|
@ -63,7 +63,7 @@ restricted libraries.
|
||||||
|
|
||||||
### Important classes
|
### Important classes
|
||||||
A `DatabaseConnectionUser` is the central piece of a drift database instance. It contains an `SqlTypeSystem` (responsible
|
A `DatabaseConnectionUser` is the central piece of a drift database instance. It contains an `SqlTypeSystem` (responsible
|
||||||
for mapping simple Dart objects from and to sql), the `QueryExecutor` discussed above and a `StreamQueryStore`
|
for mapping simple Dart objects from and to SQL), the `QueryExecutor` discussed above and a `StreamQueryStore`
|
||||||
(responsible for keeping active queries and re-running them when a table updates). It is also the super class of
|
(responsible for keeping active queries and re-running them when a table updates). It is also the super class of
|
||||||
`GeneratedDatabase` and `DatabaseAccessor`, which are the classes a `@UseMoor` and `@UseDao` class inherits from.
|
`GeneratedDatabase` and `DatabaseAccessor`, which are the classes a `@UseMoor` and `@UseDao` class inherits from.
|
||||||
Finally, the `QueryEngine` is a mixin in `DatabaseConnectionUser` that provides the `select`, `update`, `delete` methods
|
Finally, the `QueryEngine` is a mixin in `DatabaseConnectionUser` that provides the `select`, `update`, `delete` methods
|
||||||
|
@ -119,7 +119,7 @@ updates that span multiple versions, we should follow these steps
|
||||||
2. `drift_dev`
|
2. `drift_dev`
|
||||||
3. (optional) `moor_flutter`
|
3. (optional) `moor_flutter`
|
||||||
|
|
||||||
The `sqlparser` library can be published independently from drift.
|
The `sqlparser` library can be published independently of drift.
|
||||||
|
|
||||||
### Building the documentation
|
### Building the documentation
|
||||||
|
|
||||||
|
|
16
README.md
16
README.md
|
@ -26,22 +26,22 @@ _Note: Moor has been renamed to drift_
|
||||||
| [![Main version](https://img.shields.io/pub/v/drift.svg)](https://pub.dev/packages/drift) | [![Generator version](https://img.shields.io/pub/v/drift_dev.svg)](https://pub.dev/packages/drift_dev) |
|
| [![Main version](https://img.shields.io/pub/v/drift.svg)](https://pub.dev/packages/drift) | [![Generator version](https://img.shields.io/pub/v/drift_dev.svg)](https://pub.dev/packages/drift_dev) |
|
||||||
|
|
||||||
Drift is a reactive persistence library for Flutter and Dart, built on top of
|
Drift is a reactive persistence library for Flutter and Dart, built on top of
|
||||||
sqlite.
|
SQLite.
|
||||||
Drift is
|
Drift is
|
||||||
|
|
||||||
- __Flexible__: Drift lets you write queries in both SQL and Dart,
|
- __Flexible__: Drift lets you write queries in both SQL and Dart,
|
||||||
providing fluent apis for both languages. You can filter and order results
|
providing fluent apis for both languages. You can filter and order results
|
||||||
or use joins to run queries on multiple tables. You can even use complex
|
or use joins to run queries on multiple tables. You can even use complex
|
||||||
sql features like `WITH` and `WINDOW` clauses.
|
SQL features like `WITH` and `WINDOW` clauses.
|
||||||
- __🔥 Feature rich__: Drift has builtin support for transactions, schema
|
- __🔥 Feature rich__: Drift has builtin support for transactions, schema
|
||||||
migrations, complex filters and expressions, batched updates and joins. We
|
migrations, complex filters and expressions, batched updates and joins. We
|
||||||
even have a builtin IDE for SQL!
|
even have a builtin IDE for SQL!
|
||||||
- __📦 Modular__: Thanks to builtin support for daos and `import`s in sql files, drift helps you keep your database code simple.
|
- __📦 Modular__: Thanks to builtin support for daos and `import`s in SQL files, drift helps you keep your database code simple.
|
||||||
- __🛡️ Safe__: Drift generates typesafe code based on your tables and queries. If you make a mistake in your queries, drift will find it at compile time and
|
- __🛡️ Safe__: Drift generates type-safe code based on your tables and queries. If you make a mistake in your queries, drift will find it at compile time and
|
||||||
provide helpful and descriptive lints.
|
provide helpful and descriptive lints.
|
||||||
- __⚡ Fast__: Even though drift lets you write powerful queries, it can keep
|
- __⚡ Fast__: Even though drift lets you write powerful queries, it can keep
|
||||||
up with the performance of key-value stores like shared preferences and Hive. Drift is the only major persistence library with builtin threading support, allowing you to run database code across isolates with zero additional effort.
|
up with the performance of key-value stores like shared preferences and Hive. Drift is the only major persistence library with builtin threading support, allowing you to run database code across isolates with zero additional effort.
|
||||||
- __Reactive__: Turn any sql query into an auto-updating stream! This includes complex queries across many tables
|
- __Reactive__: Turn any SQL query into an auto-updating stream! This includes complex queries across many tables
|
||||||
- __⚙️ Cross-Platform support__: Drift works on Android, iOS, macOS, Windows, Linux and the web. [This template](https://github.com/simolus3/drift/tree/develop/examples/app) is a Flutter todo app that works on all platforms.
|
- __⚙️ Cross-Platform support__: Drift works on Android, iOS, macOS, Windows, Linux and the web. [This template](https://github.com/simolus3/drift/tree/develop/examples/app) is a Flutter todo app that works on all platforms.
|
||||||
- __🗡️ Battle tested and production ready__: Drift is stable and well tested with a wide range of unit and integration tests. It powers production Flutter apps.
|
- __🗡️ Battle tested and production ready__: Drift is stable and well tested with a wide range of unit and integration tests. It powers production Flutter apps.
|
||||||
|
|
||||||
|
@ -58,10 +58,10 @@ project, I'd appreciate your [🌟 on GitHub](https://github.com/simolus3/drift/
|
||||||
This repository contains a number of packages making up the drift project, most
|
This repository contains a number of packages making up the drift project, most
|
||||||
notably:
|
notably:
|
||||||
|
|
||||||
- `drift`: The main runtime for drift, which provides most apis
|
- `drift`: The main runtime for drift, which provides most APIs.
|
||||||
- `drift_dev`: The compiler for drift tables, databases and daos. It
|
- `drift_dev`: The compiler for drift tables, databases and daos. It
|
||||||
also contains a fully-featured sql ide for the Dart analyzer.
|
also contains a fully-featured SQL IDE for the Dart analyzer.
|
||||||
- `sqlparser`: A sql parser and static analyzer, written in pure Dart. This package can be used without drift to perform analysis on sql statements.
|
- `sqlparser`: A SQL parser and static analyzer, written in pure Dart. This package can be used without drift to perform analysis on SQL statements.
|
||||||
It's on pub at
|
It's on pub at
|
||||||
[![sqlparser](https://img.shields.io/pub/v/sqlparser.svg)](https://pub.dev/packages/sqlparser)
|
[![sqlparser](https://img.shields.io/pub/v/sqlparser.svg)](https://pub.dev/packages/sqlparser)
|
||||||
|
|
||||||
|
|
|
@ -13,7 +13,7 @@ CREATE TABLE categories (
|
||||||
-- You can also create an index or triggers with drift files
|
-- You can also create an index or triggers with drift files
|
||||||
CREATE INDEX categories_description ON categories(description);
|
CREATE INDEX categories_description ON categories(description);
|
||||||
|
|
||||||
-- we can put named sql queries in here as well:
|
-- we can put named SQL queries in here as well:
|
||||||
createEntry: INSERT INTO todos (title, content) VALUES (:title, :content);
|
createEntry: INSERT INTO todos (title, content) VALUES (:title, :content);
|
||||||
deleteById: DELETE FROM todos WHERE id = :id;
|
deleteById: DELETE FROM todos WHERE id = :id;
|
||||||
allTodos: SELECT * FROM todos;
|
allTodos: SELECT * FROM todos;
|
||||||
|
|
|
@ -9,9 +9,9 @@ path: docs/getting-started/expressions/
|
||||||
template: layouts/docs/single
|
template: layouts/docs/single
|
||||||
---
|
---
|
||||||
|
|
||||||
Expressions are pieces of sql that return a value when the database interprets them.
|
Expressions are pieces of SQL that return a value when the database interprets them.
|
||||||
The Dart API from drift allows you to write most expressions in Dart and then convert
|
The Dart API from drift allows you to write most expressions in Dart and then convert
|
||||||
them to sql. Expressions are used in all kinds of situations. For instance, `where`
|
them to SQL. Expressions are used in all kinds of situations. For instance, `where`
|
||||||
expects an expression that returns a boolean.
|
expects an expression that returns a boolean.
|
||||||
|
|
||||||
In most cases, you're writing an expression that combines other expressions. Any
|
In most cases, you're writing an expression that combines other expressions. Any
|
||||||
|
@ -62,7 +62,7 @@ Expression.and([
|
||||||
## Arithmetic
|
## Arithmetic
|
||||||
|
|
||||||
For `int` and `double` expressions, you can use the `+`, `-`, `*` and `/` operators. To
|
For `int` and `double` expressions, you can use the `+`, `-`, `*` and `/` operators. To
|
||||||
run calculations between a sql expression and a Dart value, wrap it in a `Variable`:
|
run calculations between an SQL expression and a Dart value, wrap it in a `Variable`:
|
||||||
```dart
|
```dart
|
||||||
Future<List<Product>> canBeBought(int amount, int price) {
|
Future<List<Product>> canBeBought(int amount, int price) {
|
||||||
return (select(products)..where((p) {
|
return (select(products)..where((p) {
|
||||||
|
@ -73,7 +73,7 @@ Future<List<Product>> canBeBought(int amount, int price) {
|
||||||
```
|
```
|
||||||
|
|
||||||
String expressions define a `+` operator as well. Just like you would expect, it performs
|
String expressions define a `+` operator as well. Just like you would expect, it performs
|
||||||
a concatenation in sql.
|
a concatenation in SQL.
|
||||||
|
|
||||||
For integer values, you can use `~`, `bitwiseAnd` and `bitwiseOr` to perform
|
For integer values, you can use `~`, `bitwiseAnd` and `bitwiseOr` to perform
|
||||||
bitwise operations:
|
bitwise operations:
|
||||||
|
@ -81,7 +81,7 @@ bitwise operations:
|
||||||
{% include "blocks/snippet" snippets = snippets name = 'bitwise' %}
|
{% include "blocks/snippet" snippets = snippets name = 'bitwise' %}
|
||||||
|
|
||||||
## Nullability
|
## Nullability
|
||||||
To check whether an expression evaluates to `NULL` in sql, you can use the `isNull` extension:
|
To check whether an expression evaluates to `NULL` in SQL, you can use the `isNull` extension:
|
||||||
|
|
||||||
```dart
|
```dart
|
||||||
final withoutCategories = select(todos)..where((row) => row.category.isNull());
|
final withoutCategories = select(todos)..where((row) => row.category.isNull());
|
||||||
|
@ -213,7 +213,7 @@ with the `separator` argument on `groupConcat`.
|
||||||
## Mathematical functions and regexp
|
## Mathematical functions and regexp
|
||||||
|
|
||||||
When using a `NativeDatabase`, a basic set of trigonometric functions will be available.
|
When using a `NativeDatabase`, a basic set of trigonometric functions will be available.
|
||||||
It also defines the `REGEXP` function, which allows you to use `a REGEXP b` in sql queries.
|
It also defines the `REGEXP` function, which allows you to use `a REGEXP b` in SQL queries.
|
||||||
For more information, see the [list of functions]({{ "../Platforms/vm.md#moor-only-functions" | pageUrl }}) here.
|
For more information, see the [list of functions]({{ "../Platforms/vm.md#moor-only-functions" | pageUrl }}) here.
|
||||||
|
|
||||||
## Subqueries
|
## Subqueries
|
||||||
|
@ -261,8 +261,8 @@ Drift also supports subqueries that appear in `JOIN`s, which are described in th
|
||||||
[documentation for joins]({{ 'select.md#subqueries' | pageUrl }}).
|
[documentation for joins]({{ 'select.md#subqueries' | pageUrl }}).
|
||||||
|
|
||||||
## Custom expressions
|
## Custom expressions
|
||||||
If you want to inline custom sql into Dart queries, you can use a `CustomExpression` class.
|
If you want to inline custom SQL into Dart queries, you can use a `CustomExpression` class.
|
||||||
It takes a `sql` parameter that lets you write custom expressions:
|
It takes an `sql` parameter that lets you write custom expressions:
|
||||||
```dart
|
```dart
|
||||||
const inactive = CustomExpression<bool, BoolType>("julianday('now') - julianday(last_login) > 60");
|
const inactive = CustomExpression<bool, BoolType>("julianday('now') - julianday(last_login) > 60");
|
||||||
select(users)..where((u) => inactive);
|
select(users)..where((u) => inactive);
|
||||||
|
@ -270,5 +270,5 @@ select(users)..where((u) => inactive);
|
||||||
|
|
||||||
_Note_: It's easy to write invalid queries by using `CustomExpressions` too much. If you feel like
|
_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
|
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
|
to let us know. If you just prefer SQL, you could also take a look at
|
||||||
[compiled sql]({{ "../SQL API/custom_queries.md" | pageUrl }}) which is typesafe to use.
|
[compiled SQL]({{ "../SQL API/custom_queries.md" | pageUrl }}) which is type-safe to use.
|
||||||
|
|
|
@ -10,7 +10,7 @@ aliases:
|
||||||
|
|
||||||
{% assign snippets = 'package:drift_docs/snippets/modular/schema_inspection.dart.excerpt.json' | readString | json_decode %}
|
{% assign snippets = 'package:drift_docs/snippets/modular/schema_inspection.dart.excerpt.json' | readString | json_decode %}
|
||||||
|
|
||||||
Thanks to the typesafe table classes generated by drift, [writing SQL queries]({{ '../Dart API/select.md' | pageUrl }}) in Dart
|
Thanks to the type-safe table classes generated by drift, [writing SQL queries]({{ '../Dart API/select.md' | pageUrl }}) in Dart
|
||||||
is simple and safe.
|
is simple and safe.
|
||||||
However, these queries are usually written against a specific table. And while drift supports inheritance for tables, sometimes it is easier
|
However, these queries are usually written against a specific table. And while drift supports inheritance for tables, sometimes it is easier
|
||||||
to access tables reflectively. Luckily, code generated by drift implements interfaces which can be used to do just that.
|
to access tables reflectively. Luckily, code generated by drift implements interfaces which can be used to do just that.
|
||||||
|
|
|
@ -11,7 +11,7 @@ path: /docs/getting-started/advanced_dart_tables/
|
||||||
{% assign setup = 'package:drift_docs/snippets/setup/database.dart.excerpt.json' | readString | json_decode %}
|
{% assign setup = 'package:drift_docs/snippets/setup/database.dart.excerpt.json' | readString | json_decode %}
|
||||||
|
|
||||||
In relational databases, tables are used to describe the structure of rows. By
|
In relational databases, tables are used to describe the structure of rows. By
|
||||||
adhering to a predefined schema, drift can generate typesafe code for your
|
adhering to a predefined schema, drift can generate type-safe code for your
|
||||||
database.
|
database.
|
||||||
As already shown in the [setup]({{ '../setup.md#database-class' | pageUrl }})
|
As already shown in the [setup]({{ '../setup.md#database-class' | pageUrl }})
|
||||||
page, drift provides APIs to declare tables in Dart:
|
page, drift provides APIs to declare tables in Dart:
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
---
|
---
|
||||||
data:
|
data:
|
||||||
title: "Many to many relationships"
|
title: "Many-to-many relationships"
|
||||||
description: An example that models a shopping cart system with drift.
|
description: An example that models a shopping cart system with drift.
|
||||||
template: layouts/docs/single
|
template: layouts/docs/single
|
||||||
---
|
---
|
||||||
|
@ -19,16 +19,16 @@ A product can be in many shopping carts at the same time, and carts can of cours
|
||||||
contain more than one product too.
|
contain more than one product too.
|
||||||
|
|
||||||
In sqlite3, there are two good ways to model many-to-many relationships
|
In sqlite3, there are two good ways to model many-to-many relationships
|
||||||
betweeen tables:
|
between tables:
|
||||||
|
|
||||||
1. The traditional way of using a third table storing every combination of
|
1. The traditional way of using a third table storing every combination of
|
||||||
products and carts.
|
products and carts.
|
||||||
2. A more modern way might be to store product ids in a shopping cart as a JSON
|
2. A more modern way might be to store product IDs in a shopping cart as a JSON
|
||||||
array.
|
array.
|
||||||
|
|
||||||
The two approaches have different upsides and downsides. With the traditional
|
The two approaches have different upsides and downsides. With the traditional
|
||||||
relational way, it's easier to ensure data integrity (by, for instance, deleting
|
relational way, it's easier to ensure data integrity (by, for instance, deleting
|
||||||
product references out of shopping carts when they a product is deleted).
|
product references out of shopping carts when a product is deleted).
|
||||||
On the other hand, queries are easier to write with JSON structures. Especially
|
On the other hand, queries are easier to write with JSON structures. Especially
|
||||||
when the order of products in the shopping cart is important as well, a JSON
|
when the order of products in the shopping cart is important as well, a JSON
|
||||||
list is very helpful since rows in a table are unordered.
|
list is very helpful since rows in a table are unordered.
|
||||||
|
@ -109,11 +109,11 @@ in a single table:
|
||||||
|
|
||||||
To select a single cart, we can use the [`json_each`](https://sqlite.org/json1.html#jeach)
|
To select a single cart, we can use the [`json_each`](https://sqlite.org/json1.html#jeach)
|
||||||
function from sqlite3 to "join" each item stored in the JSON array as if it were a separate
|
function from sqlite3 to "join" each item stored in the JSON array as if it were a separate
|
||||||
row. That way, we can efficiently lookup all items in a cart:
|
row. That way, we can efficiently look up all items in a cart:
|
||||||
|
|
||||||
{% include "blocks/snippet" snippets=json name="watchCart" %}
|
{% include "blocks/snippet" snippets=json name="watchCart" %}
|
||||||
|
|
||||||
Watching all carts isn't that much harder, we just remove the `where` clause and
|
Watching all carts isn't that much harder, we just remove the `where` clause and
|
||||||
combine all rows into a map from carts to their items:
|
combine all rows into a map from carts to their items:
|
||||||
|
|
||||||
{% include "blocks/snippet" snippets=json name="watchAllCarts" %}
|
{% include "blocks/snippet" snippets=json name="watchAllCarts" %}
|
||||||
|
|
|
@ -25,7 +25,7 @@ the second section gives an example for a custom query defined at runtime.
|
||||||
|
|
||||||
## Statements with a generated api
|
## Statements with a generated api
|
||||||
|
|
||||||
You can instruct drift to automatically generate a typesafe
|
You can instruct drift to automatically generate a type-safe
|
||||||
API for your select, update and delete statements. Of course, you can still write custom
|
API for your select, update and delete statements. Of course, you can still write custom
|
||||||
sql manually. See the sections below for details.
|
sql manually. See the sections below for details.
|
||||||
|
|
||||||
|
@ -92,6 +92,6 @@ Of course, you can also use indexed variables (like `?12`) - for more informatio
|
||||||
|
|
||||||
## Custom update statements
|
## Custom update statements
|
||||||
For update and delete statements, you can use `customUpdate`. Just like `customSelect`, that method
|
For update and delete statements, you can use `customUpdate`. Just like `customSelect`, that method
|
||||||
also takes a sql statement and optional variables. You can also tell drift which tables will be
|
also takes an SQL statement and optional variables. You can also tell drift which tables will be
|
||||||
affected by your query using the optional `updates` parameter. That will help with other select
|
affected by your query using the optional `updates` parameter. That will help with other select
|
||||||
streams, which will then update automatically.
|
streams, which will then update automatically.
|
||||||
|
|
|
@ -22,7 +22,7 @@ template: layouts/docs/single
|
||||||
Drift files are a new feature that lets you write all your database code in SQL.
|
Drift files are a new feature that lets you write all your database code in SQL.
|
||||||
But unlike raw SQL strings you might pass to simple database clients, everything in a drift file is verified
|
But unlike raw SQL strings you might pass to simple database clients, everything in a drift file is verified
|
||||||
by drift's powerful SQL analyzer.
|
by drift's powerful SQL analyzer.
|
||||||
This allows you to write SQL queries safer: Drift will find mistakes in them during builds, and it will generate typesafe
|
This allows you to write SQL queries safer: Drift will find mistakes in them during builds, and it will generate type-safe
|
||||||
Dart APIs for them so that you don't have to read back results manually.
|
Dart APIs for them so that you don't have to read back results manually.
|
||||||
|
|
||||||
## Getting started
|
## Getting started
|
||||||
|
@ -63,7 +63,7 @@ Inside of named queries, you can use variables just like you would expect with
|
||||||
sql. We support regular variables (`?`), explicitly indexed variables (`?123`)
|
sql. We support regular variables (`?`), explicitly indexed variables (`?123`)
|
||||||
and colon-named variables (`:id`). We don't support variables declared
|
and colon-named variables (`:id`). We don't support variables declared
|
||||||
with @ or $. The compiler will attempt to infer the variable's type by
|
with @ or $. The compiler will attempt to infer the variable's type by
|
||||||
looking at its context. This lets drift generate typesafe apis for your
|
looking at its context. This lets drift generate type-safe APIs for your
|
||||||
queries, the variables will be written as parameters to your method.
|
queries, the variables will be written as parameters to your method.
|
||||||
|
|
||||||
When it's ambiguous, the analyzer might be unable to resolve the type of
|
When it's ambiguous, the analyzer might be unable to resolve the type of
|
||||||
|
@ -476,4 +476,4 @@ At the moment, the following statements can appear in a `.drift` file.
|
||||||
All imports must come before DDL statements, and those must come before named queries.
|
All imports must come before DDL statements, and those must come before named queries.
|
||||||
|
|
||||||
If you need support for another statement, or if drift rejects a query you think is valid, please
|
If you need support for another statement, or if drift rejects a query you think is valid, please
|
||||||
create an issue!
|
create an issue!
|
||||||
|
|
|
@ -124,7 +124,7 @@ Sqflite is a Flutter package that provides bindings to the sqlite api for both i
|
||||||
and has stable api. In fact, the `moor_flutter` or `drift_sqflite` variants are built on top of sqflite. But even though sqflite
|
and has stable api. In fact, the `moor_flutter` or `drift_sqflite` variants are built on top of sqflite. But even though sqflite
|
||||||
has an api to construct some simple queries in Dart, drift goes a bit further by
|
has an api to construct some simple queries in Dart, drift goes a bit further by
|
||||||
|
|
||||||
* Generating typesafe mapping code for your queries
|
* Generating type-safe mapping code for your queries
|
||||||
* Providing auto-updating streams for queries
|
* Providing auto-updating streams for queries
|
||||||
* Managing `CREATE TABLE` statements and most schema migrations
|
* Managing `CREATE TABLE` statements and most schema migrations
|
||||||
* A more fluent api to compose queries
|
* A more fluent api to compose queries
|
||||||
|
|
|
@ -11,20 +11,20 @@ Drift is a reactive persistence library for Dart and Flutter applications. It's
|
||||||
of database libraries like [the sqlite3 package](https://pub.dev/packages/sqlite3), [sqflite](https://pub.dev/packages/sqflite) or [sql.js](https://github.com/sql-js/sql.js/)
|
of database libraries like [the sqlite3 package](https://pub.dev/packages/sqlite3), [sqflite](https://pub.dev/packages/sqflite) or [sql.js](https://github.com/sql-js/sql.js/)
|
||||||
and provides additional features, like:
|
and provides additional features, like:
|
||||||
|
|
||||||
- __Type safety__: Instead of writing sql queries manually and parsing the `List<Map<String, dynamic>>` that they
|
- __Type safety__: Instead of writing SQL queries manually and parsing the `List<Map<String, dynamic>>` that they
|
||||||
return, drift turns rows into objects of your choice.
|
return, drift turns rows into objects of your choice.
|
||||||
- __Stream queries__: Drift lets you "watch" your queries with zero additional effort. Any query can be turned into
|
- __Stream queries__: Drift lets you "watch" your queries with zero additional effort. Any query can be turned into
|
||||||
an auto-updating stream that emits new items when the underlying data changes.
|
an auto-updating stream that emits new items when the underlying data changes.
|
||||||
- __Fluent queries__: Drift generates a Dart api that you can use to write queries and automatically get their results.
|
- __Fluent queries__: Drift generates a Dart api that you can use to write queries and automatically get their results.
|
||||||
Keep an updated list of all users with `select(users).watch()`. That's it! No sql to write, no rows to parse.
|
Keep an updated list of all users with `select(users).watch()`. That's it! No SQL to write, no rows to parse.
|
||||||
- __Typesafe sql__: If you prefer to write sql, that's fine! Drift has an sql parser and analyzer built in. It can parse
|
- __Type-safe SQL__: If you prefer to write SQL, that's fine! Drift has an SQL parser and analyzer built in. It can parse
|
||||||
your queries at compile time, figure out what columns they're going to return and generate Dart code to represent your
|
your queries at compile time, figure out what columns they're going to return and generate Dart code to represent your
|
||||||
rows.
|
rows.
|
||||||
- __Migration utils__: Drift makes writing migrations easier thanks to utility functions like `.createAllTables()`.
|
- __Migration utils__: Drift makes writing migrations easier thanks to utility functions like `.createAllTables()`.
|
||||||
You don't need to manually write your `CREATE TABLE` statements and keep them updated.
|
You don't need to manually write your `CREATE TABLE` statements and keep them updated.
|
||||||
|
|
||||||
And much more! Drift validates data before inserting it, so you can get helpful error messages instead of just an
|
And much more! Drift validates data before inserting it, so you can get helpful error messages instead of just an
|
||||||
sql error code. Of course, it supports transactions. And DAOs. And efficient batched insert statements. The list goes on.
|
SQL error code. Of course, it supports transactions. And DAOs. And efficient batched insert statements. The list goes on.
|
||||||
|
|
||||||
## Getting started
|
## Getting started
|
||||||
|
|
||||||
|
|
|
@ -26,7 +26,7 @@ If you want to look at an example app for inspiration, a cross-platform Flutter
|
||||||
|
|
||||||
## The dependencies {#adding-dependencies}
|
## The dependencies {#adding-dependencies}
|
||||||
|
|
||||||
First, lets add drift to your project's `pubspec.yaml`.
|
First, let's add drift to your project's `pubspec.yaml`.
|
||||||
In addition to the core drift dependencies, we're also adding packages to find a suitable database
|
In addition to the core drift dependencies, we're also adding packages to find a suitable database
|
||||||
location on the device and to include a recent version of `sqlite3`, the database most commonly
|
location on the device and to include a recent version of `sqlite3`, the database most commonly
|
||||||
used with drift.
|
used with drift.
|
||||||
|
@ -66,7 +66,7 @@ If you're wondering why so many packages are necessary, here's a quick overview
|
||||||
## Database class
|
## Database class
|
||||||
|
|
||||||
Every project using drift needs at least one class to access a database. This class references all the
|
Every project using drift needs at least one class to access a database. This class references all the
|
||||||
tables you want to use and is the central entrypoint for drift's code generator.
|
tables you want to use and is the central entry point for drift's code generator.
|
||||||
In this example, we'll assume that this database class is defined in a file called `database.dart` and
|
In this example, we'll assume that this database class is defined in a file called `database.dart` and
|
||||||
somewhere under `lib/`. Of course, you can put this class in any Dart file you like.
|
somewhere under `lib/`. Of course, you can put this class in any Dart file you like.
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
---
|
---
|
||||||
page:
|
page:
|
||||||
title: "Drift - Reactive, typesafe persistence library for Dart"
|
title: "Drift - Reactive, type-safe persistence library for Dart"
|
||||||
template: layouts/home.html
|
template: layouts/home.html
|
||||||
path: ""
|
path: ""
|
||||||
data:
|
data:
|
||||||
|
@ -57,7 +57,7 @@ between all your revisions.
|
||||||
|
|
||||||
{% block "blocks/feature.html" icon="fas fa-database" title="Prefer SQL? Drift's got you covered!" %}
|
{% block "blocks/feature.html" icon="fas fa-database" title="Prefer SQL? Drift's got you covered!" %}
|
||||||
{% block "blocks/markdown.html" %}
|
{% block "blocks/markdown.html" %}
|
||||||
Drift ships a powerful sql parser and analyzer, allowing it to create typesafe methods for all your sql queries. All sql queries are
|
Drift ships a powerful SQL parser and analyzer, allowing it to create type-safe methods for all your SQL queries. All SQL queries are
|
||||||
validated and analyzed during build-time, so drift can provide hints about potential errors quickly and generate efficient mapping
|
validated and analyzed during build-time, so drift can provide hints about potential errors quickly and generate efficient mapping
|
||||||
code.
|
code.
|
||||||
Of course, you can mix SQL and Dart to your liking.
|
Of course, you can mix SQL and Dart to your liking.
|
||||||
|
|
|
@ -32,7 +32,7 @@ more flexibility when writing database code.
|
||||||
{% block "blocks/section" color="light" %}
|
{% block "blocks/section" color="light" %}
|
||||||
{% block "blocks/feature" icon="fas fa-database" title="Pure SQL API" %} {% block "blocks/markdown" %}
|
{% block "blocks/feature" icon="fas fa-database" title="Pure SQL API" %} {% block "blocks/markdown" %}
|
||||||
The new `.moor` files have been updated and can now hold both `CREATE TABLE` statements
|
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 queries you define. Moor will then generate type-safe Dart APIs based on your tables
|
||||||
and statements.
|
and statements.
|
||||||
|
|
||||||
[Get started with SQL and moor]({{ "docs/SQL API/index.md" | pageUrl }})
|
[Get started with SQL and moor]({{ "docs/SQL API/index.md" | pageUrl }})
|
||||||
|
@ -55,7 +55,7 @@ worlds.
|
||||||
{% block "blocks/lead" color="green" %} {% block "blocks/markdown" %}
|
{% block "blocks/lead" color="green" %} {% block "blocks/markdown" %}
|
||||||
## Builtin SQL IDE
|
## Builtin SQL IDE
|
||||||
|
|
||||||
Moor 2.0 expands the previous sql parser and analyzer, providing real-time feedback on your
|
Moor 2.0 expands the previous SQL parser and analyzer, providing real-time feedback on your
|
||||||
SQL queries as you type. Moor plugs right into the Dart analysis server, so you don't have
|
SQL queries as you type. Moor plugs right into the Dart analysis server, so you don't have
|
||||||
to install any additional extensions.
|
to install any additional extensions.
|
||||||
|
|
||||||
|
@ -113,4 +113,4 @@ _Please not that the package is still in preview_
|
||||||
- To get started with SQL in moor, or to migrate an existing project to moor, follow our
|
- To get started with SQL in moor, or to migrate an existing project to moor, follow our
|
||||||
[migration guide]({{ "docs/SQL API/index.md" | pageUrl }})
|
[migration guide]({{ "docs/SQL API/index.md" | pageUrl }})
|
||||||
|
|
||||||
{% endblock %} {% endblock %}
|
{% endblock %} {% endblock %}
|
||||||
|
|
|
@ -15,22 +15,22 @@
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
Drift is a reactive persistence library for Flutter and Dart, built on top of
|
Drift is a reactive persistence library for Flutter and Dart, built on top of
|
||||||
sqlite.
|
SQLite.
|
||||||
Drift is
|
Drift is
|
||||||
|
|
||||||
- __Flexible__: Drift lets you write queries in both SQL and Dart,
|
- __Flexible__: Drift lets you write queries in both SQL and Dart,
|
||||||
providing fluent apis for both languages. You can filter and order results
|
providing fluent apis for both languages. You can filter and order results
|
||||||
or use joins to run queries on multiple tables. You can even use complex
|
or use joins to run queries on multiple tables. You can even use complex
|
||||||
sql features like `WITH` and `WINDOW` clauses.
|
SQL features like `WITH` and `WINDOW` clauses.
|
||||||
- __🔥 Feature rich__: Drift has builtin support for transactions, schema
|
- __🔥 Feature rich__: Drift has builtin support for transactions, schema
|
||||||
migrations, complex filters and expressions, batched updates and joins. We
|
migrations, complex filters and expressions, batched updates and joins. We
|
||||||
even have a builtin IDE for SQL!
|
even have a builtin IDE for SQL!
|
||||||
- __📦 Modular__: Thanks to builtin support for daos and `import`s in sql files, drift helps you keep your database code simple.
|
- __📦 Modular__: Thanks to builtin support for daos and `import`s in SQL files, drift helps you keep your database code simple.
|
||||||
- __🛡️ Safe__: Drift generates typesafe code based on your tables and queries. If you make a mistake in your queries, drift will find it at compile time and
|
- __🛡️ Safe__: Drift generates type-safe code based on your tables and queries. If you make a mistake in your queries, drift will find it at compile time and
|
||||||
provide helpful and descriptive lints.
|
provide helpful and descriptive lints.
|
||||||
- __⚡ Fast__: Even though drift lets you write powerful queries, it can keep
|
- __⚡ Fast__: Even though drift lets you write powerful queries, it can keep
|
||||||
up with the performance of key-value stores. Drift is the only major persistence library with builtin threading support, allowing you to run database code across isolates with zero additional effort.
|
up with the performance of key-value stores. Drift is the only major persistence library with builtin threading support, allowing you to run database code across isolates with zero additional effort.
|
||||||
- __Reactive__: Turn any sql query into an auto-updating stream! This includes complex queries across many tables
|
- __Reactive__: Turn any SQL query into an auto-updating stream! This includes complex queries across many tables
|
||||||
- __⚙️ Cross-Platform support__: Drift works on Android, iOS, macOS, Windows, Linux and [the web](https://drift.simonbinder.eu/web). [This template](https://github.com/simolus3/drift/tree/develop/examples/app) is a Flutter todo app that works on all platforms
|
- __⚙️ Cross-Platform support__: Drift works on Android, iOS, macOS, Windows, Linux and [the web](https://drift.simonbinder.eu/web). [This template](https://github.com/simolus3/drift/tree/develop/examples/app) is a Flutter todo app that works on all platforms
|
||||||
- __🗡️ Battle tested and production ready__: Drift is stable and well tested with a wide range of unit and integration tests. It powers production Flutter apps.
|
- __🗡️ Battle tested and production ready__: Drift is stable and well tested with a wide range of unit and integration tests. It powers production Flutter apps.
|
||||||
|
|
||||||
|
|
|
@ -1,16 +1,16 @@
|
||||||
# sqlparser
|
# sqlparser
|
||||||
|
|
||||||
Sql parser and static analyzer written in Dart. At the moment, this library targets the
|
SQL parser and static analyzer written in Dart. At the moment, this library targets the
|
||||||
sqlite dialect only.
|
SQLite dialect only.
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
This library aims to support every sqlite feature, which includes parsing and detailed
|
This library aims to support every SQLite feature, which includes parsing and detailed
|
||||||
static analysis.
|
static analysis.
|
||||||
We can resolve what type a column in a `SELECT` statement has, infer types for variables,
|
We can resolve what type a column in a `SELECT` statement has, infer types for variables,
|
||||||
find semantic errors and more.
|
find semantic errors and more.
|
||||||
|
|
||||||
This library supports most sqlite features:
|
This library supports most SQLite features:
|
||||||
- DQL: Full support, including joins, `group by`, nested and compound selects, `WITH` clauses
|
- DQL: Full support, including joins, `group by`, nested and compound selects, `WITH` clauses
|
||||||
and window functions
|
and window functions
|
||||||
- DDL: Supports `CREATE TABLE` statements, including advanced features like foreign keys or
|
- DDL: Supports `CREATE TABLE` statements, including advanced features like foreign keys or
|
||||||
|
@ -18,7 +18,7 @@ This library supports most sqlite features:
|
||||||
`CREATE TRIGGER` and `CREATE INDEX` statements.
|
`CREATE TRIGGER` and `CREATE INDEX` statements.
|
||||||
|
|
||||||
### Using the parser
|
### Using the parser
|
||||||
To obtain an abstract syntax tree from an sql statement, use `SqlEngine.parse`.
|
To obtain an abstract syntax tree from an SQL statement, use `SqlEngine.parse`.
|
||||||
```dart
|
```dart
|
||||||
import 'package:sqlparser/sqlparser.dart';
|
import 'package:sqlparser/sqlparser.dart';
|
||||||
|
|
||||||
|
@ -35,11 +35,11 @@ LIMIT 5 OFFSET 5 * 3
|
||||||
```
|
```
|
||||||
|
|
||||||
### Analysis
|
### Analysis
|
||||||
Given information about all tables and a sql statement, this library can:
|
Given information about all tables and an SQL statement, this library can:
|
||||||
|
|
||||||
1. Determine which result columns a query is going to have, including types and nullability
|
1. Determine which result columns a query is going to have, including types and nullability
|
||||||
2. Make an educated guess about what type the variables in the query should have (it's not really
|
2. Make an educated guess about what type the variables in the query should have (it's not really
|
||||||
possible to be 100% accurate about this because sqlite is very flexible at types, but this library
|
possible to be 100% accurate about this because SQLite is very flexible at types, but this library
|
||||||
gets it mostly right)
|
gets it mostly right)
|
||||||
3. Issue basic warnings about queries that are syntactically valid but won't run (references unknown
|
3. Issue basic warnings about queries that are syntactically valid but won't run (references unknown
|
||||||
tables / columns, uses undefined functions, etc.)
|
tables / columns, uses undefined functions, etc.)
|
||||||
|
@ -70,7 +70,7 @@ resolvedColumns.map((c) => context.typeOf(c).type.type); // int, text, int, text
|
||||||
|
|
||||||
## But why?
|
## But why?
|
||||||
[Drift](https://pub.dev/packages/drift), a persistence library for Dart apps, uses this
|
[Drift](https://pub.dev/packages/drift), a persistence library for Dart apps, uses this
|
||||||
package to generate type-safe methods from sql.
|
package to generate type-safe methods from SQL.
|
||||||
|
|
||||||
## Thanks
|
## Thanks
|
||||||
- To [Bob Nystrom](https://github.com/munificent) for his amazing ["Crafting Interpreters"](https://craftinginterpreters.com/)
|
- To [Bob Nystrom](https://github.com/munificent) for his amazing ["Crafting Interpreters"](https://craftinginterpreters.com/)
|
||||||
|
|
Loading…
Reference in New Issue