Upgrading Drift

Migrating from drift 2.x to drift 3.x preview#

Version 3 is an upcoming major upgrade for drift that is currently in preview. drift_dev provides a tool to automatically migrate most of your project, run it before changing any dependencies:

dart run drift_dev upgrade

The focus of this upgrade is a faster query interface, better support for other SQL dialects and changes to the generated code to prepare for augmentations. Most of these changes are internal and only relevant for custom drift backends, but some affect all apps using drift. In particular, this changes a few default options. drift_dev upgrade explicitly applies existing options to preserve existing behavior.

To support both major versions in a transition period, drift version 3 is currently only available as the drift3_preview package. SQLite support additionally requires the drift_sqlite package. Manager queries require a dependency on drift_manager. drift_flutter has not been ported yet.

Dialect changes#

Drift no longer has a default SQLite dialect. To reflect that all dialects are equally supported, SQLite support has moved to the drift_sqlite package. This also makes it possible to implement your own drift dialect by extending the DriftDialect class.

Support for custom column types is no longer a special case, as all SQL types are treated equally. The SqlType interface represents a logical SQL type that works across dialects, while PhysicalSqlType is a dialect-specific type implementation.

The SQLite dialect now stores date times as text by default to preserve accuracy and time zones. The SQLite dialect uses strict tables by default now. The upgrade tool disables both options for existing databases, as existing migrations otherwise require a migration.

Drift now has builtin support for JSON columns. SQLite stores them as jsonb by default, this can be changed to text.

In build.yaml files, dialect options are now an array with one element per dialect:

targets:
  $default:
    builders:
      drift_dev:
        options:
          drift3_preview: true
          dialects:
            - dialect: sqlite
              version: "3.50"
              strict_tables_by_default: true
            - dialect: postgres

Connection setup#

The drift_flutter package continues to work without major changes. Under the hood, default connections use a much faster default configuration now:

• package:drift/isolate.dart and package:drift/remote.dart have been removed. The only builtin way to use multi-threaded connections is to use sqliteConnectionPool from package:drift_sqlite/native.dart. That option uses multiple connections and isolates for fast and parallel queries. Two isolates opening the same file with sqliteConnectionPool automatically coordinate access and update notifications, even on different Flutter engines.
• Web support from package:drift/wasm.dart was moved to package:drift_sqlite/web.dart, and uses the sqlite3_web package, which is faster.
• The deprecated package:drift/web.dart library based on sql.js has been removed without replacement.

Other#

• Generating manager code is now opt-in and requires the generate_manager: true builder option as well as a dependency on the drift_manager package.
• computeWithDatabase now requires the drift_sqlite package.

Internal#

• Remove QueryExecutor class, replaced with DriftSession which is much easier to implement.
  • Remove runCustom, runDelete, runInsert, runSelect and runUpdate. Use execute instead.
• Change row representation from Map<String, Object?> to List<Object?> for efficiency.
• Make reading rows more efficient by only resolving types once per query instead of once per value.

Migrating from drift 1.x to drift 2.x#

The first major upgrade from drift 1 to drift 2 involves a number of breaking changes and the removal of legacy features. These changes make drift easier to maintain and easier to use.

This overview describes important breaking changes and how to apply them to your project. For a full list of updates, see the changelog.

1. Null-safety only: Drift will always emit null-safe code now. To use drift 2.x, please migrate your application (or at least the parts defining the database) to Dart 2.12 or later.

2. Instances of Expression always have a non-nullable type parameter now. That is, use Expression<int> instead of Expression<int?>. The old distinction was an attempt to embed SQL's behavior around NULL values into Dart's typesystem. This didn't work, and so expressions no longer have associated nullability in their types.

3. Reading nullable expressions: QueryRow.read (used to read columns from a complex select in Dart) only supports non-nullable values now. To read nullable values, use readNullable.

4. Updated type converters: The mapToSql and mapToDart methods have been renamed to simply toSql and fromSql, respectively. Also, a type converter only needs to support the exact types that it was declared with. In particular, a TypeConverter<MyObject, String> no longer needs to deal with null values in either direction.

   Type converters that are declared as nullable (e.g. TypeConverter<Foo?, int?>) can no longer be applied to non-nullable columns. These changes bring proper null-safety support to type converters and make their behavior around null values more intuitive.

