feat(plugin): Auto-instrument SQLiteDriver for Room users (GRADLE-107)

[0xadam-brown]

📜 Description

Adds a new bytecode method visitor that lets us auto-wrap all occurrences of SQLiteDriver with SentrySQLiteDriver whenever the driver is passed to Room.DatabaseBuilder.setDriver(SQLiteDriver) (Room's sole driver access point – see the "Coverage" section from #1281 for why we don't need to worry about anything else).

In other words, this:

val database = Room.databaseBuilder(context, MyDatabase::class.java, "dbName")
     .setDriver(AndroidSQLiteDriver())
     .build()

becomes:

val database = Room.databaseBuilder(context, MyDatabase::class.java, "dbName")
     .setDriver(SentrySQLiteDriver.create(AndroidSQLiteDriver()))
     .build()

The wrapping policy is naive in that every SQLiteDriver passed to Room.DatabaseBuilder.setDriver() is wrapped. That's deliberate because SentrySQLiteDriver protects against double-wrapping internally, which lets us keep our visitor implementation simple.

💡 Motivation and Context

Room 2.7 introduced RoomDatabase.Builder.setDriver(SQLiteDriver) as the new way to configure an underlying SQLite implementation (link), with the intention of eventually replacing SupportSQLiteOpenHelper. (Room 3.0+ does just that.)

The Sentry Android Gradle Plugin currently auto-instruments only the open helper path. Apps that adopt the driver-based API will lose automatic SQL performance instrumentation unless they manually wrap their driver with SentrySQLiteDriver.create(...) at every setDriver(...) call site.

This PR provides auto-wrapping for the driver path too.

Addresses GRADLE-107 / #1281

Preconditions

1. sentry-android-sqlite version in the SAGP build must include SentrySQLiteDriver
2. InstrumentationFeature.DATABASE must be enabled (⚠️ in other words, we piggyback on the existing DATABASE toggle used to auto-instrument the SupportSQLiteOpenHelper + Room DAO spans)

Coverage

• Auto-wraps SQLiteDriver for all Room users.
• SQLDelight users don't need driver auto-wrapping (they still use SupportSQLiteOpenHelper, which we already auto-instrument).
• The few developers who use SQLiteDriver directly will need to wrap it manually.

Impact on build times

Near zero. The new instrumentation gates on a two-entry allowlist (androidx.room.RoomDatabase$Builder / androidx.room3.RoomDatabase$Builder), which means 0-1 classes will be visited per build in virtually all scenarios. The rest of the per-class cost is a single Set.contains check.

Interactions with other db instrumentation

SupportSQLiteOpenHelper

Driver instrumentation operates alongside our existing instrumentation of SupportSQLiteOpenHelper. (It's fine to use both drivers and open helpers in the same project, so long as a given db file is associated with exactly one of them. Room's APIs help enforce that restriction.)

The Sentry Android SDK – and not the SAGP – is responsible for protecting against double-wrapping and duplicate spans. In general that's easy (just check the type being passed to the wrapper). In the case of the SupportSQLiteDriver used with Room [2.7, 3.0) things get a bit trickier, as it's both a driver and consumes an open helper. But the SDK has that covered as well (see #5514).

Room DAO methods

Driver instrumentation also operates in tandem with our existing Room DAO spans – in theory, at least. Unfortunately DAO instrumentation broke under API changes in Room 2.7, which is the same version that introduced SQLiteDriver. So for now the two are never active at the same time. Fixing that is a task for another day...

💚 How did you test it?

[1] Added unit tests + integration tests in this PR

[2] Verified that all the (for now) @Ignored integration tests pass against a local sentry-java SDK artifact containing SentrySQLiteDriver.

[3] Built out a local version of the Sentry Android sample app that let me manually test SAGP + sentry-java compatibility end-to-end. Verified that auto-instrumentation of SQLiteDriver works as expected.

📝 Checklist

• I reviewed the submitted code
• I added tests to verify the changes
• I updated the docs if needed
• No breaking changes

🔮 Next steps

• Merge updates to sentry-docs (#18489)
• Consider a CI cron job that checks Room's latest API for changes that would impact our implementation here and in the Sentry Android SDK.

[github-actions]

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 41fba8c

[linear-code]

GRADLE-107

[runningcode]

Thanks this looks good! I just don't think I'm enough of an expert in how we instrument classes to approve this.
I left some questions for my better understanding of the patterns we are using.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2ee2ad8. Configure here.}

[romtsn]

nicely done, hats off!