Skip to main content

WasmSQLiteDriver

WasmSQLiteDriver is an implementation of the androidx.sqlite.SQLiteDriver interface, enabling SQLite usage in both JVM and Android projects.

Installation​

Add sqlite-driver dependency:

dependencies {
    implementation("at.released.wasm-sqlite-driver:sqlite-driver:0.1-beta03")
}

Add a runtime environment for executing SQLite Wasm code. Currently, the primary runtime is based on the Chicory library.

implementation("at.released.wasm-sqlite-driver:sqlite-embedder-chicory:0.1-beta03")
implementation("com.dylibso.chicory:runtime:1.2.1")

Add the SQLite WebAssembly binary dependency. Although the binary file for SQLite is replaceable, the main version is currently SQLite AOT compiled into an .class for use with Chicory:

implementation("at.released.wasm-sqlite-driver:sqlite-android-wasm-emscripten-icu-aot-349:0.7")

Usage​

Create SQLite Driver using WasmSQLiteDriver:

import at.released.wasm.sqlite.binary.aot.SqliteAndroidWasmEmscriptenIcuAot349
import at.released.wasm.sqlite.binary.aot.SqliteAndroidWasmEmscriptenIcuAot349Machine
import at.released.wasm.sqlite.driver.WasmSQLiteDriver
import at.released.wasm.sqlite.open.helper.chicory.ChicorySqliteEmbedder

val wasmSqliteDriver = WasmSQLiteDriver(ChicorySqliteEmbedder) {
    embedder {
        sqlite3Binary = SqliteAndroidWasmEmscriptenIcuAot349
        machineFactory = ::SqliteAndroidWasmEmscriptenIcuAot349Machine
    }
}

This driver can be used either standalone or with Android Room (2.7+). Here’s an example of how it might be used in tests:

import android.content.ContextWrapper

val mockContext = object : ContextWrapper(null) {
    override fun getDatabasePath(name: String?): File = File(name!!)
}

val db = Room.databaseBuilder(
    name = dbFile.absolutePath,
    factory = ::UserDatabase_Impl,
    context = mockContext,
)
    .setJournalMode(WRITE_AHEAD_LOGGING)
    .setDriver(wasmSqliteDriver)
    .setQueryCoroutineContext(testScope.backgroundScope.coroutineContext) // or newSingleThreadContext("RoomDatabase")
    .allowMainThreadQueries()
    .build()

All available customization options are documented on the Customization page.

Experimental runtimes and binaries​

In addition to the Chicory runtime, experimental runtimes based on GraalVM and Chasm have also been implemented, though they should be used for experimentation only.

// Runtime environment for executing SQLite Wasm code based on GraalVM (Sqlite Embedder)
implementation("at.released.wasm-sqlite-driver:sqlite-embedder-graalvm:0.1-beta03")

// implementation of the runtime environment based on the Chasm library. 
implementation("at.released.wasm-sqlite-driver:sqlite-embedder-chasm:0.1-beta03")

You can explore all available embedders on the Embedders page.

Alternative SQLite builds are also supported. The building of the WebAssembly SQLite libraries has been moved to the wasm-sqlite-driver-binary repository. Please check it out to see the available binaries.