Builder options
The moor_generator
package has some options that control how the
code is generated. Note that, in most cases, the default settings
should be sufficient. See the section on recommended settings below.
To use the options, create a build.yaml
file in the root of your project (e.g. next
to your pubspec.yaml
):
# build.yaml. This file is quite powerful, see https://pub.dev/packages/build_config
targets:
$default:
builders:
moor_generator:
options:
compact_query_methods: true
Available options
At the moment, moor supports these options:
write_from_json_string_constructor
: boolean. Adds a.fromJsonString
factory constructor to generated data classes. By default, we only write a.fromJson
constructor that takes aMap<String, dynamic>
.override_hash_and_equals_in_result_sets
: boolean. When moor generates another class to hold the result of generated select queries, this flag controls whether moor should overrideoperator ==
andhashCode
in those classes. In recent versions, it will also overridetoString
if this option is enabled.compact_query_methods
(defaults totrue
): For queries declared on a@UseMoor
or@UseDao
annotation, moor used to generate three methods: A base method returning aSelectable
and then two helper methods returning aStream
or aFuture
. As theSelectable
class contains its own methods to convert it to aStream
andFuture
, the two later methods only exist for backwards compatibility. When this flag is enabled, moor won’t write them at all. This flag is enabled by default in moor 3.0, but it can still be disabled.skip_verification_code
: Generated tables contain a significant chunk of code to verify integrity of inserted data and report detailed errors when the integrity is violated. If you’re only using inserts with SQL, or don’t need this functionality, enabling this flag can help to reduce the amount generated code.use_data_class_name_for_companions
: By default, the name for companion classes is based on the table name (e.g. a@DataClassName('Users') class UsersTable extends Table
would generate aUsersTableCompanion
). With this option, the name is based on the data class (soUsersCompanion
in this case).use_column_name_as_json_key_when_defined_in_moor_file
(defaults totrue
): When serializing columns declared inside a.moor
file from and to json, use their sql name instead of the generated Dart getter name (so a column nameduser_name
would also useuser_name
as a json key instead ofuserName
). You can always override the json key by using aJSON KEY
column constraint (e.g.user_name VARCHAR NOT NULL JSON KEY userName
)generate_connect_constructor
: Generate necessary code to support the isolate runtime. This is a build option because isolates are still experimental. This will be the default option eventually.sqlite_modules
: This list can be used to enable sqlite extensions, like those for json or full-text search. Modules have to be enabled explicitly because they’re not supported on all platforms. See the following section for details.eagerly_load_dart_ast
: Moor’s builder will load the resolved AST whenever it encounters a Dart file, instead of lazily when it reads a table. This is used to investigate rare builder crashes.data_class_to_companions
(defaults totrue
): Controls whether moor will write thetoCompanion
method in generated data classes.mutable_classes
(defaults tofalse
): The fields generated in generated data, companion and result set classes are final by default. You can make them mutable by settingmutable_classes: true
.raw_result_set_data
: The generator will expose the underlyingQueryRow
for generated result set classesapply_converters_on_variables
: Applies type converters to variables in compiled statements.generate_values_in_copy_with
: Generates aValue<T?>
instead ofT?
for nullable columns incopyWith
. This allows to set columns back to null (by usingValue(null)
). Passingnull
was ignored before, making it impossible to set columns tonull
.named_parameters
: Generates named parameters for named variables in SQL queries.new_sql_code_generation
: Generates SQL statements from the parsed AST instead of replacing substrings. This will also remove unecessary whitespace and comments. If enabling this option breaks your queries, please file an issue!
Available extensions
Note: This enables extensions in the analyzer for custom queries only. For instance, when the json1
extension is
enabled, the json
functions can be used in moor files. This doesn’t necessarily
mean that those functions are supported at runtime! Both extensions are available on iOS 11 or later. On Android, they’re
only available when using moor_ffi
. See our docs for more details on them.
targets:
$default:
builders:
moor_generator:
options:
sqlite_modules:
- json1
- fts5
- moor_ffi
We currently support the following extensions:
- json1: Support static analysis for
json_
functions in moor files - fts5: Support
CREATE VIRTUAL TABLE
statements forfts5
tables and theMATCH
operator. Functions likehighlight
orbm25
are available as well. moor_ffi
: Enables support for functions that are only available when usingmoor_ffi
. This containspow
,sqrt
and a variety of trigonometric functions. Details on those functions are available here.
Recommended options
In general, we recommend using the default options. However, some options will be enabled by default in a future moor release. At the moment, they’re opt-in to not break existing users. These options are:
apply_converters_on_variables
generate_values_in_copy_with
new_sql_code_generation
We recommend enabling these options.
You can disable some default moor features and reduce the amount of generated code with the following options:
skip_verification_code: true
: You can remove a significant portion of generated code with this option. The downside is that error messages when inserting invalid data will be less specific.data_class_to_companions: false
: Don’t generate thetoCompanion
method on data classes. If you don’t need that method, you can disable this option.
Using moor classes in other builders
Starting with moor 2.4, it’s possible to use classes generated by moor in other builders.
Due to technicalities related to Dart’s build system and source_gen
, this approach requires a custom configuration
and minor code changes. Put this content in a file called build.yaml
next to your pubspec.yaml
:
targets:
$default:
builders:
# disable the default generators, we'll only use the non-shared moor generator here
auto_apply_builders: false
moor_generator|moor_generator_not_shared:
enabled: true
# If needed, you can configure the builder like this:
# options:
# skip_verification_code: true
# use_experimental_inference: true
# This builder is necessary for moor-file preprocessing. You can disable it if you're not
# using .moor files with type converters.
moor_generator|preparing_builder:
enabled: true
run_built_value:
dependencies: ['your_package_name']
builders:
# Disable moor builders. By default, those would run on each target
moor_generator:
enabled: false
moor_generator|preparing_builder:
enabled: false
# we don't need to disable moor_generator_not_shared, because it's disabled by default
In all files that use generated moor code, you’ll have to replace part 'filename.g.dart'
with part 'filename.moor.dart'
.
If you use moor and another builder in the same file, you’ll need both .g.dart
and .moor.dart
as part-files.
A full example is available as part of the moor repo.
If you run into any problems with this approach, feel free to open an issue on moor. At the moment, a known issue is that
other builders can emit a warning about missing part
statements in the .moor.dart
file generated by moor. This shouldn’t
affect the generated code and has been reported here.
The technicalities, explained
Almost all code generation packages use a so called “shared part file” approach provided by source_gen
.
It’s a common protocol that allows unrelated builders to write into the same .g.dart
file.
For this to work, each builder first writes a .part
file with its name. For instance, if you used moor
and built_value
in the same project, those part files could be called .moor.part
and .built_value.part
.
Later, the common source_gen
package would merge the part files into a single .g.dart
file.
This works great for most use cases, but a downside is that each builder can’t see the final .g.dart
file, or use any classes or methods defined in it. To fix that, moor offers an optional builder -
moor_generator|moor_generator_not_shared
- that will generate a separate part file only containing
code generated by moor. So most of the work resolves around disabling the default generator of moor
and use the non-shared generator instead.
Finally, we need to the build system to run moor first, and all the other builders otherwise. This is why we split the builders up into multiple targets. The first target will only run moor, the second target has a dependency on the first one and will run all the other builders.