feat(android-sqlite): Add SentrySQLiteDriver (JAVA-275)

Introduces support for AndroidX's SQLiteDriver via a new SentrySQLiteDriver wrapper.

SentrySQLiteDriver automatically creates spans for each SQL statement it executes, and its data scheme closely tracks that of SentrySupportSQLiteOpenHelper, which it's designed to replace. (Span duration is an important exception; see the SentrySQLiteStatement KDoc for more details.)

A key motivation for Google's using SQLiteDriver with Room 2.7+ was Kotlin Multiplatform support. We've been careful to keep the SentrySQLiteDriver KMP-compatible as well, should we one day want to lift it into sentry-kotlin-multiplatform.

---

Co-authored-by: Angus Holder <7407345+angusholder@users.noreply.github.com>

Author: 0xadam-brown

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Add `SentrySQLiteDriver` to `sentry-android-sqlite` for instrumenting AndroidX's `SQLiteDriver` ([#5466](https://github.com/getsentry/sentry-java/pull/5466))
+  - Automatically generates spans for all SQLite statements
+  - To use it, pass your `SQLiteDriver` to `SentrySQLiteDriver.create(...)`
+  - See https://docs.sentry.io/platforms/android/integrations/room-and-sqlite/ for more details, including info about migrating from `SentrySupportSQLiteOpenHelper`
+
 ## 8.43.0
 
 ### Features

sentry-android-sqlite/README.md

@@ -0,0 +1,21 @@
+# sentry-android-sqlite
+
+This module provides automatic SQLite query instrumentation for Android.
+
+Two instrumentation paths are supported, matching the two SQLite APIs offered by AndroidX:
+
+- **`androidx.sqlite.SQLiteDriver`** — used by Room 2.7+ via `Room.databaseBuilder(...).setDriver(...)` and by SQLDelight via its AndroidX SQLite driver.
+- **`androidx.sqlite.db.SupportSQLiteOpenHelper`** — used by legacy Room via `Room.databaseBuilder(...).openHelperFactory(...)`, or applied automatically by the Sentry Android Gradle plugin.
+
+Please consult the [Sentry Docs](https://docs.sentry.io/platforms/android/integrations/room-and-sqlite/) for usage and migration guidance, as well as how to avoid duplicate spans when using Room's `SupportSQLiteDriver` adapter.
+
+## Package layout
+
+This module is organized as two separate packages:
+
+- **`io.sentry.android.sqlite`**: Android-specific code. Classes here depend on `android.database.*` (e.g., `CrossProcessCursor`, `SQLException`) and/or on `androidx.sqlite.db.*`, the Android-only compatibility layer over the platform's SQLite. The `SentrySupportSQLiteOpenHelper` path and its span helper `SQLiteSpanManager` live here.
+- **`io.sentry.sqlite`**: Code whose contract depends only on the multiplatform `androidx.sqlite.*` interfaces (e.g., `SQLiteDriver` and `SQLiteConnection`). `SentrySQLiteDriver` and its span helper `SQLiteSpanRecorder` live here.
+
+The split anticipates the possibility of future Kotlin Multiplatform support. The `androidx.sqlite.*` driver interfaces are defined in the library's `commonMain` source set and are reused by Room across Android, JVM, and native targets. Classes in `io.sentry.sqlite` are written against those portable interfaces and are intended to lift cleanly into a KMP `commonMain` source set if/when the `sentry` core gains multiplatform targets. Classes in `io.sentry.android.sqlite` are Android-only by construction and will stay where they are.
+
+Note that the module artifact itself (`sentry-android-sqlite`) is currently an Android-only AAR regardless of package layout.

sentry-android-sqlite/api/sentry-android-sqlite.api

@@ -21,3 +21,14 @@ public final class io/sentry/android/sqlite/SentrySupportSQLiteOpenHelper$Compan
 	public final fun create (Landroidx/sqlite/db/SupportSQLiteOpenHelper;)Landroidx/sqlite/db/SupportSQLiteOpenHelper;
 }
 
