📜 Description

PR protects against generating duplicate db.sql.query spans when using the androidx.sqlite.driver.SupportSQLiteDriver bridge.

💡 Motivation and Context

The bridge is the sole Room (or SQLDelight) API that leaves open the possibility of using SentrySQLiteDriver and SentrySupportSQLiteOpenHelper together with the same db file – a possibility that would lead to redundant spans.

Example misuse this PR guards against

// Step 1: Developer wraps their open helper with Sentry, either manually or
// via the Sentry Android Gradle Plugin.
val sentryWrappedHelper: SupportSQLiteOpenHelper =
    SentrySupportSQLiteOpenHelper.create(
        FrameworkSQLiteOpenHelperFactory().create(configuration)
    )

// Step 2: Developer builds the support driver around that wrapped helper.
val driver: SQLiteDriver = SupportSQLiteDriver(sentryWrappedHelper)

// Step 3: Developer (wrongly) wraps the bridge with Sentry as well. All
// spans would be duplicated were it not for this PR, which returns 
// SupportSQLiteDrivers unwrapped.
val sentryWrappedDriver: SQLiteDriver = SentrySQLiteDriver.create(driver)

Room.databaseBuilder(context, MyDb::class.java, "mydb")
    .setDriver(sentryWrappedDriver)
    .build()

Addresses JAVA-275

⚠️ Callouts

[1] I've covered the no-span edge case via documentation: It's possible to use SupportSQLiteDriver without wrapping the open helper passed via its constructor, resulting in no spans being produced. That a temporary concern, as SupportSQLiteDriver goes away with Room 3.0+; the blast radius should also be limited, as most of our users rely on the Sentry Android Gradle Plugin to auto-wrap the open helper. I've flagged the issue in the CHANGELOG and the SentrySQLiteDriver KDoc.

[2] Support driver has open helper span semantics: Users who rely on SupportSQLiteDriver will have their spans auto-generated via the open helper, and so the span semantics will match its behavior rather than that of SQLiteDriver (for more details about SQLiteDriver's span policy, see here). (Wrapping the SQLiteDriver would've required reflection, which I wanted to avoid for performance reasons and to make it easier to eventually lift the driver into KMP common.)

[3] Changes in this PR are needed if we want to use ASM auto-wrapping: I've a forthcoming PR that introduces ASM auto-wrapping of SQLiteDriver via the Sentry Android Gradle Plugin. The approach in this PR makes that auto-wrapping safe, as SAGP will always convert the SQLiteDriver passed to RoomDatabase.Builder.setDriver(SQLiteDriver) into SentrySQLiteDriver.create(SQLiteDriver). If the provided driver is a SupportSQLiteDriver, this PR ensures SentrySQLiteDriver.create(SQLiteDriver) will return it unwrapped.

💚 How did you test it?

[1] Created a new "Bridge" section in the Android sample app that wires up the SupportSQLiteDriver and provides it with both a SentrySupportSQLiteOpenHelper and a SentrySQLiteDriver:

[2] Verified via the Sentry UI that spans are not duplicated:

Baseline: Existing behavior of SentrySupportSQLiteOpenHelper

This PR: Behavior of SupportSQLiteDriver

📝 Checklist

• I added GH Issue ID & Linear ID
• I added tests to verify the changes.
• No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
• I updated the docs if needed.
• I updated the wizard if needed.
• Review from the native team if needed.
• No breaking change or entry added to the changelog.
• No breaking change for hybrid SDKs or communicated to hybrid SDKs.

🔮 Next steps