5. Changed builder options: To reduce the complexity of drift_dev, and to make some long-recommended builder options the default, some options have been removed or had their defaults changed.

• The following options are no longer available:
  • new_sql_code_generation: Always enabled now. If this changes the behavior of your queries, please open an issue!
  • null_aware_type_converters: This is always enabled now with the new semantics for type converters.
  • compact_query_methods: Has been enabled by default before, can no longer be disabled now.
  • eagerly_load_dart_ast: This option used to not do anything for a while and has been removed entirely now.
• In addition, the defaults for these options has changed (but the existing behavior can be restored if desired):
  • apply_converters_on_variables is enabled by default now.
  • generate_values_in_copy_with is enabled by default now.
  • scoped_dart_components is enabled by default now.

6. The generated fromData factory on data classes is no longer generated. Use the map methods on the table instance instead (e.g. database.users.map instead of User.fromData).

The breaking changes in drift 2.0 are motivated by making drift easier to maintain and to unblock upcoming new features. This release also provides some new features, like nested transactions or support for RETURNING for updates and deletes in the dart_api. We hope the upgrade is worthwhile. If you run into any issues, please do not hesitate to start a new discussion or to open an issue. Thanks for using drift!

Migrating from moor to drift#

Moor has been renamed to drift. The reason for this is that, in some parts of the world, moor may be used as a derogatory term. I have not been aware of this when starting this project, but we believe that the current name does not reflect the inclusivity of the Dart and Flutter communities. Despite the associated effort, I'm convinced that renaming the project is the right decision. Thank you for your understanding!

Until version 5.0.0, the current moor, moor_flutter and moor_generator packages will continue to work - no urgent action is necessary. All features and fixes to the new drift packages will be mirrored in moor as well. With the release of drift 2.0.0, the moor set of packages have been discontinued in favor of drift and drift_dev.

This page describes how to migrate from the old moor package to the new drift package. This process can be automated, and we hope that the migration is a matter of minutes for you. In case of issues with the tool, this page also describes how to manually migrate to the new drift packages.

Automatic migration#

To make the name change as easy as possible for you, drift comes with an automatic migration tool for your project. It will analyze your source files and perform all changes that come with this migration.

To use the migration tool, please first make sure that you're using moor_generator version 4.6.0 or later, for instance by updating your dependency on it:

dev_dependencies:
  moor_generator: ^4.6.0

Next, please make sure that your project does not contain analysis errors, as this could make the migration tool less effective. Also, please create a backup of your project's files before running the migration tool. It will override parts of your sources without further confirmation. When using git, it is sufficient to ensure that you have a clean state.

To apply the migration, run dart run moor_generator migrate in your project's directory. The migration tool will transform your pubspec, build.yaml files and Dart source files. It will also rename .moor files to .drift and patch imports as needed.

After running the migration, please verify the changes to ensure that they match what you expect. Also, you may have to

• Format your sources again: Run dart format ..
• Re-run the build: Run dart run build_runner build -d.
  • If you have been using generated migration test files, re-generate them as well with dart run drift_dev schema generate drift_schemas/ test/generated_migrations/ (you may have to adapt the command to the directories you use for schemas).
• Manually fix the changed order of imports caused by the migration.

Congratulations, your project is now using drift!

If you run into any issues with the automatic migration tool, please open an issue.

Manual migration#

To migrate from moor to drift, you may have to update:

• Your pubspec
• Dart imports
• Dart code, to reflect new API names
• Your build.yaml configuration files, if any

The following sections will describe each of the steps.

New dependencies

First, replace the moor dependency with drift and moor_generator with drift_dev, respectively:

dependencies:
  drift: ^2.35.3
dev_dependencies:
  drift_dev: ^2.35.2

If you've been using moor_flutter, also add a dependency on drift_sqflite: ^1.0.0.

Run pub get to get the new packages.

Changing Dart imports

This table compares the old imports from moor and the new imports for drift:

Changing Dart code

This table compares old moor-specific API names and new names as provided by drift:

(Optional: Rename moor files)

For consistency, you can rename your .moor files to .drift. The drift generator will continue to accept .moor files though.

If you opt for a rename, also update your imports and include: parameters in database and DAO classes.

Build configuration

When configuring moor builders for options, you have to update your build.yaml files to reflect the new builder keys: