5.0 Migration Guide

This lists out the major changes since < 5.0

Major Changes

1. Package name is now com.dbflow5 , which enables bundling multiple versions in the same repo.

   1. Note: Using multiple versions of DBFlow on the same DB is not recommended, as it can lead to inconsistent usage on the database in respect to transaction queuing, migrations, or synchronization.

2. Library is now 100% Kotlin, except generated code. KSP (Kotlin Source Processing) is promising, but will require major updates to support it directly. This means that any -kotlinextensions artifacts are now rolled into the library.

3. Library now adds support for incremental annotation processing. Please report any issues!

4. New artifacts: paging(architecture components Paging), coroutines, contentprovider, (splits out ContentProvider usage out of main library), livedata, reactive-streams (RXJava3).

   1. RXJava1 and 2 support is dropped given, https://github.com/ReactiveX/RxJava/tree/2.x is now in maintenance mode. You simply need to copy paste the reactive-streams files you need and then replace the package names back to their RXJava2 equivalent. RXJava 1 is not quite equivalent and not supported.

5. save() methods on the ModelAdapter classes now use a more efficient INSERT OR REPLACE method, rather than check if exists manually from the DB before inserting or replacing.

6. @Database classes must now be an abstract class that extends DBFlowDatabase (or related subclass)

   1. @Database(version = 1)
      abstract class AppDatabase : DBFlowDatabase()

7. Removed deprecated @Database annotation fields including name, databaseExtension, and inMemory. Use the DatabaseConfig.Builder object when initializing DBFlow (see Database configuration docs for some examples).

8. The implicit DatabaseWrapper that was used in model operations is now required explicit.

9. // 4.x
   // this would grab the default database from the FlowManager
   model.save()
   
   // 5.x
   database<AppDatabase> { db -> model.save(db) }

10. ModelAdapter.bindToContentValues and corresponding ContentValues generated code is no longer enabled by default. If you need ContentValues generation, set @Table(generateContentValues = true).

    1. Note: For @ContentProvider object, your db must now extend ContentProviderDatabase to supply ContentValues methods on the database. This lives in a separate artifact named contentprovider.

11. Explicitly marking every field in a @Table with @Column is no longer the default. By default, any visible field in the model class are referenced. To enable the old behavior use @Table(allFields = false)

12. Adds @Fts3 and @Fts4 annotations. See SQLite docs on Fts3 and 4. Added corresponding snippet and offsets method support.

    val value = (select(snippet<Fts4VirtualModel2>(
        start = "[",
        end = "]",
        ellipses = "...",
    )) from Fts4VirtualModel2::class
        where (tableName<Fts4VirtualModel2>() match "\"min* tem*\""))
        .stringValue(db)

13. @ModelView: gets orderedCursorLookup, assignDefaultValuesFromCursor , and createWithDatabase that were allowed on @Table classes.

14. @QueryModel: gets orderedCursorLookup, andassignDefaultValuesFromCursor that were allowed on @Table classes.

15. IMultiKeyCacheConverter renamed to MultiKeyCacheConverter and make it a fun interface!

16. Performing DB operations not in a transaction will throw a new warning in FlowLog: Database Not Running in a Transaction. Performance may be impacted, observability will need manual updates via db.tableObserver.checkForTableUpdates()

17. QueryModelAdapter is deprecated as RetrievalAdapter performs all functionality.

18. DBFlowDatabase can now specify a JournalMode to support write-ahead logging. Note: on higher end devices this will enable WriteAheadLogging by default for performance gains.

19. New TableObserver class on a DBFlowDatabase. Inspired by Room, this sets up Trigger on table changes for observed tables to efficiently track which table changes. This is useful in recomputing queries for LiveData, Flowable , or Paging DataSource. Whenever a Transaction is run on the DB, upon completing it, we check for any table changes and dispatch that to the active queries that are observed.

    1. (select from MyTable::class ...)
         .toLiveData(db)
         .observe(owner) { r -> }

20. AlterTableMigration supports default values for a column when adding a column.

21. Index.enable renamed to createIfNotExists, Index.disable renamed to drop.

22. Reduce generated code in tables.

23. New database configuration DSL! Prior usage looked like:

FlowManager.init(FlowConfig.builder()
    .database(DatabaseConfig.builder(AppDatabase::class)
      .databaseName("AppDatabase")
      .build())
    .build())

Now looks like:

FlowManager.init(context) {
  database<AppDatabase> {
    databaseName("AppDatabase")
  }
}