|
|
|
|
@ -1,8 +1,9 @@
|
|
|
|
|
# Contributing
|
|
|
|
|
|
|
|
|
|
Thanks for taking the time to contribute to moor!
|
|
|
|
|
Thanks for taking the time to contribute to drift!
|
|
|
|
|
|
|
|
|
|
## Reporting issues
|
|
|
|
|
|
|
|
|
|
Feel free to post any questions, bug reports or feature requests by creating an issue.
|
|
|
|
|
In any case, taking the time to provide some context on
|
|
|
|
|
- what you were trying to do
|
|
|
|
|
@ -15,27 +16,28 @@ most certainly helps to resolve the issue quickly.
|
|
|
|
|
All kinds of pull requests are absolutely appreciated! Before working on bigger changes, it
|
|
|
|
|
can be helpful to create an issue describing your plans to help coordination.
|
|
|
|
|
|
|
|
|
|
When working on moor, its recommended to fork the `develop` branch and also target that
|
|
|
|
|
branch for PRs. When possible, we only use the `master` branch to reflect the state that's
|
|
|
|
|
been released to pub.
|
|
|
|
|
When working on drift, its recommended to fork the `develop` branch and also target that
|
|
|
|
|
branch for PRs. When possible, we only use the `latest_release` branch to reflect the state
|
|
|
|
|
that's been released to pub.
|
|
|
|
|
|
|
|
|
|
If you have any question about moor internals that you feel are not explained well enough,
|
|
|
|
|
If you have any question about drift internals that you feel are not explained well enough,
|
|
|
|
|
you're most welcome to create an issue or [chat via gitter](https://gitter.im/moor-dart/community).
|
|
|
|
|
|
|
|
|
|
## Project structure
|
|
|
|
|
The project is divided into multiple modules:
|
|
|
|
|
|
|
|
|
|
- `moor/`: Contains common APIs that will run on all platforms.
|
|
|
|
|
- `drift/`: Contains common APIs that will run on all platforms.
|
|
|
|
|
- `backends`: Common helper classes to make implementing backends easier. The idea is that a
|
|
|
|
|
backend only needs to know how to run prepared statements. This lets us port the library to
|
|
|
|
|
different database libraries without much trouble.
|
|
|
|
|
- `moor_web`: Experimental web implementation, built with `sql.js`.
|
|
|
|
|
- This is the biggest module, see the concepts section below on how moor works and what it
|
|
|
|
|
- `web.dart`: Experimental web implementation, built with `sql.js`.
|
|
|
|
|
- `native.dart`: FFI-based implementation around the `sqlite3` package.
|
|
|
|
|
- This is the biggest package, see the concepts section below on how drift works and what it
|
|
|
|
|
contains.
|
|
|
|
|
- `moor_flutter/`: Contains a Flutter implementation for the database.
|
|
|
|
|
- `moor_generator/`: 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.
|
|
|
|
|
- `sqlparser/`: Contains an sql parser and analyzer that is fairly independent of moor,
|
|
|
|
|
- `sqlparser/`: Contains an sql parser and analyzer that is mostly independent of drift,
|
|
|
|
|
but used by the generator for compiled custom queries.
|
|
|
|
|
|
|
|
|
|
## Concepts
|
|
|
|
|
@ -49,7 +51,7 @@ we generate three classes:
|
|
|
|
|
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".
|
|
|
|
|
|
|
|
|
|
This approach lets us write a higher-level api that uses the generated `TableInfo` classes to know what columns to
|
|
|
|
|
This approach lets us write a higher-level api that uses the generated `TableInfo` classes to know what columns to
|
|
|
|
|
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
|
|
|
|
|
buffer to write the query, keeps track of the introduced variables and so on. The idea is that everything that can
|
|
|
|
|
@ -60,8 +62,8 @@ This query is then sent to a `QueryExecutor`, which is responsible for executing
|
|
|
|
|
restricted libraries.
|
|
|
|
|
|
|
|
|
|
### Important classes
|
|
|
|
|
A `DatabaseConnectionUser` is the central piece of a moor database instance. It contains an `SqlTypeSystem` (responsible
|
|
|
|
|
for mapping simple Dart objects from and to sql), the `QueryExecutor` discussed above and a `StreamQueryStore`
|
|
|
|
|
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`
|
|
|
|
|
(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.
|
|
|
|
|
Finally, the `QueryEngine` is a mixin in `DatabaseConnectionUser` that provides the `select`, `update`, `delete` methods
|
|
|
|
|
@ -80,8 +82,8 @@ Note: Port 9999 has to be free for this to work, but you can change the
|
|
|
|
|
port defined in the two files below.
|
|
|
|
|
|
|
|
|
|
To debug the plugin, do the following:
|
|
|
|
|
1. In `moor/tools/analyzer_plugin/bin/plugin.dart`, set `useDebuggingVariant` to true.
|
|
|
|
|
2. Run `moor_generator/bin/moor_generator.dart debug-plugin` as a regular Dart VM app
|
|
|
|
|
1. In `drift/tools/analyzer_plugin/bin/plugin.dart`, set `useDebuggingVariant` to true.
|
|
|
|
|
2. Run `drift_dev/tool/debug_plugin.dart` as a regular Dart VM app
|
|
|
|
|
(this can be debugged when started from an IDE).
|
|
|
|
|
3. (optional) Make sure the analysis server picks up the updated version of the analysis
|
|
|
|
|
plugin by deleting the `~/.dartServer/.plugin_manager` folder.
|
|
|
|
|
@ -91,7 +93,7 @@ More details are available under `extras/plugin_example/README.md`.
|
|
|
|
|
|
|
|
|
|
### Debugging the builder
|
|
|
|
|
|
|
|
|
|
To debug the builder, run `pub run build_runner generate-build-script` in the `moor`
|
|
|
|
|
To debug the builder, run `pub run build_runner generate-build-script` in the `drift`
|
|
|
|
|
subdirectory (or any other directory you want to use as an input). This will generate
|
|
|
|
|
a `.dart_tool/build/entrypoint/build.dart`. That file can be run and debugged as a
|
|
|
|
|
regular Dart VM app. Be sure to pass something like `build -v` as program arguments
|
|
|
|
|
@ -101,26 +103,25 @@ and use the input package as a working directory.
|
|
|
|
|
Minor changes will be published directly, no special steps are necessary. For major
|
|
|
|
|
updates that span multiple versions, we should follow these steps
|
|
|
|
|
|
|
|
|
|
1. Changelogs: For new updates, we use the same `CHANGELOG` for `moor` and `moor_flutter`. This
|
|
|
|
|
is because most changes happen with moor directly, but users are most likely depending on the
|
|
|
|
|
Flutter version only. The changelog for the generator should only point out relevant changes to
|
|
|
|
|
the generator.
|
|
|
|
|
2. Make sure each package has the correct dependencies: `moor_flutter` version `1.x` should depend
|
|
|
|
|
on moor `1.x` as well to ensure users will always `pub get` moor packages that are compatible
|
|
|
|
|
1. Changelogs: The changelog of `drift_dev` should only mention changes to the generator,
|
|
|
|
|
most changes shuold be in `drift/CHANGELOG.md`. Generator changes should also be copied
|
|
|
|
|
into that file.
|
|
|
|
|
2. Make sure each package has the correct dependencies: `drift_dev` version `1.x` should depend
|
|
|
|
|
on `drift` `1.x` as well to ensure users will always `pub get` drift packages that are compatible
|
|
|
|
|
with each other.
|
|
|
|
|
3. Comment out the `dependency_overrides` section in `moor`, `moor/tool/analyzer_plugin`, `moor_flutter`,
|
|
|
|
|
`moor_generator` and `sqlparser`. Make sure that `useDebuggingVariant` is false in the
|
|
|
|
|
3. Comment out the `dependency_overrides` section in `drift`, `drift/tool/analyzer_plugin`, `moor_flutter`,
|
|
|
|
|
`drift_dev` and `sqlparser`. Make sure that `useDebuggingVariant` is false in the
|
|
|
|
|
analyzer plugin.
|
|
|
|
|
4. Publish packages in this order to avoid scoring penalties caused by versions not existing:
|
|
|
|
|
1. `moor`
|
|
|
|
|
2. `moor_generator`
|
|
|
|
|
3. `moor_flutter`
|
|
|
|
|
|
|
|
|
|
The `sqlparser` library can be published independently from moor.
|
|
|
|
|
4. Create an annotated tag and a GitHub release for each package published. `drift` and `drift_dev` can be
|
|
|
|
|
merged into a single GitHub release.
|
|
|
|
|
5. Publish packages in this order to avoid scoring penalties caused by versions not existing:
|
|
|
|
|
1. `drift`
|
|
|
|
|
2. `drift_dev`
|
|
|
|
|
3. (optional) `moor_flutter`
|
|
|
|
|
|
|
|
|
|
Significant updates to more than one package, or updates to the `moor` package, should get
|
|
|
|
|
their own tag in git!
|
|
|
|
|
The `sqlparser` library can be published independently from drift.
|
|
|
|
|
|
|
|
|
|
### Building the documentation
|
|
|
|
|
We use hugo and docsy to build the documentation. The [readme](docs/README.md) contains everything
|
|
|
|
|
you need to know go get started.
|
|
|
|
|
|
|
|
|
|
We use `build_runner` to build the documentation. The [readme](docs/README.md) contains everything
|
|
|
|
|
you need to know go get started.
|
|
|
|
|
|
Simon Binder