Drift: Type-Safe SQL in Dart & Flutter

Why it exists

Standard Dart database libraries often return a List<Map<String, dynamic>>, a structure that offers no type safety. A typo in a column name or a schema mismatch is only discovered at runtime, leading to crashes. Drift was created to bring compile-time guarantees to database persistence in Dart, bridging the gap between raw SQL's power and Dart's type system.

The mental model

Think of Drift's SQL integration as a pre-flight check for your database queries. Before your app is even compiled, Drift's build runner acts like a database expert. It reads your SQL, checks it against your table definitions, and then generates the exact Dart classes needed to hold the results. It turns potential runtime crashes into compile-time errors you can fix immediately.

How it works

You define your tables using Dart classes. Then, you write SQL queries, typically in dedicated .drift files. During the standard Dart build process, a code generator parses this SQL. It understands the syntax, infers the columns and types of the result set, and generates corresponding type-safe Dart classes and methods. To execute the query, you call the generated Dart method and receive a list of strongly-typed objects, not a generic map.

When to use it

Use Drift's type-safe SQL when you need to write complex queries that are difficult or verbose to express with a fluent API. This is perfect for intricate joins, aggregations, or using database-specific functions not covered by the fluent interface. It allows developers comfortable with SQL to leverage their skills without sacrificing the safety of the Dart type system.

When not to use it

For simple CRUD (Create, Read, Update, Delete) operations, Drift's fluent Dart API is often cleaner and requires no context switching. For example, select(users).watch() is more direct than writing the equivalent SQL. Overusing raw SQL for simple tasks adds unnecessary boilerplate and can make the code harder to refactor if the schema changes.

One canonical example

Imagine you have users and purchases tables. To get each user and their total spending, you could write a query in a .drift file: totalSpentByUser: SELECT u.*, SUM(p.price) AS total FROM users u JOIN purchases p ON p.user_id = u.id GROUP BY u.id;. At compile time, Drift generates a TotalSpentByUserResult class with properties for all columns from the users table plus a double total field. Your Dart code then calls a generated method and gets a List<TotalSpentByUserResult>, fully typed and safe.