+public final class io/sentry/sqlite/SentrySQLiteDriver : androidx/sqlite/SQLiteDriver {
+	public static final field Companion Lio/sentry/sqlite/SentrySQLiteDriver$Companion;
+	public synthetic fun <init> (Landroidx/sqlite/SQLiteDriver;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public static final fun create (Landroidx/sqlite/SQLiteDriver;)Landroidx/sqlite/SQLiteDriver;
+	public fun open (Ljava/lang/String;)Landroidx/sqlite/SQLiteConnection;
+}
+
+public final class io/sentry/sqlite/SentrySQLiteDriver$Companion {
+	public final fun create (Landroidx/sqlite/SQLiteDriver;)Landroidx/sqlite/SQLiteDriver;
+}
+

sentry-android-sqlite/src/main/java/io/sentry/android/sqlite/SQLiteSpanManager.kt

@@ -4,20 +4,18 @@ import android.database.CrossProcessCursor
 import android.database.SQLException
 import io.sentry.IScopes
 import io.sentry.ISpan
-import io.sentry.Instrumenter
 import io.sentry.ScopesAdapter
 import io.sentry.SentryIntegrationPackageStorage
-import io.sentry.SentryStackTraceFactory
-import io.sentry.SpanDataConvention
 import io.sentry.SpanStatus
-
-private const val TRACE_ORIGIN = "auto.db.sqlite"
+import io.sentry.sqlite.SQLiteSpanHelper
+import io.sentry.sqlite.dbMetadataFromDatabaseName
 
 internal class SQLiteSpanManager(
   private val scopes: IScopes = ScopesAdapter.getInstance(),
-  private val databaseName: String? = null,
+  databaseName: String? = null,
 ) {
-  private val stackTraceFactory = SentryStackTraceFactory(scopes.options)
+
+  private val spanHelper = SQLiteSpanHelper(scopes, dbMetadataFromDatabaseName(databaseName))
 
   init {
     SentryIntegrationPackageStorage.getInstance().addIntegration("SQLite")
@@ -45,33 +43,18 @@ internal class SQLiteSpanManager(
       if (result is CrossProcessCursor) {
         return SentryCrossProcessCursor(result, this, sql) as T
       }
-      span = scopes.span?.startChild("db.sql.query", sql, startTimestamp, Instrumenter.SENTRY)
-      span?.spanContext?.origin = TRACE_ORIGIN
+      span = spanHelper.startSpan(sql, startTimestamp)
       span?.status = SpanStatus.OK
       result
     } catch (e: Throwable) {
-      span = scopes.span?.startChild("db.sql.query", sql, startTimestamp, Instrumenter.SENTRY)
-      span?.spanContext?.origin = TRACE_ORIGIN
+      span = spanHelper.startSpan(sql, startTimestamp)
       span?.status = SpanStatus.INTERNAL_ERROR
       span?.throwable = e
       throw e
     } finally {
-      span?.apply {
-        val isMainThread: Boolean = scopes.options.threadChecker.isMainThread
-        setData(SpanDataConvention.BLOCKED_MAIN_THREAD_KEY, isMainThread)
-        if (isMainThread) {
-          setData(SpanDataConvention.CALL_STACK_KEY, stackTraceFactory.inAppCallStack)
-        }
-        // if db name is null, then it's an in-memory database as per
-        // https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:sqlite/sqlite/src/main/java/androidx/sqlite/db/SupportSQLiteOpenHelper.kt;l=38-42
-        if (databaseName != null) {
-          setData(SpanDataConvention.DB_SYSTEM_KEY, "sqlite")
-          setData(SpanDataConvention.DB_NAME_KEY, databaseName)
-        } else {
-          setData(SpanDataConvention.DB_SYSTEM_KEY, "in-memory")
-        }
-
-        finish()
+      span?.let {
+        spanHelper.applyDataToSpan(it)
+        it.finish()
       }
     }
   }

sentry-android-sqlite/src/main/java/io/sentry/sqlite/DbMetadata.kt

@@ -0,0 +1,55 @@
+package io.sentry.sqlite
+
+/**
+ * Value associated with [DB_SYSTEM_KEY][io.sentry.SpanDataConvention.DB_SYSTEM_KEY] for in-memory
+ * databases.
+ */
+internal const val DB_SYSTEM_IN_MEMORY = "in-memory"
+
+/**
+ * Value associated with [DB_SYSTEM_KEY][io.sentry.SpanDataConvention.DB_SYSTEM_KEY] for SQLite
+ * databases.
+ */
+internal const val DB_SYSTEM_SQLITE = "sqlite"
+
+/**
+ * Sentinel file name that [SQLiteDriver.open][androidx.sqlite.SQLiteDriver.open] interprets as an
+ * in-memory database:
+ * https://developer.android.com/reference/androidx/sqlite/driver/AndroidSQLiteDriver.
+ */
+private const val IN_MEMORY_DB_FILENAME = ":memory:"
+
+/** Path separators matching [File.separatorChar][java.io.File.separatorChar]. */
+private val FILE_NAME_PATH_SEPARATORS = charArrayOf('/', '\\')
+
+internal data class DbMetadata(val name: String?, val system: String)
+
+/**
+ * Resolves metadata from the [fileName] argument to
+ * [SQLiteDriver.open][androidx.sqlite.SQLiteDriver.open].
+ */
+internal fun dbMetadataFromFileName(fileName: String): DbMetadata {
+  if (fileName == IN_MEMORY_DB_FILENAME) {
+    return DbMetadata(name = null, system = DB_SYSTEM_IN_MEMORY)
+  }
+
+  val trimmed = fileName.trimEnd('/', '\\')
+  if (trimmed.isEmpty()) {
+    return DbMetadata(name = null, system = DB_SYSTEM_SQLITE)
+  }
+
+  val index = trimmed.lastIndexOfAny(FILE_NAME_PATH_SEPARATORS)
+  val basename = if (index >= 0) trimmed.substring(index + 1) else trimmed
+  return DbMetadata(name = basename.ifEmpty { null }, system = DB_SYSTEM_SQLITE)
+}
+
+/**
+ * Resolves metadata from
+ * [SupportSQLiteOpenHelper.databaseName][androidx.sqlite.db.SupportSQLiteOpenHelper.databaseName].
+ */
+internal fun dbMetadataFromDatabaseName(databaseName: String?): DbMetadata =
+  if (databaseName == null) {
+    DbMetadata(name = null, system = DB_SYSTEM_IN_MEMORY)
+  } else {
+    DbMetadata(name = databaseName, system = DB_SYSTEM_SQLITE)
+  }

sentry-android-sqlite/src/main/java/io/sentry/sqlite/SQLiteSpanHelper.kt

@@ -0,0 +1,33 @@
+package io.sentry.sqlite
+
+import io.sentry.IScopes
+import io.sentry.ISpan
+import io.sentry.Instrumenter
+import io.sentry.SentryDate
+import io.sentry.SentryStackTraceFactory
+import io.sentry.SpanDataConvention
+
+private const val SQLITE_TRACE_ORIGIN = "auto.db.sqlite"
+
+/** Shared span creation and metadata for SQLite instrumentation. */
+internal class SQLiteSpanHelper(private val scopes: IScopes, private val dbMetadata: DbMetadata) {
+
+  private val stackTraceFactory = SentryStackTraceFactory(scopes.options)
+
+  fun startSpan(sql: String, startTimestamp: SentryDate): ISpan? =
+    scopes.span?.startChild("db.sql.query", sql, startTimestamp, Instrumenter.SENTRY)?.apply {
+      spanContext.origin = SQLITE_TRACE_ORIGIN
+    }
+
+  fun applyDataToSpan(span: ISpan) {
+    val isMainThread = scopes.options.threadChecker.isMainThread
+    span.setData(SpanDataConvention.BLOCKED_MAIN_THREAD_KEY, isMainThread)
+
+    if (isMainThread) {
+      span.setData(SpanDataConvention.CALL_STACK_KEY, stackTraceFactory.inAppCallStack)
+    }
+
+    dbMetadata.name?.let { span.setData(SpanDataConvention.DB_NAME_KEY, it) }
+    span.setData(SpanDataConvention.DB_SYSTEM_KEY, dbMetadata.system)
+  }
+}

sentry-android-sqlite/src/main/java/io/sentry/sqlite/SQLiteSpanRecorder.kt

@@ -0,0 +1,45 @@
+package io.sentry.sqlite
+
+import io.sentry.IScopes
+import io.sentry.ScopesAdapter
+import io.sentry.SentryDate
+import io.sentry.SentryLevel
+import io.sentry.SentryLongDate
+import io.sentry.SpanStatus
+
+internal class SQLiteSpanRecorder(
+  fileName: String,
+  private val scopes: IScopes = ScopesAdapter.getInstance(),
+) {
+
+  private val spanHelper = SQLiteSpanHelper(scopes, dbMetadataFromFileName(fileName))
+
+  /**
+   * Returns a start timestamp for a db.sql.query span.
+   *
+   * Exposed so callers can capture a wall-clock start before accumulating database time.
+   * Internalizing the start time in [recordSpan] would shift spans to end-of-work on the trace
+   * timeline, which is less desirable.
+   */
+  fun startTimestamp(): SentryDate = scopes.options.dateProvider.now()
+
+  /** Records a db.sql.query span. */
+  @Suppress("TooGenericExceptionCaught")
+  fun recordSpan(
+    sql: String,
+    startTimestamp: SentryDate,
+    durationNanos: Long,
+    status: SpanStatus,
+    throwable: Throwable? = null,
+  ) {
+    try {
+      val span = spanHelper.startSpan(sql, startTimestamp) ?: return
+      throwable?.let { span.throwable = it }
+      spanHelper.applyDataToSpan(span)
+      val endTimestamp = SentryLongDate(startTimestamp.nanoTimestamp() + durationNanos)
+      span.finish(status, endTimestamp)
+    } catch (t: Throwable) {
+      scopes.options.logger.log(SentryLevel.ERROR, "Failed to record SQLite span.", t)
+    }
+  }
+}

sentry-android-sqlite/src/main/java/io/sentry/sqlite/SentrySQLiteConnection.kt

@@ -0,0 +1,16 @@
+package io.sentry.sqlite
+
+import androidx.sqlite.SQLiteConnection
+import androidx.sqlite.SQLiteStatement
+
+internal class SentrySQLiteConnection(
+  private val delegate: SQLiteConnection,
+  private val spanRecorder: SQLiteSpanRecorder,
+) : SQLiteConnection by delegate {
+
+  override fun prepare(sql: String): SQLiteStatement {
+    val statement = delegate.prepare(sql)
+    return statement as? SentrySQLiteStatement
+      ?: SentrySQLiteStatement(statement, spanRecorder, sql)
+  }
+}

sentry-android-sqlite/src/main/java/io/sentry/sqlite/SentrySQLiteDriver.kt

@@ -0,0 +1,66 @@
+package io.sentry.sqlite
+
+import androidx.sqlite.SQLiteConnection
+import androidx.sqlite.SQLiteDriver
+import io.sentry.ScopesAdapter
+import io.sentry.SentryIntegrationPackageStorage
+import io.sentry.SentryLevel
+
+/**
+ * Wraps a [SQLiteDriver] and automatically adds spans for each SQL statement it executes.
+ *
+ * Example usage:
+ * ```
+ * val driver = SentrySQLiteDriver.create(AndroidSQLiteDriver())
+ * ```
+ *
+ * If you use Room:
+ * ```
+ * val database = Room.databaseBuilder(context, MyDatabase::class.java, "dbName")
+ *     .setDriver(SentrySQLiteDriver.create(AndroidSQLiteDriver()))
+ *     .build()
+ * ```
+ *
+ * **Warning:** Do not use [SentrySQLiteDriver] together with
+ * [io.sentry.android.sqlite.SentrySupportSQLiteOpenHelper] on the same database file. Both wrappers
+ * instrument at different layers, so combining them will produce duplicate spans for every SQL
+ * statement.
+ *
+ * @param delegate The [SQLiteDriver] instance to delegate calls to.
+ */
+public class SentrySQLiteDriver private constructor(private val delegate: SQLiteDriver) :
+  SQLiteDriver {
+
+  init {
+    SentryIntegrationPackageStorage.getInstance().addIntegration("SQLiteDriver")
+  }
+
+  @Suppress("TooGenericExceptionCaught")
+  override fun open(fileName: String): SQLiteConnection {
+    val connection = delegate.open(fileName)
+
+    return try {
+      val spanRecorder = SQLiteSpanRecorder(fileName)
+      // create() ensures delegate is unwrapped, so we don't protect against double-wrapping the
+      // connection.
+      SentrySQLiteConnection(connection, spanRecorder)
+    } catch (t: Throwable) {
+      ScopesAdapter.getInstance()
+        .options
+        .logger
+        .log(
+          SentryLevel.ERROR,
+          "Failed to instrument SQLite connection; returning uninstrumented connection.",
+          t,
+        )
+      connection
+    }
+  }
+
+  public companion object {
+
+    @JvmStatic
+    public fun create(delegate: SQLiteDriver): SQLiteDriver =
+      delegate as? SentrySQLiteDriver ?: SentrySQLiteDriver(delegate)
+  }
+}