# DBFlow is a Kotlin Multiplatform SQLite ORM built around a compiler plugin

> DBFlow annotates tables and databases, then generates adapters and a typed query DSL at build time. It targets Android, JVM, iOS and macOS, and its install path currently runs through a Gradle plugin version catalog.

**agrosner/DBFlow** — A blazing fast, powerful, and very simple ORM android database library that writes database code for you.

- Repository: https://github.com/agrosner/DBFlow
- Stars: 4,847 · Forks: 592
- Language: Kotlin
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/agrosner-dbflow

## The problem DBFlow solves: typed SQLite without hand-written mapping code

Android and Kotlin Multiplatform projects that touch SQLite usually end up with two layers that must be kept in sync by hand: the table definitions and the code that reads rows into objects. DBFlow removes the second layer. You annotate a data class with @Table and a database class with @Database, and the compiler plugin generates the companion objects, the adapters and the column properties used by the query DSL.

The target audience is narrow and specific. This is for Kotlin teams shipping to Android, JVM, iOS or macOS who want one persistence layer across those targets. A single-platform Android app backed by Room does not gain much here, because Room already couples an annotation processor to Kotlin and is maintained inside the Android toolchain. DBFlow's pitch is the shared surface: the README describes it as a Kotlin Multiplatform SQLite library, and the module table keeps the multiplatform runtime in lib while Android-only extras live in separate artifacts. The query DSL is the second half of the pitch. Expressions like the one below are ordinary Kotlin, checked when the query is compiled, rather than a string that fails at runtime.

## How the compiler plugin, adapters and query DSL fit together

The mechanism has three parts, all visible in the repository layout. Annotations and converters live in core, which lib pulls in. The runtime, the query DSL, transactions and Flow observers live in lib. Code generation lives in compiler, kotlin-codegen and compiler-gradle, and it is exposed to consumers as the Gradle plugin with id com.dbflow5.

The data flow starts at the annotation. A @Table data class and a @Database class are inputs to the plugin. The plugin emits table companions containing adapters and column properties, plus *_Adapter helpers and *_Database types. When the README says the plugin adds "the generated-sources directory on commonMain", that is the output location your code compiles against. The generated adapter is the object you call save on; the generated column property is what makes User.name eq "Ada" a valid Kotlin expression instead of a string fragment.

Two details in the README are worth flagging as design trade-offs. First, coroutines are built into lib, and the README states there is no separate coroutines artifact. That removes a dependency decision, but it also means the runtime carries coroutine support whether or not a given target uses it. Second, the plugin does more than wire dependencies: it also adds -lsqlite3 linker options for native binaries and registers a dbflowGenerate task. Putting linker flags in a Gradle plugin is convenient for the common case and awkward when a project already controls its native linking configuration.

## Installing DBFlow with the com.dbflow5 Gradle plugin

The README points installation at usage2/including-in-project.md and gives a version catalog quick start. Add the plugin to your catalog first. The README shows a [plugins] entry with the id com.dbflow5 and version 5.0.0-alpha2, so the version you pin matches the published release rather than a range.

```toml
[plugins]
dbflow = { id = "com.dbflow5", version = "5.0.0-alpha2" }
```

Then apply it in the module that holds your shared code, alongside the Kotlin Multiplatform plugin. The README calls this "the whole setup", and the plugin resolves the rest.

```kotlin
plugins {
    kotlin("multiplatform")
    alias(libs.plugins.dbflow)
}
```

After applying it, the plugin adds the com.dbflow5:lib dependency, attaches the compiler plugin, registers the generated-sources directory on commonMain, adds -lsqlite3 linker opts for native binaries, and creates the dbflowGenerate task. The practical consequence is that your models must be in place before a build will produce adapters. Declare a table and a database, as the README does, then run dbflowGenerate to see the generated companions appear.

```kotlin
@Database(version = 1, tables = [User::class])
abstract class AppDatabase : DBFlowDatabase<AppDatabase>() {
    abstract val userAdapter: ModelAdapter<User>
}
```

Opening a database and writing a row follows the README's example. createDB takes a context and a configuration lambda; the README's snippet uses copy(name = "App") to set the database name. Inside writableTransaction, userAdapter.save persists a User, and the select expression filters by the generated column property.

```kotlin
import com.dbflow5.database.createDB

val db = createDB<AppDatabase>(context) { copy(name = "App") }

db.writableTransaction {
    userAdapter.save(User(name = "Ada"))
    val users = (userAdapter.select() where (User.name eq "Ada")).list()
}
```

One install constraint is stated plainly. Until the plugin is published to Maven Central, the README directs you to a composite build of this repository, documented under usage2/including-in-project.md#from-this-repository. If you are not already comfortable with Gradle composite builds, that is the first thing to read.

## Where DBFlow is the wrong choice, and what the docs leave open

The release history is the clearest limitation. The newest published release is 5.0.0-alpha2, dated 2021-03-13. The previous alpha, 5.0.0-alpha1, is from 2018-10-21, and the last non-alpha release, 4.2.4, is from 2017-12-28. Anyone who needs a stable, versioned dependency with a predictable upgrade path is looking at an alpha line here, and the 4.x releases belong to a different API generation than the Kotlin Multiplatform code shown in the README. Treat the alpha label as the constraint it is, not as a formality.

