Setup

All you need to know about adding drift to your project.

Drift is a powerful database library for Dart and Flutter applications. To support its advanced capabilities like type-safe SQL queries, verification of your database and migrations, it uses a builder and command-line tooling that runs at compile-time.

This means that the setup involves a little more than just adding a single dependency to your pubspec. This page explains how to add drift to your project and gives pointers to the next steps. If you're stuck adding drift, or have questions or feedback about the project, please share that with the community by starting a discussion on GitHub. If you want to look at an example app for inspiration, a cross-platform Flutter app using drift is available as part of the drift repository.

The dependencies

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 location on the device and to include a recent version of sqlite3, the database most commonly used with drift.

dependencies:
  drift: ^2.16.0
  sqlite3_flutter_libs: ^0.5.0
  path_provider: ^2.0.0
  path: ^1.9.0

dev_dependencies:
  drift_dev: ^2.16.0
  build_runner: ^2.4.8

Alternatively, you can achieve the same result using the following command:

dart pub add drift sqlite3_flutter_libs path_provider path dev:drift_dev dev:build_runner

If you're wondering why so many packages are necessary, here's a quick overview over what each package does:

  • drift: This is the core package defining the APIs you use to access drift databases.
  • sqlite3_flutter_libs: Ships the latest sqlite3 version with your Android or iOS app. This is not required when you're not using Flutter, but then you need to take care of including sqlite3 yourself. For an overview on other platforms, see platforms. Note that the sqlite3_flutter_libs package will include the native sqlite3 library for the following architectures: armv8, armv7, x86 and x86_64. Most Flutter apps don't run on 32-bit x86 devices without further setup, so you should add a snippet to your build.gradle if you don't need x86 builds. Otherwise, the Play Store might allow users on x86 devices to install your app even though it is not supported. In Flutter's current native build system, drift unfortunately can't do that for you.
  • path_provider and path: Used to find a suitable location to store the database. Maintained by the Flutter and Dart team.
  • drift_dev: This development-only dependency generates query code based on your tables. It will not be included in your final app.
  • build_runner: Common tool for code-generation, maintained by the Dart team.

Database class

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 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 somewhere under lib/. Of course, you can put this class in any Dart file you like.

To make the database useful, we'll also add a simple table to it. This table, TodoItems, can be used to store todo items for a todo list app. Everything there is to know about defining tables in Dart is described on the Dart tables page. If you prefer using SQL to define your tables, drift supports that too! You can read all about the SQL API here.

For now, the contents of database.dart are:

import 'package:drift/drift.dart';

part 'database.g.dart';

class TodoItems extends Table {
  IntColumn get id => integer().autoIncrement()();
  TextColumn get title => text().withLength(min: 6, max: 32)();
  TextColumn get content => text().named('body')();
  IntColumn get category => integer().nullable()();
}

@DriftDatabase(tables: [TodoItems])
class AppDatabase extends _$AppDatabase {
}

You will get an analyzer warning on the part statement and on extends _$AppDatabase. This is expected because drift's generator did not run yet. You can do that by invoking build_runner:

  • dart run build_runner build generates all the required code once.
  • dart run build_runner watch watches for changes in your sources and generates code with incremental rebuilds. This is suitable for development sessions.

After running either command, the database.g.dart file containing the generated _$AppDatabase class will have been generated. You will now see errors related to missing overrides and a missing constructor. The constructor is responsible for telling drift how to open the database. The schemaVersion getter is relevant for migrations after changing the database, we can leave it at 1 for now. The database class now looks like this:

// These imports are necessary to open the sqlite3 database
import 'dart:io';

import 'package:drift/native.dart';
import 'package:path_provider/path_provider.dart';
import 'package:path/path.dart' as p;
import 'package:sqlite3/sqlite3.dart';
import 'package:sqlite3_flutter_libs/sqlite3_flutter_libs.dart';

// ... the TodoItems table definition stays the same

@DriftDatabase(tables: [TodoItems])
class AppDatabase extends _$AppDatabase {
  AppDatabase() : super(_openConnection());

  @override
  int get schemaVersion => 1;
}

LazyDatabase _openConnection() {
  // the LazyDatabase util lets us find the right location for the file async.
  return LazyDatabase(() async {
    // put the database file, called db.sqlite here, into the documents folder
    // for your app.
    final dbFolder = await getApplicationDocumentsDirectory();
    final file = File(p.join(dbFolder.path, 'db.sqlite'));

    // Also work around limitations on old Android versions
    if (Platform.isAndroid) {
      await applyWorkaroundToOpenSqlite3OnOldAndroidVersions();
    }

    // Make sqlite3 pick a more suitable location for temporary files - the
    // one from the system may be inaccessible due to sandboxing.
    final cachebase = (await getTemporaryDirectory()).path;
    // We can't access /tmp on Android, which sqlite3 would try by default.
    // Explicitly tell it about the correct temporary directory.
    sqlite3.tempDirectory = cachebase;

    return NativeDatabase.createInBackground(file);
  });
}

The Android-specific workarounds are necessary because sqlite3 attempts to use /tmp to store private data on unix-like systems, which is forbidden on Android. We also use this opportunity to work around a problem some older Android devices have with loading custom libraries through dart:ffi.

Next steps

Congratulations! With this setup complete, your project is ready to use drift. This short snippet shows how the database can be opened and how to run inserts and selects:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final database = AppDatabase();

  await database.into(database.todoItems).insert(TodoItemsCompanion.insert(
        title: 'todo: finish drift setup',
        content: 'We can now write queries and define our own tables.',
      ));
  List<TodoItem> allItems = await database.select(database.todoItems).get();

  print('items in database: $allItems');
}

But drift can do so much more! These pages provide more information useful when getting started with drift:

  • Dart tables: This page describes how to write your own Dart tables and which classes drift generates for them.
  • Writing queries: Drift-generated classes support writing the most common SQL statements, like selects or inserts, updates and deletes.
  • Something to keep in mind for later: When changing the database, for instance by adding new columns or tables, you need to write a migration so that existing databases are transformed to the new format. Drift's extensive migration tools help with that.

Once you're familiar with the basics, the overview here shows what more drift has to offer. This includes transactions, automated tooling to help with migrations, multi-platform support and more.