[joker-777]

Fixes two defects in the legacy (non-JSI) SQLite adapter path, i.e. SQLiteAdapter with jsi: false on iOS and Android. The JSI path (native/shared/DatabaseBridge.cpp) is unchanged.

Related upstream issues: Nozbe#1845 (app crashes at launch instead of reaching onSetUpError), Nozbe#1609 (adapter unusable after a failed migration).

Defect 1: setup failures crash instead of rejecting (iOS) / are uncaught (Android)

On iOS, WMDatabase, WMDatabaseDriver and WMDatabaseBridge raised NSExceptions inside async RCT_EXPORT_METHODs. React Native's TurboModule interop only converts an NSException to a JS error for synchronous methods; for async ones it re-throws and the process dies. So a database file that cannot be opened crash-loops at launch and the JS onSetUpError callback never runs. Android's setUpWithSchema had no try/catch, unlike initialize and setUpWithMigrations.

Fix: WMDatabase open / setUserVersion and the driver's setUpWithSchema / setUpWithMigrations report through NSError ** (same pattern as the other WMDatabase methods), driverWithName: / databaseWithPath: return nil with an error when the database cannot be opened, and the bridge rejects with the existing db.<method>.error codes. Android's setUpWithSchema is wrapped like setUpWithMigrations.

Defect 2: no driver after a failed migration

Both bridges called disconnectDriver after a failed migration, which removed the driver for the tag. On iOS it also removed the queue, so the operations queued during startup never settled and every later call, including unsafeResetDatabase, hung silently ([nil addObject:] is a no-op). On Android every later call was rejected with No driver with tag N available. The database itself is consistent after a failed migration (it runs in one transaction with rollback), so there was nothing preventing recovery except the missing driver.

Fix: on a failed schema setup or migration, the operations queued while waiting for setup are rejected with the setup error, and the driver stays connected so JS can recover (e.g. database.unsafeResetDatabase(), which is what the Kenhub companion does from its onSetUpError handler). If the database could not be opened at all, there is no driver to keep: iOS now rejects later calls instead of hanging, Android keeps a Connection.Failed state and rejects them with the open error.

On Android the bridge now creates the driver with the plain constructor and calls unsafeResetDatabase / migrate on it (so the driver instance survives a failure instead of being lost in a throwing constructor, which also leaked its open SQLiteDatabase). WMDatabaseDriver.migrate becomes package-private for that.

Failure paths, before and after

Path	Before	After
iOS: database file cannot be opened during initialize	NSException OpenFailed → process crash, onSetUpError never runs	initialize rejects with db.initialize.error; onSetUpError runs; later calls reject with No driver with tag N available
iOS: database cannot be (re)opened during setUpWithSchema / setUpWithMigrations	NSException → crash	promise rejects; queued operations rejected with the same error; later calls reject
iOS: schema SQL fails in setUpWithSchema	NSException SetUpWithSchemaFailed → crash	rejects with db.setUpWithSchema.error; queued operations rejected with the setup error; driver stays connected, unsafeResetDatabase works
iOS: migration SQL fails or user_version cannot be set	rejected, but driver and queue removed: queued promises never settle, every later call (incl. unsafeResetDatabase) hangs forever	rejects with db.setUpWithMigrations.error; queued operations rejected with the setup error; driver stays connected, unsafeResetDatabase works
iOS: DB version does not match the migration set's fromVersion	NSException IncompatibleMigrations → crash	rejects with Incompatible migration set applied. DB: X, migration: Y (same recovery as above)
iOS: unexpected WMDatabaseCompatibility in initialize	NSException BadArgument → crash	rejects with db.initialize.error
iOS: operation for a tag with neither driver nor queue	silently dropped, promise never settles	rejects with No driver with tag N available
Android: setUpWithSchema throws (open fails, schema SQL fails)	uncaught exception from a @ReactMethod → native crash	rejects; queued operations rejected with the setup error; driver stays connected if the DB opened
Android: setUpWithMigrations throws	rejected, but driver removed: queued and all later calls rejected with No driver with tag N available	rejects; queued operations rejected with the setup error; driver stays connected, unsafeResetDatabase works
Android: database cannot be opened in setUpWith*	(crash / "No driver")	rejects; later calls rejected with the open error (Connection.Failed)

Unchanged on purpose: Android initialize still throws IllegalStateException when the tag is already set up (iOS rejects), and the JSI path.

What was and was not verified

