SQLDelight in Android: Getting Started

As soon as we add the SQLDelight plugin to our project, it applies a configuration that covers the most common use cases with some sane default values. Let’s go over how this configuration can be tweaked for customization or advanced usage.

The Gradle plugin for SQLDelight exposes a domain-specific language to consumers. Let’s open the app module’s build.gradle file and, below the android block, declare a new block named ‘sqldelight’.

The first thing that we have to declare in this block is the name of our database, which will also become the name of its generated Kotlin class.

In our case, we will simply write ‘Database’ - capital D. Note how we could define multiple databases inside the sqldelight block for different purposes. Our bug collector app only needs one database, though, so let’s stick to just the one here.

sqldelight {
    Database {

    }
}

It’s time to over the settings that SQLDelight allows us to configure. First, remember the Database class that it generates? By default, it will be created in the package expressed through the module’s applicationId.

If you want to use a different package instead, use the ‘packageName’ key to change it. I would like it to be placed in a dedicated database package, so let’s derive it from the application ID variable and append dot-d-b at the end.

sqldelight {
    Database {
+       packageName = "${appPackageName}.db"
    }
}

Next, we can define the folders that make up the source set for SQLDelight script files, such as tables and migrations.

The default value is the string ‘sqldelight’, meaning that the plugin will scan the folder src/main/sqldelight for files and nothing else. Note how the ‘sourceFolders’ key is an array, so you could define multiple folders here if you want.

sqldelight {
    Database {
        packageName = "${appPackageName}.db"

+       sourceFolders = ["sqldelight"]
    }
}

The next setting is related to testing migrations in the future. By specifying a value for the ‘schemaOutputDirectory’, SQLDelight will create empty database files and store them in this folder.

Furthermore, the Gradle plugin will attach a test task to validate migration files automatically, checking that you never overlook anything in-between two versions of the database - this will come into play at a later point.

To enable the verification feature, we also need to enable the ‘verifyMigrations’ flag by setting it to true. From now on, our build will fail at compile-time whenever we update the database to a new version, but mess up the migration in any way.

sqldelight {
    Database {
        packageName = "${appPackageName}.db"

        sourceFolders = ["sqldelight"]

+       schemaOutputDirectory = file("src/main/sqldelight/schemas")
    }
}

There are a few more advanced features that can be specified in the SQLDelight configuration block, and even though we won’t need them for our sample app, let me show how they work regardless.

First, you can specify the dialect of SQL that SQLDelight should use with the ‘dialect’ key. By default, SQLite 3.18 is used, but this can be freely changed to other versions of SQLite or even things like Postgres or MySQL.

These settings don’t really have a use for Android projects, so let’s remove this key again to stick to the default.

sqldelight {
    Database {
        packageName = "${appPackageName}.db"

        sourceFolders = ["sqldelight"]

        schemaOutputDirectory = file("src/main/sqldelight/schemas")

+       dialect = "mysql"
-       dialect = "mysql"
    }
}

Finally, the ‘dependency’ key makes it possible to first distribute the contents of your database between multiple Gradle modules, then pull them together in the app module, which is super interesting. I’m going to visualize this, so let’s explore this together.

sqldelight {
    Database {
        packageName = "${appPackageName}.db"

        sourceFolders = ["sqldelight"]

        schemaOutputDirectory = file("src/main/sqldelight/schemas")

+       dependency project(":library1")
-       dependency project(":library1")
    }
}

Assume that we have two Gradle modules in our project: the app module on the left, and a library module on the right.

Each of them have their corresponding Android plugins applied. We want to make use of SQLDelight dependencies now, so first we apply the SQLDelight Gradle plugin to both modules.

The app module will generate a Database class using tables defined in the library module. We have three files in the library that we can inject into the app’s database by declaring the ‘dependency project library1’ inside the app’s build file. SQLDelight will know that the library’s files are to be included into the app database.

This is not limited to a singular dependency either. Here is a second library module with two additional files. Repeat the dependency statement for it and voilà: The app database will be created with five files in total!

Sync your Gradle project after finishing the configuration. The SQLDelight code generator won’t create a Database class just yet, since we haven’t written any script file that declares a table for it. This will come in the next step!