feat(database)!: migrate database to TurboModules

Author: mikehardy

jest.setup.ts

@@ -252,59 +252,6 @@ jest.doMock('react-native', () => {
           sendUnsentReports: jest.fn(),
           setCrashlyticsCollectionEnabled: jest.fn(),
         },
-        RNFBDatabaseModule: {
-          constants: {
-            isDatabaseCollectionEnabled: true,
-            url: 'https://test.firebaseio.com',
-            ref: 'ref()',
-          },
-          on: jest.fn(),
-          off: jest.fn(),
-          once: jest.fn(
-            (_appName: any, _customUrl: any, path: any, _modifiers: any, eventType: any) => {
-              // Database native methods receive (appName, customUrlOrRegion, ...actualArgs)
-              let key = 'test';
-              if (path && typeof path === 'string') {
-                const parts = path.split('/').filter(p => p);
-                key = parts[parts.length - 1] || 'test';
-              }
-
-              const snapshotData = {
-                key,
-                value: null,
-                exists: false,
-                childKeys: [],
-                priority: null,
-              };
-
-              if (eventType === 'value') {
-                return Promise.resolve(snapshotData);
-              }
-
-              return Promise.resolve({
-                snapshot: snapshotData,
-                previousChildName: null,
-              });
-            },
-          ),
-          useEmulator: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          set: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          update: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          setWithPriority: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          remove: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          setPriority: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          keepSynced: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          transactionStart: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          transactionTryCommit: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          goOnline: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          goOffline: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          setPersistenceEnabled: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          setLoggingEnabled: jest.fn((_appName: any, _customUrl: any) => Promise.resolve()),
-          setPersistenceCacheSizeBytes: jest.fn((_appName: any, _customUrl: any) =>
-            Promise.resolve(),
-          ),
-          getServerTime: jest.fn((_appName: any, _customUrl: any) => Promise.resolve(Date.now())),
-        },
         NativeRNFBTurboFirestore: {
           setLogLevel: jest.fn(),
           loadBundle: jest.fn(() =>
@@ -385,6 +332,45 @@ jest.doMock('react-native', () => {
             }),
           ),
         },
+        NativeRNFBTurboDatabase: {
+          goOnline: jest.fn(() => Promise.resolve()),
+          goOffline: jest.fn(() => Promise.resolve()),
+          setPersistenceEnabled: jest.fn(),
+          setLoggingEnabled: jest.fn(),
+          setPersistenceCacheSizeBytes: jest.fn(),
+          useEmulator: jest.fn(),
+        },
+        NativeRNFBTurboDatabaseReference: {
+          set: jest.fn(() => Promise.resolve()),
+          update: jest.fn(() => Promise.resolve()),
+          setWithPriority: jest.fn(() => Promise.resolve()),
+          remove: jest.fn(() => Promise.resolve()),
+          setPriority: jest.fn(() => Promise.resolve()),
+        },
+        NativeRNFBTurboDatabaseQuery: {
+          once: jest.fn(() =>
+            Promise.resolve({
+              value: null,
+              key: null,
+              exists: false,
+              childKeys: [],
+            }),
+          ),
+          on: jest.fn(),
+          off: jest.fn(),
+          keepSynced: jest.fn(() => Promise.resolve()),
+        },
+        NativeRNFBTurboDatabaseOnDisconnect: {
+          onDisconnectCancel: jest.fn(() => Promise.resolve()),
+          onDisconnectRemove: jest.fn(() => Promise.resolve()),
+          onDisconnectSet: jest.fn(() => Promise.resolve()),
+          onDisconnectSetWithPriority: jest.fn(() => Promise.resolve()),
+          onDisconnectUpdate: jest.fn(() => Promise.resolve()),
+        },
+        NativeRNFBTurboDatabaseTransaction: {
+          transactionStart: jest.fn(),
+          transactionTryCommit: jest.fn(),
+        },
         NativeRNFBTurboFiam: {
           getConstants: () => ({
             isMessagesDisplaySuppressed: false,

okf-bundle/new-architecture/migration-work-queue.md

@@ -8,7 +8,7 @@ timestamp: 2026-06-26T00:00:00Z
 
 # TurboModule migration — work queue
 
-> **IN PROGRESS (2026-07-02):** Phase **4** — **next pickup:** `database` + remaining Tier A/B. P4m committed; P4a events deferred to Phase C ([ADR-4](architecture-decisions.md#newarch-ad-4--events-deferred-to-phase-c--accepted)).
+> **IN PROGRESS (2026-07-02):** Phase **4** remaining complex — P4d `database` committed; next pickup from phase table (Tier A/B packages not yet queued).
 > **Goal/order:** app foundation → hard probe → easy wins → remaining complex → sync conversion → coordinated break → cleanup (events, shared-state encapsulation). Decisions: [architecture-decisions.md](architecture-decisions.md). Links: [implementation workflow](turbomodule-implementation-workflow.md), [change authoring](../testing/change-authoring-workflow.md), [functions reference](../../../packages/functions/) ([PR #8603](https://github.com/invertase/react-native-firebase/pull/8603)).
 
 Ephemeral tracker; see [OKF policy](../documentation-policy.md).
@@ -322,11 +322,11 @@ Skip steps 1–2 when spec shape is known (most Tier D packages).
 
 ## Current snapshot
 
-**Label:** `phase-4-messaging` (2026-07-02); **harness:** area-focused (`messaging`)
+**Label:** `phase-4-database` (2026-07-02); **harness:** area-focused (`database`)
 
-**Next item:** Phase **4** `messaging` TurboModule migration
+**Next item:** Phase **4** remaining complex (pick next Tier A/B package — no arbiter row yet)
 
-**Current gates:** P4m committed. **Next:** Phase 4 `database` (or next Tier A/B item).
+**Current gates:** P4d all gates **closed** — committed `feat(database)!: migrate database to TurboModules` 2026-07-02. Delta review: macOS 213 / iOS 219 / Android 220 passing.
 
 **Host rule:** one `:test-cover` at a time — never parallel subagents with e2e.
 
@@ -357,6 +357,7 @@ Skip steps 1–2 when spec shape is known (most Tier D packages).
 | Phase 3.5 guardrails | P3.5 | **closed** | **closed** | **closed** | done | `full` | `fix: add codegen verify and spec-native parity tests` | Committed `64f99c53d` 2026-07-02. |
 | Phase 4a messaging event decision | P4a | n/a | n/a | n/a | done | `none` | none | **Defer** events to Phase C — [NewArch-AD-4 § messaging](architecture-decisions.md#messaging--defer-eventemitter-cutover-migrate-shell-only-in-phase-4). |
 | Phase 4 `messaging` TurboModules | P4m | **closed** | **closed** | **closed** | done | `area-focused` | `feat(messaging)!: migrate messaging to TurboModules` | Turbo shell only (AD-4 event path preserved). Jest 38/38 + parity 32/32; codegen:verify incl messaging; legacy Java removed. iOS/Android area e2e green on method-call + listener-registration scope. Foreground `onMessage` delivery test **left `xit`** — flaky FCM harness; re-enable in [Phase C](#deferred-cleanup-phase-eventemitter). |
+| Phase 4 `database` TurboModules | P4d | **closed** | **closed** | **closed** | done | `area-focused` | `feat(database)!: migrate database to TurboModules` | 5 Turbo specs/shells + committed codegen; Jest 49 + parity 38; area e2e macOS 213 / iOS 219 / Android 220 (delta logs `/tmp/rnfb-e2e-*-database-delta-review.log`). Remediation: invalidate/teardown parity (Reference+Transaction), onComplete guard, contract test 22 methods, jest mock cleanup. Orchestration: macOS/Android `:8090` pre-flight in `firebase.test.js` + OKF. **Deferred minor:** void spec vs Promise JS API; silent Query `RejectedExecutionException` post-invalidate. |
 | Phase Docs — NA reqs + consolidation | PDoc | open | open | open | documentation | `none` | `docs: new-architecture requirements + migration consolidation` | Opportunistic; does not gate 4. |
 | Phase PD — platform divergence | PPD | open | open | open | documentation | `none` | `docs(<pkg>): …` per package | Opportunistic; gap-analysis first. |
 | Phase R — remove `NativeModules` fallback | PR-fallback | open | open | open | pre-merge-validation | `full` | (Phase R) | Decision B. Jest + `app` e2e "unknown module throws". |

okf-bundle/testing/running-e2e.md

@@ -97,10 +97,11 @@ macOS: `yarn tests:macos:test-cover` only — same `:8090` transport, no Detox.
 
 **Launch gate (orchestration race fix)** — `firebase.test.js` starts the test runner with `RNFB_JET_DEFER_RUN=1`. It listens on 8090 and **defers** `server.run()` until the host signals launch success:
 
-1. Host waits for TCP **8090**, then Metro (debug) if needed, then `launchAppWithRetry`.
-2. Host `POST`s **`/orchestrate-state`** (`{ "phase": "launch-pending" | "launch-ok" | … }`) to the control port (best-effort diagnostics).
-3. After `launchApp` succeeds, host `POST`s **`/launch-ready`** → test runner calls `server.run()` and the app may receive the mocha-remote `run` action.
-4. Mocha tests must not start during a stuck or retried `launchApp`; on inner launch retry the host may kill and respawn the test runner before `terminateApp`/simulator reboot.
+1. On Android, host force-stops both test packages and clears any stray **8090** listener before spawning Jet.
+2. Host waits for TCP **8090**, then Metro (debug) if needed, then `launchAppWithRetry`.
+3. Host `POST`s **`/orchestrate-state`** (`{ "phase": "launch-pending" | "launch-ok" | … }`) to the control port (best-effort diagnostics).
+4. After `launchApp` succeeds, host `POST`s **`/launch-ready`** → test runner calls `server.run()` and the app may receive the mocha-remote `run` action.
+5. Mocha tests must not start during a stuck or retried `launchApp`; on inner launch retry the host may kill and respawn the test runner before `terminateApp`/simulator reboot.
 
 **Log markers** — `[rnfb-e2e] orchestrate-state=…`, `[jet-control] deferring server.run until POST /launch-ready`, `[jet-control] launch-ready received`, `[jet-control] listening on http://…:8091`, `[jet-coverage] …`, `Jet client connected`.
 
@@ -165,15 +166,34 @@ No in-flight test run on the target platform:
 
 | Platform | Clear when |
 |----------|------------|
-| **Android** | [Host-clear probes](#host-clear-probes) pass (no instrumentation PID) |
+| **Android** | [Android app reset](#android-app-reset-blocking) + [host-clear probes](#host-clear-probes) pass |
 | **iOS** | [Host-clear probes](#host-clear-probes) pass — **zero booted simulators** and no stray listener on `:8090`. Detox boots `iPhone 17` from `tests/.detoxrc.js`; do not pre-boot or leave simulators running. |
 | **macOS** | [Host-clear probes](#host-clear-probes) pass (no `io.invertase.testing` process) |
 
 Also wait for any visible unfinished `yarn tests:*:test-cover`.
 
+<a id="android-app-reset-blocking"></a>
+
+**Android app reset (blocking)** — run **before every** Android `:test-cover`, not only after a failed run:
+
+```bash
+adb -s emulator-5554 shell am force-stop com.invertase.testing
+adb -s emulator-5554 shell am force-stop com.invertase.testing.test
+```
+
+The main app (`com.invertase.testing`) can sit on **“waiting for jet to start tests…”** while the [host-clear probe](#host-clear-probes) still passes (it only checks `com.invertase.testing.test`). A stale main app then connects as a **second Jet client** after Detox launches a fresh run → `Received a message from the client, but server wasn't running` and no Mocha summary. Force-stop **both** packages, then re-run the probe.
+
+On **darwin** hosts, also clear the macOS test app before Android `:test-cover` — macOS and Android share Jet **`:8090`**. Alternating macOS and Android runs without killing `io.invertase.testing` leaves a stale macOS Jet client that connects when Android starts → duplicate clients and `server wasn't running`.
+
+```bash
+! pgrep -x io.invertase.testing >/dev/null 2>&1
+```
+
+(`firebase.test.js` runs this automatically via `ensureAndroidJetHostClear` before spawning Android Jet; use the probe manually when prepping from the runbook.)
+
 <a id="host-clear-probes"></a>
 
-**Host-clear probes** — run the block for your platform; **exit 0 = clear** (chain with `&&`):
+**Host-clear probes** — run after [Android app reset](#android-app-reset-blocking) (Android) or directly (iOS/macOS); **exit 0 = clear** (chain with `&&`):
 
 ```bash
 # iOS — booted-device count must be 0
@@ -189,12 +209,13 @@ test -z "$(lsof -nP -iTCP:8090 -sTCP:LISTEN -t 2>/dev/null || true)"
 
 <a id="pre-flight-recovery"></a>
 
-**Pre-flight recovery** — when probes fail after abort, kill, or `EADDRINUSE` on `:8090`. Then re-run [host-clear probes](#host-clear-probes).
+**Pre-flight recovery** — when probes fail **after** [Android app reset](#android-app-reset-blocking), abort, kill, or `EADDRINUSE` on `:8090`. Before any new `:test-cover`, kill the stray **8090** listener, re-run force-stop (Android) or the iOS/macOS steps below, then [host-clear probes](#host-clear-probes).
 
 ```bash
-# Android
+# Android — force-stop both apps, then clear the Jet WS listener
 adb -s emulator-5554 shell am force-stop com.invertase.testing
 adb -s emulator-5554 shell am force-stop com.invertase.testing.test
+lsof -nP -iTCP:8090 -sTCP:LISTEN -t | xargs kill 2>/dev/null || true
 
 # iOS — Detox re-boots iPhone 17 after shutdown booted
 lsof -nP -iTCP:8090 -sTCP:LISTEN -t | xargs kill 2>/dev/null || true
@@ -203,6 +224,8 @@ pkill -f 'jet.js --target=ios' 2>/dev/null || true
 xcrun simctl shutdown booted
 ```
 
+After Android recovery, verify `pidof com.invertase.testing.test` is empty and `:8090` is closed before rerunning `:test-cover`.
+
 Do **not** use `boot-simulator.sh` or `simctl shutdown all` as routine prep ([what not to do](#what-not-to-do)).
 
 #### 2. Services ready
@@ -332,7 +355,7 @@ Each run owns its blocking `:test-cover` and returns summaries only.
 
 ### Interrupted run (abort, killed terminal, EADDRINUSE on :8090)
 
-Run [pre-flight recovery](#pre-flight-recovery), confirm [host-clear probes](#host-clear-probes) pass, then rerun from repo root: `yarn tests:<platform>:build && yarn tests:<platform>:test-cover` (foreground; tee if logging).
+Run [pre-flight recovery](#pre-flight-recovery), confirm [host-clear probes](#host-clear-probes) pass, then rerun from repo root: `yarn tests:<platform>:build && yarn tests:<platform>:test-cover` (foreground; tee if logging). Keep one `:test-cover` active at a time on a host.
 
 ### What not to do
 

packages/app/__tests__/specNativeParityHelper.ts

@@ -22,6 +22,7 @@ export const MIGRATED_TURBO_PACKAGES = [
   'storage',
   'functions',
   'messaging',
+  'database',
 ] as const;
 
 export type MigratedTurboPackage = (typeof MIGRATED_TURBO_PACKAGES)[number];

packages/database/RNFBDatabase.podspec

@@ -28,15 +28,27 @@ Pod::Spec.new do |s|
   s.ios.deployment_target = firebase_ios_target
   s.macos.deployment_target = firebase_macos_target
   s.tvos.deployment_target = firebase_tvos_target
-  s.source_files        = 'ios/**/*.{h,m}'
+  s.source_files        = 'ios/**/*.{h,m,mm,cpp}'
+  s.private_header_files = [
+    'ios/RNFBDatabase/RNFBDatabaseModule.h',
+    'ios/RNFBDatabase/RNFBDatabaseReferenceModule.h',
+    'ios/RNFBDatabase/RNFBDatabaseQueryModule.h',
+    'ios/RNFBDatabase/RNFBDatabaseOnDisconnectModule.h',
+    'ios/RNFBDatabase/RNFBDatabaseTransactionModule.h',
+    'ios/generated/**/*.h',
+  ]
+  s.exclude_files       = 'ios/generated/RCTThirdPartyComponentsProvider.*', 'ios/generated/RCTAppDependencyProvider.*', 'ios/generated/RCTModuleProviders.*', 'ios/generated/RCTModulesConformingToProtocolsProvider.*', 'ios/generated/RCTUnstableModulesRequiringMainQueueSetupProvider.*'
+
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/ios/generated/RNFBDatabaseTurboModules\" \"$(PODS_TARGET_SRCROOT)/ios/generated\"",
+  }
 
   s.dependency          'RNFBApp'
 
-  # React Native dependencies
-  if defined?(install_modules_dependencies()) != nil
-    install_modules_dependencies(s);
-  else
-    s.dependency "React-Core"
+  install_modules_dependencies(s);
+
+  if defined?(ENV["RCT_NEW_ARCH_ENABLED"]) != nil && (ENV["RCT_NEW_ARCH_ENABLED"] == '0')
+     raise "#{s.name} requires New Architecture. Enable New Architecture to use this module"
   end
 
   if defined?($FirebaseSDKVersion)