• Android: verified on an emulator. native/androidTest (./gradlew connectedAndroidTest, React Native 0.74.6 test app, Pixel-class AVD, API 36 x86_64) was built with this branch and run with a dev bundle served by Metro. All 244 shared adapter tests pass in both the async-mode and JSI-mode configurations, including errors when migration fails with the new async-bridge assertions (queued operation rejected with the setup error, then unsafeResetDatabase, write and query on the same adapter) and all other migration/reset tests. The Java bridge changes compiled as part of that build. Two local, uncommitted tweaks were needed only to run on a modern emulator: adding x86_64 to the test app's abiFilters (the AVD has no 32-bit x86 ABI) and forwarding Metro with adb reverse.
• iOS was not compiled here. This machine has no Xcode, so the iOS changes were reviewed by reading only. They mirror the NSError ** / BRIDGE_METHOD / WITH_DRIVER patterns already used in these files and the existing try/catch in the Android bridge. The iOS side still needs a build of the Kenhub companion (Expo SDK 58, React Native 0.88.1) or yarn test:ios on a Mac, ideally with a deliberately broken migration (and an unreadable database file) to exercise onSetUpError → unsafeResetDatabase.
• The JS adapter itself is unchanged: it already handles a rejected setUpWithMigrations / setUpWithSchema (_initPromise rejects and devSetupCallback calls onSetUpError) and keeps dispatching to the same tag afterwards.
• Regression test: the shared adapter test errors when migration fails (src/adapters/__tests__/commonTests.js) now also checks, for the asynchronous (non-JSI) SQLite dispatcher, that an operation issued while the failing migration runs is rejected with the setup error, and that the same adapter can then unsafeResetDatabase, write and query. It runs on device through src/adapters/sqlite/integrationTest.js (async-mode configuration; the JSI configuration is skipped because the JSI bridge asserts on operations before setup) and under jest through the sqlite-node bridge.
• src/adapters/sqlite/sqlite-node/DatabaseBridge.js is the JS mirror of the native bridges and had the same disconnect-on-failure behaviour, so it now mirrors the fix (keep driver, reject queued operations with the setup error, catch setUpWithSchema). Verified under jest with Node 22: the new test fails against the old node bridge (No driver for with tag N available) and passes with the new one; the full src/adapters/sqlite suite (135 tests) passes, and eslint is clean.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

A critical issue remains: failed database reopening can still publish a non-nil driver as connected, causing later operations to use an unopened database and potentially preventing reset retries.

1 open issue

• Do not retain a driver when database reopening fails · New

What changed in this PR

This PR improves setup-error handling and recovery in the legacy, non-JSI SQLite bridges on iOS and Android. The JSI path is unchanged.

Changes:

• Converts native setup failures into rejected promises.
• Rejects queued operations after setup failure while retaining available drivers for recovery.
• Adds Android connection-failure state and documents the behavior.

File	Description
native/​ios/​WatermelonDB/​objc/​WMDatabaseDriver.m	Propagates initialization, schema, and migration errors.
native/​ios/​WatermelonDB/​objc/​WMDatabaseDriver.h	Declares error-reporting driver APIs.
native/​ios/​WatermelonDB/​objc/​WMDatabaseBridge.m	Rejects setup failures and settles queued operations.
native/​ios/​WatermelonDB/​objc/​WMDatabase.m	Reports open, reopen, and version-update errors.
native/​ios/​WatermelonDB/​objc/​WMDatabase.h	Declares error-reporting database APIs.
native/​android/​src/​main/​java/​com/​nozbe/​watermelondb/​WMDatabaseDriver.java	Makes migration execution accessible to the bridge.
native/​android/​src/​main/​java/​com/​nozbe/​watermelondb/​WMDatabaseBridge.java	Catches setup failures and preserves drivers for recovery.
native/​android/​src/​main/​java/​com/​nozbe/​watermelondb/​Connection.java	Adds a failed connection state carrying the setup error.
CHANGELOG-Unreleased.md	Documents legacy SQLite error handling and recovery.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

An async-bridge regression test is still needed on iOS and Android to verify queued-operation rejection during failed migration and successful reset, write, and query using the same adapter/tag.

1 open issue

• Test async bridge recovery after failed migration · New

1 resolved since last review

• Do not retain a driver when database reopening fails

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The native iOS and Android changes lack build and device validation for setup-error rejection, queued-operation settlement, and reset recovery, including iOS database-open failures.

1 open issue

• Test async bridge recovery after failed migration

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Native builds and on-device failure-injection checks are still needed to validate iOS/Android promise rejection and database reset recovery.

1 open issue

• Test async bridge recovery after failed migration

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Schema-setup failures still leave Android reset unable to recover from an empty database and the Node bridge treating a closed SQLite handle as connected.

2 open issues

• Handle empty cursor when listing tables during database reset · New
• Do not retain driver after database handle is closed · New

1 resolved since last review

• Test async bridge recovery after failed migration

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The native bridge changes need iOS and Android builds and on-device failure-path tests to validate promise rejection, queued-operation settlement, and reset recovery.

1 open issue

• Handle empty cursor when listing tables during database reset

1 resolved since last review

• Do not retain driver after database handle is closed

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The iOS and Android bridge failure/recovery paths still require native builds and on-device validation of async rejection, queued-operation settlement, and same-tag database reset recovery.

No open issues 🎉

1 resolved since last review

• Handle empty cursor when listing tables during database reset

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The iOS/Android bridge changes remain uncompiled and untested on-device, requiring native validation of failure handling, queued promise settlement, and same-adapter reset recovery.

No open issues 🎉

_{Review effort: Balanced}

[joker-777]

Offered upstream as Nozbe#1981, rebuilt on upstream master.