The README is also thin in places that matter for adoption decisions. It does not document migration or schema upgrade behaviour beyond the version parameter on @Database. It does not describe rollback semantics for transactions. It does not state a minimum Kotlin or Gradle version, so the plugin's compatibility range has to be discovered by trying it. The sqlcipher module covers encrypted Android databases, but the README does not explain how encryption is configured, and the livedata, paging and reactive-streams artifacts are listed by role only. None of that is disqualifying, but each item is something you would otherwise expect a persistence library's front page to answer.

The wrong-tool case is straightforward. If your app is Android-only, uses Room, and has no iOS or desktop target on the roadmap, DBFlow asks you to take on a compiler plugin and a build-time code generation step in exchange for portability you will not use. If your team cannot adopt a composite build while the plugin is off Maven Central, the documented install path does not work for you yet.

## DBFlow compared with Room and SQLDelight

The comparison that matters is what each tool treats as the source of truth. Room, the Android persistence library, generates its implementation from annotated entities and DAO interfaces through an annotation processor, and it is Android-only. DBFlow generates adapters and a query DSL from annotations through a Kotlin compiler plugin, and it targets Android, JVM, iOS and macOS. The difference is both portability and when generation happens: a compiler plugin sees Kotlin symbols in a way an annotation processor does not, which is what lets DBFlow expose User.name as a typed column property.

SQLDelight takes the opposite approach to the same problem. You write SQL in .sq files, and it generates typed Kotlin from the queries. DBFlow keeps the query in Kotlin and generates the plumbing around your models; SQLDelight keeps the query in SQL and generates Kotlin around it. If your team already writes and reviews SQL, SQLDelight's model will feel closer to how you work. If you would rather never write a SQL string, DBFlow's DSL is the reason to pick it. Neither approach is a superset of the other, and the README's own framing puts DBFlow on the annotation-and-DSL side.

A secondary difference is coroutines. The README states that coroutines are built into lib with no separate artifact, and that Flow observers are part of the runtime. That is a smaller decision than the source-of-truth question, but it shapes how much of your async code the library touches.

## Maintenance, licence and the cost of upgrading

On maintenance, the facts are limited to the repository state: the project is not archived, and the last push was on 2026-08-23. That is recent activity on the default branch. It does not change the release picture, which is that the newest published artifact is an alpha from 2021-03-13. Commits and releases are separate signals, and here they point in different directions.

The upgrade cost follows from the plugin design. Because the plugin injects the lib dependency, the compiler plugin, the generated-sources directory, the native linker options and the dbflowGenerate task, an upgrade is a build-level change rather than a dependency version bump. Moving between 4.x and 5.x is not a patch upgrade: the README's examples use DBFlowDatabase, ModelAdapter, createDB and the com.dbflow5 package namespace, none of which appear in the older release numbering. Plan for the generated output to change shape and for your call sites to change with it.

The licence is MIT, which is permissive and places few constraints on how you distribute the library inside an application. That is the extent of what the repository states; if your organisation has specific obligations around attribution or bundled third-party notices, that is a question for your own counsel rather than something the README settles.

## Conclusion

Adopt DBFlow if you want an ORM whose query surface is generated Kotlin rather than reflection, and you accept a plugin-driven build: the README notes the plugin is not yet on Maven Central, so a composite build of the repository is the documented fallback. Skip it if you need a stable release line; the newest published release is 5.0.0-alpha2, published 2021-03-13, and the 4.x line predates the Kotlin Multiplatform rewrite. Before committing, verify that dbflowGenerate runs in your build and that generated sources appear on commonMain.

## FAQ

### How do I add DBFlow to an Android or Kotlin Multiplatform project?

Add the Gradle plugin com.dbflow5 to your version catalog with version 5.0.0-alpha2, then apply it alongside the Kotlin Multiplatform plugin. The README states the plugin adds the com.dbflow5:lib dependency, the compiler plugin, the generated-sources directory on commonMain, native linker options and the dbflowGenerate task.

### Is DBFlow available on Maven Central?

The README states that until the plugin is on Maven Central you should use a composite build of this repository, documented under usage2/including-in-project.md#from-this-repository. The quick start otherwise relies on the plugin being resolvable through a version catalog.

### Which platforms does DBFlow target?

The README lists Android, JVM, iOS and macOS as targets. The lib module holds the multiplatform runtime, query DSL, transactions and Flow observers, while livedata, paging and reactive-streams are Android extras.

### Does DBFlow require a separate coroutines artifact?

No. The README states that coroutines are built into lib and that there is no separate coroutines artifact.

## Sources

- [agrosner/DBFlow on GitHub](https://github.com/agrosner/DBFlow)
- [Issues](https://github.com/agrosner/DBFlow/issues)
- [License: MIT](https://github.com/agrosner/DBFlow/blob/master/LICENSE)
- [README](https://github.com/agrosner/DBFlow/blob/master/README.md)
- [Releases](https://github.com/agrosner/DBFlow/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agrosner-dbflow