Upgrading to 2.0

SQLDelight 2.0 makes some breaking changes to the gradle plugin and runtime APIs.

This page lists those breaking changes and their new 2.0 equivalents. For a full list of new features and other changes, see the changelog.

New Package Name and Artifact Group

All instances of com.squareup.sqldelight need to be replaced with app.cash.sqldelight.

Gradle Dependencies

plugins {
-  id("com.squareup.sqldelight") version "2.0.0"
+  id("app.cash.sqldelight") version "2.0.0"
}

dependencies {
-  implementation("com.squareup.sqldelight:sqlite-driver:2.0.0")
+  implementation("app.cash.sqldelight:sqlite-driver:2.0.0")
}

In Code

-import com.squareup.sqldelight.db.SqlDriver
+import app.cash.sqldelight.db.SqlDriver

Gradle Configuration Changes

• SQLDelight 2.0 requires Java 11 for building, and Java 8 for the runtime.

• The SQLDelight configuration API now uses managed properties and a DomainObjectCollection for the databases.

  KotlinGroovy

  sqldelight {
    databases { // (1)!
      create("Database") {
        packageName.set("com.example") // (2)!
      }
    }
  }
  

  1. New DomainObjectCollection wrapper.
  2. Now a Property<String>.

  sqldelight {
    databases { // (1)!
      Database {
        packageName = "com.example"
      }
    }
  }
  

  1. New DomainObjectCollection wrapper.

• The SQL dialect of your database is now specified using a Gradle dependency.

  KotlinGroovy

  sqldelight {
    databases {
      create("MyDatabase") {
        packageName.set("com.example")
        dialect("app.cash.sqldelight:mysql-dialect:2.0.0")
  
        // Version catalogs also work!
        dialect(libs.sqldelight.dialects.mysql)
      }  
    }  
  }
  

  sqldelight {
    databases {
      MyDatabase {
        packageName = "com.example"
        dialect "app.cash.sqldelight:mysql-dialect:2.0.0"
  
        // Version catalogs also work!
        dialect libs.sqldelight.dialects.mysql
      }  
    }  
  }
  

  The currently supported dialects are mysql-dialect, postgresql-dialect, hsql-dialect, sqlite-3-18-dialect, sqlite-3-24-dialect, sqlite-3-25-dialect, sqlite-3-30-dialect, sqlite-3-35-dialect, and sqlite-3-38-dialect

Runtime Changes

• Primitive types must now be imported into .sq and .sqm files.

  +import kotlin.Boolean;
  
  CREATE TABLE HockeyPlayer (
    name TEXT NOT NULL,
    good INTEGER AS Boolean
  );
  

  Some previously supported types now require an adapter. Adapters for primitive types are available in the app.cash.sqldelight:primitive-adapters:2.0.0 artifact. e.g. The IntColumnAdapter for doing INTEGER As kotlin.Int conversions.

• The AfterVersionWithDriver type was removed in favour of AfterVersion which now always includes the driver, and the migrateWithCallbacks extension function was removed in favour of the main migrate method that now accepts callbacks.

  Database.Schema.migrateWithCallbacks(
    driver = driver,
    oldVersion = 1,
    newVersion = Database.Schema.version,
  -  AfterVersionWithDriver(3) { driver ->
  -    driver.execute(null, "INSERT INTO test (value) VALUES('hello')", 0)
  -  }
  +  AfterVersion(3) { driver ->
  +    driver.execute(null, "INSERT INTO test (value) VALUES('hello')", 0)
  +  }
  )
  

• The Schema type is no longer a nested type of SqlDriver, and is now called SqlSchema.

  -val schema: SqlDriver.Schema
  +val schema: SqlSchema
  

• The paging3 extension API has changed to only allow int types for the count.

• The coroutines extension API now requires a dispatcher to be explicitly passed in.

  val players: Flow<List<HockeyPlayer>> =
    playerQueries.selectAll()
      .asFlow()
  +   .mapToList(Dispatchers.IO)
  

• Some driver methods like execute(), executeQuery(), newTransaction(), and endTransaction() now return a QueryResult object. Use QueryResult.value to access the returned value.

  -driver.executeQuery(null, "PRAGMA user_version", { /*...*/ })
  +driver.executeQuery(null, "PRAGMA user_version", { /*...*/ }).value
  

  This change enables driver implementations to be based on non-blocking APIs where the returned value can be accessed using the suspending QueryResult.await() method.
• The next() method on the SqlCursor interface has also been changed to return a QueryResult to enable better cursor support for asynchronous drivers.
• The SqlSchema interface now has a generic QueryResult type parameter. This is used to distinguish schema runtimes that were generated for use with asynchronous drivers, which may not be directly compatible with synchronous drivers. This is only relevant for projects that are simultaneously using synchronous and asynchronous drivers together, like in a multiplatform project that has a JS target. See "Multiplatform setup with the Web Worker Driver" for more details.
• The type of SqlSchema.Version changed from Int to Long to allow for server environments to leverage timestamps as version. Existing setups can safely cast between from Int and Long, and drivers that require an Int range for versions will crash before database creation for out of bounds versions.