Room and SQLite

Learn more about the Sentry Room and AndroidX SQLite integrations for the Android SDK.

Supported in Sentry's Android SDK version 4.0.0 and above.

Supported in Sentry Android Gradle Plugin version 3.0.0 and above.

Custom instrumentation is supported in Sentry's Android SDK, version 6.21.0 and above.

The Sentry Android Gradle Plugin provides Room and AndroidX SQLite support through bytecode manipulation. The source can be found on GitHub.

On this page, we get you up and running with Sentry's Room and SQLite Integration, so that it will automatically start a span from an active transaction that's bound to the scope of each sqlite/dao query.

To use the Room and AndroidX SQLite integration, add the Sentry Android Gradle plugin and the Sentry Android SDK (version 4.0.0 or above) in build.gradle:

Copied
plugins {
  id "io.sentry.android.gradle" version "4.11.0"
}

dependencies {
  implementation 'io.sentry:sentry-android:7.13.0'
}

Make sure, that tracing is enabled.

In general, no further configuration is required as the auto-instrumentation is enabled by default. If you would like to disable the database instrumentation feature, we expose a configuration option for that:

Copied
import io.sentry.android.gradle.extensions.InstrumentationFeature

sentry {
  tracingInstrumentation {
    enabled = true
    features = EnumSet.allOf(InstrumentationFeature) - InstrumentationFeature.DATABASE
  }
}

Supported in Sentry's Android SDK, version 6.21.0 and above.

Sentry captures data by wrapping a SupportSQLiteOpenHelper.Factory. To add the SQLite integration, initialize the Android SDK, then add the sentry-android-sqlite dependency using Gradle:

Copied
implementation 'io.sentry:sentry-android:7.13.0'
implementation 'io.sentry:sentry-android-sqlite:7.13.0'

No configuration is required. Just wrap your SupportSQLiteOpenHelper instance in SentrySupportSQLiteOpenHelper.

Copied
import io.sentry.android.sqlite.SentrySupportSQLiteOpenHelper

private val myOpenHelper = MyOpenHelper()
private val instrumentedOpenHelper = SentrySupportSQLiteOpenHelper.create(myOpenHelper)

Room is supported when using the default FrameworkSQLiteOpenHelperFactory provided by the androidx.sqlite package, but any custom SupportSQLiteOpenHelper can be used.

Copied
import androidx.room.Room
import io.sentry.android.sqlite.SentrySupportSQLiteOpenHelper

val database = Room.databaseBuilder(context, MyDatabase::class.java, "dbName")
    .openHelperFactory { configuration ->
        SentrySupportSQLiteOpenHelper.create(FrameworkSQLiteOpenHelperFactory().create(configuration))
    }
    .build()

Assuming you have the following (reduced) code snippet performing a database query on a Room Dao:

Copied
import android.os.Bundle
import android.widget.Button
import androidx.activity.ComponentActivity
import androidx.room.Database
import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.RoomDatabase
import io.sentry.Sentry
import io.sentry.SpanStatus
import kotlinx.coroutines.withContext

@Dao
abstract class TracksDao {
  @Insert(onConflict = OnConflictStrategy.REPLACE)
  abstract suspend fun insert(track: Track): Long
}

@Database(
  entities = [Track::class],
  version = 1,
  exportSchema = false
)
abstract class TracksDatabase : RoomDatabase() {
    abstract fun tracksDao(): TracksDao
}

class EditActivity : ComponentActivity() {
  private lateinit var database: TracksDatabase

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    database = TODO("initialize database...")

    findViewById<Button>(R.id.editTrack).setOnClickListener {
      val transaction = Sentry.startTransaction(
        name = "Track Interaction",
        operation = "ui.action.edit",
        bindToScope = true
      )

      val newTrack = Track(/* fill in track values */)

      withContext(Dispatchers.IO) {
        database.tracksDao().insert(newTrack)
        transaction.finish(SpanStatus.OK)
      }
    }
  }
}

To view the recorded transaction, log into sentry.io and open your project. Clicking on Performance will open a page with transactions, where you can select the just recorded transaction with the name Track Interaction. The event will look similar to this:

Room and AndroidX SQLite performance instrumentation

The Sentry Android Gradle plugin will report SQL queries for any SupportSQLiteOpenHelper.Factory, starting with version 3.11.0.

Earlier versions will only support standard androidx.room usage and won't report SQL queries for any SupportSQLiteOpenHelper.Factory other than androidx.sqlite.

If you're having trouble with this SDK, we want to hear about it. Create an issue on GitHub and describe your experience.

If you are directly using SupportSQLiteDatabase#query or SupportSQLiteDatabase#execSQL methods through the Room's SQLiteOpenHelper, consider switching to their alternatives that accept bindArgs as a second parameter.

Because Sentry captures SQL queries as Span description, there is a risk of leaking sensitive data when not using an SQL string with placeholders.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").