refactor(database): return sync parity for connection controls

Author: mikehardy

docs/migrating-to-v26.mdx

@@ -85,7 +85,7 @@ When migrating from firebase-js-sdk web examples, watch for these high-impact ru
 | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Auth**                      | Browser persistence, redirects, reCAPTCHA, `revokeAccessToken`, `useDeviceLanguage`, `linkWithPhoneNumber` / `reauthenticateWithPhoneNumber` | Native iOS/Android SDKs manage persistence. Several web-only helpers **throw synchronously** on React Native (`setPersistence`, `getRedirectResult`, `revokeAccessToken`, `useDeviceLanguage`, `linkWithPhoneNumber`, `reauthenticateWithPhoneNumber`). Use native provider flows instead. |
 | **Analytics**                 | Cross-platform modular API                                                                                                                   | On-device conversion measurement helpers (`initiateOnDeviceConversionMeasurement*`) are **iOS only**; on Android and web the JS layer resolves without calling native (no-op). `logTransaction` (verified iOS in-app purchase events) is **iOS only** and **rejects** on other platforms.  |
-| **Realtime Database**         | `goOnline` / `goOffline` are synchronous; web transport toggles                                                                              | RN helpers are **async** (native bridge). `getServerTime`, `setPersistenceEnabled`, and `setPersistenceCacheSizeBytes` are RN-specific. `forceLongPolling` / `forceWebSockets` **throw** — transport is native-controlled.                                                                 |
+| **Realtime Database**         | `goOnline` / `goOffline` are synchronous; web transport toggles                                                                              | `goOnline` / `goOffline` are **synchronous** through TurboModules, matching firebase-js-sdk. `getServerTime`, `setPersistenceEnabled`, and `setPersistenceCacheSizeBytes` are RN-specific. `forceLongPolling` / `forceWebSockets` **throw** — transport is native-controlled.                                                                 |
 | **Phone Number Verification** | N/A (Android SDK only)                                                                                                                       | **Android only** — all entry points throw on iOS and Web.                                                                                                                                                                                                                                  |
 | **Cloud Storage**             | `uploadBytes` / `uploadString` from JS blobs                                                                                                 | `putFile` and `writeToFile` are **native-only** file-path APIs with no firebase-js-sdk equivalent. Retry-time setters are modular functions on RN, not instance properties.                                                                                                                |
 | **Cloud Messaging**           | Web push / service-worker surface                                                                                                            | FCM token lifecycle, permissions, background handlers, and **APNs token APIs are iOS only**. Event delivery still uses the legacy native event proxy during the TurboModule migration; behavior matches pre-v26 releases but will change when Codegen events land in a future release.     |
@@ -534,6 +534,10 @@ The namespaced API for `@react-native-firebase/database` has been **removed**. T
 | `database().ref()`          | `ref(database, path?)`                                         |
 | `database().refFromURL()`   | `refFromURL(database, url)`                                    |
 
+## Signature changes
+
+- `goOnline(db)` and `goOffline(db)` (and the database instance methods) now return `void` synchronously (previously `Promise<void>`), matching firebase-js-sdk. Remove any `await` on these calls.
+
 # Cloud Storage
 
 The namespaced API for `@react-native-firebase/storage` has been **removed**. This package is **modular-only** — use `getStorage()` and root-level helper functions.

jest.setup.ts

@@ -341,8 +341,8 @@ jest.doMock('react-native', () => {
           ),
         },
         NativeRNFBTurboDatabase: {
-          goOnline: jest.fn(() => Promise.resolve()),
-          goOffline: jest.fn(() => Promise.resolve()),
+          goOnline: jest.fn(),
+          goOffline: jest.fn(),
           setPersistenceEnabled: jest.fn(),
           setLoggingEnabled: jest.fn(),
           setPersistenceCacheSizeBytes: jest.fn(),

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

@@ -231,7 +231,7 @@ The "keep async if it does network/IO/disk" rule in the discriminator **assumes*
 | `needs-native-change` | `analytics` fire-and-forget setters/events; `app-check/initializeAppCheck`; `firestore/initializeFirestore`; `storage` task controls; storage retry setters | Web APIs are sync or fire-and-forget, but RNFB native paths currently wrap async work or need behavior clarification before sync conversion. |
 | `keep-async` | Firestore persistent cache index manager delete/enable/disable | Web returns `void` but starts real persistent-cache work; do not block JS thread. |
 
-**Next slice:** `app/registerVersion` because RNFB already behaves synchronously and Phase S should only change the public type/compare-types entry. Planned subject: `refactor(app): return sync parity for registerVersion`.
+**Next slice:** `convert` inventory complete (2026-07-03). Remaining gap-analysis verdicts (`needs-native-change`, `keep-async`) are out of Phase S scope until native behavior is clarified or documented only.
 
 ---
 
@@ -332,9 +332,9 @@ Skip steps 1–2 when spec shape is known (most Tier D packages).
 
 **Label:** `phase-s-sync-conversion` (2026-07-03)
 
-**Next item:** Phase **S** database sync controls (`PS-database-online` — after perf commit)
+**Next item:** Phase **S** `convert` inventory **complete** — deferred `needs-native-change` / `keep-async` items documented in gap-analysis table
 
-**Current gates:** PS-perf-metrics all gates **closed** — committing `refactor(perf): return sync parity for metric controls`.
+**Current gates:** PS-database-online all gates **closed** — committing `refactor(database): return sync parity for connection controls`.
 
 **Host rule:** one `:test-cover` at a time — never parallel subagents with e2e.
 
@@ -375,6 +375,7 @@ Skip steps 1–2 when spec shape is known (most Tier D packages).
 | Phase S `app/registerVersion` sync parity | PS-app-registerVersion | **closed** | **closed** | **closed** | done | `area-focused` | `refactor(app): return sync parity for registerVersion` | Implemented 2026-07-03: `registerVersion(): void`, sync throw Jest assertion, removed stale `configs/app.ts` async-vs-sync entry. Green: `lerna:prepare`, `tsc:compile`, `tsc:compile:consumer`, focused app Jest 10/10, `reference:api`, `compare:types`, `lint:js`. Independent review: no findings; no e2e needed for type-only scope. |
 | Phase S auth parser/TOTP sync parity | PS-auth-parsers | **closed** | **closed** | **closed** | done | `area-focused` | `refactor(auth): return sync parity for auth parsers` | Committed 2026-07-03. Sync `isSignInWithEmailLink` + `TotpSecret.generateQrCodeUrl`; native sync error shape; jest.setup; tests + e2e sync calls; compare-types + v26 doc. Validation: Jest 91/91, compare:types, lint, reference:api, codegen:verify exit 0. Android area e2e 159/15/0 (`/tmp/rnfb-e2e-android-auth-phaseS-final.log`). |
 | Phase S perf metric controls sync parity | PS-perf-metrics | **closed** | **closed** | **closed** | done | `area-focused` | `refactor(perf): return sync parity for metric controls` | Sync trace/http/screen start/stop; Android *Sync helpers; iOS sync shells. Jest 10/10; compare:types, lint, reference:api green. Review e2e iOS/Android 60/2/0 (`/tmp/rnfb-e2e-*-perf-review.log`). macOS N/A (module skip). Remediation: perf usage docs await removed. |
+| Phase S database connection sync parity | PS-database-online | **closed** | **closed** | **closed** | done | `area-focused` | `refactor(database): return sync parity for connection controls` | Sync turbo + instance goOnline/goOffline; Android direct SDK calls; e2e await removed on modular calls. Jest 52/52; codegen:verify exit 0. Review e2e macOS 181/10/0, iOS 182/9/0, Android 183/8/0 (`/tmp/rnfb-e2e-*-database-review.log`). |
 
 ---
 

packages/database/__tests__/database.test.ts

@@ -229,4 +229,33 @@ describe('Database', function () {
       expect(update).toBeDefined();
     });
   });
+
+  describe('synchronous connection control parity', function () {
+    it('`goOnline()` and `goOffline()` return synchronously (not Promises)', function () {
+      const db = getDatabase();
+
+      const onlineResult = goOnline(db);
+      expect(onlineResult).toBeUndefined();
+      expect(onlineResult).not.toBeInstanceOf(Promise);
+
+      const offlineResult = goOffline(db);
+      expect(offlineResult).toBeUndefined();
+      expect(offlineResult).not.toBeInstanceOf(Promise);
+    });
+
+    it('database instance `goOnline()` / `goOffline()` return synchronously (not Promises)', function () {
+      const db = getDatabase() as ReturnType<typeof getDatabase> & {
+        goOnline(): void;
+        goOffline(): void;
+      };
+
+      const onlineResult = db.goOnline();
+      expect(onlineResult).toBeUndefined();
+      expect(onlineResult).not.toBeInstanceOf(Promise);
+
+      const offlineResult = db.goOffline();
+      expect(offlineResult).toBeUndefined();
+      expect(offlineResult).not.toBeInstanceOf(Promise);
+    });
+  });
 });

packages/database/__tests__/nativeModuleContract.test.ts

@@ -165,4 +165,35 @@ describe('TurboModule wrapper contract (NewArch-AD-17.1)', function () {
 
     expect(Object.keys(wrapped).sort()).toEqual([...ALL_SPEC_METHODS].sort());
   });
+  it('returns synchronously from goOnline and goOffline on the main host (Phase S)', function () {
+    const goOnlineMock = jest.fn();
+    const goOfflineMock = jest.fn();
+
+    jest
+      .mocked(TurboModuleRegistry.get)
+      .mockReturnValueOnce(
+        createTurboModuleFixture({ goOnline: goOnlineMock, goOffline: goOfflineMock }),
+      )
+      .mockReturnValueOnce(createTurboModuleFixture({}))
+      .mockReturnValueOnce(createTurboModuleFixture({}))
+      .mockReturnValueOnce(createTurboModuleFixture({}))
+      .mockReturnValueOnce(createTurboModuleFixture({}));
+
+    const wrapped = getNativeModule(
+      createMergeModule('databaseSyncConnection'),
+    ) as WrappedNativeModule & {
+      goOnline: () => unknown;
+      goOffline: () => unknown;
+    };
+
+    const onlineResult = wrapped.goOnline();
+    expect(onlineResult).toBeUndefined();
+    expect(onlineResult).not.toBeInstanceOf(Promise);
+    expect(goOnlineMock).toHaveBeenCalledTimes(1);
+
+    const offlineResult = wrapped.goOffline();
+    expect(offlineResult).toBeUndefined();
+    expect(offlineResult).not.toBeInstanceOf(Promise);
+    expect(goOfflineMock).toHaveBeenCalledTimes(1);
+  });
 });

packages/database/android/src/main/java/io/invertase/firebase/database/UniversalFirebaseDatabaseModule.java

@@ -20,8 +20,6 @@
 import static io.invertase.firebase.database.UniversalFirebaseDatabaseCommon.getDatabaseForApp;
 
 import android.content.Context;
-import com.google.android.gms.tasks.Task;
-import com.google.android.gms.tasks.Tasks;
 import io.invertase.firebase.common.UniversalFirebaseModule;
 
 public class UniversalFirebaseDatabaseModule extends UniversalFirebaseModule {
@@ -30,19 +28,11 @@ public class UniversalFirebaseDatabaseModule extends UniversalFirebaseModule {
     super(context, serviceName);
   }
 
-  Task<Void> goOnline(String appName, String dbURL) {
-    return Tasks.call(
-        () -> {
-          getDatabaseForApp(appName, dbURL).goOnline();
-          return null;
-        });
+  void goOnline(String appName, String dbURL) {
+    getDatabaseForApp(appName, dbURL).goOnline();
   }
 
-  Task<Void> goOffline(String appName, String dbURL) {
-    return Tasks.call(
-        () -> {
-          getDatabaseForApp(appName, dbURL).goOffline();
-          return null;
-        });
+  void goOffline(String appName, String dbURL) {
+    getDatabaseForApp(appName, dbURL).goOffline();
   }
 }

packages/database/android/src/reactnative/java/io/invertase/firebase/database/NativeRNFBTurboDatabase.java

@@ -20,9 +20,7 @@
 import static io.invertase.firebase.database.UniversalFirebaseDatabaseCommon.addEmulatorConfig;
 
 import com.facebook.fbreact.specs.NativeRNFBTurboDatabaseSpec;
-import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
-import io.invertase.firebase.common.ReactNativeFirebaseModule;
 import io.invertase.firebase.common.UniversalFirebasePreferences;
 
 public class NativeRNFBTurboDatabase extends NativeRNFBTurboDatabaseSpec {
@@ -35,33 +33,13 @@ public NativeRNFBTurboDatabase(ReactApplicationContext reactContext) {
   }
 
   @Override
-  public void goOnline(String app, String dbURL, Promise promise) {
-    module
-        .goOnline(app, dbURL)
-        .addOnCompleteListener(
-            task -> {
-              if (task.isSuccessful()) {
-                promise.resolve(task.getResult());
-              } else {
-                ReactNativeFirebaseModule.rejectPromiseWithExceptionMap(
-                    promise, task.getException());
-              }
-            });
+  public void goOnline(String app, String dbURL) {
+    module.goOnline(app, dbURL);
   }
 
   @Override
-  public void goOffline(String app, String dbURL, Promise promise) {
-    module
-        .goOffline(app, dbURL)
-        .addOnCompleteListener(
-            task -> {
-              if (task.isSuccessful()) {
-                promise.resolve(task.getResult());
-              } else {
-                ReactNativeFirebaseModule.rejectPromiseWithExceptionMap(
-                    promise, task.getException());
-              }
-            });
+  public void goOffline(String app, String dbURL) {
+    module.goOffline(app, dbURL);
   }
 
   @Override

packages/database/android/src/reactnative/java/io/invertase/firebase/database/generated/java/com/facebook/fbreact/specs/NativeRNFBTurboDatabaseSpec.java

@@ -13,7 +13,6 @@
 package com.facebook.fbreact.specs;
 
 import com.facebook.proguard.annotations.DoNotStrip;
-import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
 import com.facebook.react.bridge.ReactContextBaseJavaModule;
 import com.facebook.react.bridge.ReactMethod;
@@ -34,11 +33,11 @@ public NativeRNFBTurboDatabaseSpec(ReactApplicationContext reactContext) {
 
   @ReactMethod
   @DoNotStrip
-  public abstract void goOnline(String app, String dbURL, Promise promise);
+  public abstract void goOnline(String app, String dbURL);
 
   @ReactMethod
   @DoNotStrip
-  public abstract void goOffline(String app, String dbURL, Promise promise);
+  public abstract void goOffline(String app, String dbURL);
 
   @ReactMethod
   @DoNotStrip

packages/database/android/src/reactnative/java/io/invertase/firebase/database/generated/jni/RNFBDatabaseTurboModules-generated.cpp

@@ -14,12 +14,12 @@ namespace facebook::react {
 
 static facebook::jsi::Value __hostFunction_NativeRNFBTurboDatabaseSpecJSI_goOnline(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
   static jmethodID cachedMethodId = nullptr;
-  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, PromiseKind, "goOnline", "(Ljava/lang/String;Ljava/lang/String;Lcom/facebook/react/bridge/Promise;)V", args, count, cachedMethodId);
+  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, VoidKind, "goOnline", "(Ljava/lang/String;Ljava/lang/String;)V", args, count, cachedMethodId);
 }
 
 static facebook::jsi::Value __hostFunction_NativeRNFBTurboDatabaseSpecJSI_goOffline(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
   static jmethodID cachedMethodId = nullptr;
-  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, PromiseKind, "goOffline", "(Ljava/lang/String;Ljava/lang/String;Lcom/facebook/react/bridge/Promise;)V", args, count, cachedMethodId);
+  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, VoidKind, "goOffline", "(Ljava/lang/String;Ljava/lang/String;)V", args, count, cachedMethodId);
 }
 
 static facebook::jsi::Value __hostFunction_NativeRNFBTurboDatabaseSpecJSI_setPersistenceEnabled(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {

packages/database/android/src/reactnative/java/io/invertase/firebase/database/generated/jni/react/renderer/components/RNFBDatabaseTurboModules/RNFBDatabaseTurboModulesJSI-generated.cpp

@@ -12,18 +12,20 @@
 namespace facebook::react {
 
 static jsi::Value __hostFunction_NativeRNFBTurboDatabaseCxxSpecJSI_goOnline(jsi::Runtime &rt, TurboModule &turboModule, const jsi::Value* args, size_t count) {
-  return static_cast<NativeRNFBTurboDatabaseCxxSpecJSI *>(&turboModule)->goOnline(
+  static_cast<NativeRNFBTurboDatabaseCxxSpecJSI *>(&turboModule)->goOnline(
     rt,
     count <= 0 ? throw jsi::JSError(rt, "Expected argument in position 0 to be passed") : args[0].asString(rt),
     count <= 1 ? throw jsi::JSError(rt, "Expected argument in position 1 to be passed") : args[1].asString(rt)
   );
+  return jsi::Value::undefined();
 }
 static jsi::Value __hostFunction_NativeRNFBTurboDatabaseCxxSpecJSI_goOffline(jsi::Runtime &rt, TurboModule &turboModule, const jsi::Value* args, size_t count) {
-  return static_cast<NativeRNFBTurboDatabaseCxxSpecJSI *>(&turboModule)->goOffline(
+  static_cast<NativeRNFBTurboDatabaseCxxSpecJSI *>(&turboModule)->goOffline(
     rt,
     count <= 0 ? throw jsi::JSError(rt, "Expected argument in position 0 to be passed") : args[0].asString(rt),
     count <= 1 ? throw jsi::JSError(rt, "Expected argument in position 1 to be passed") : args[1].asString(rt)
   );
+  return jsi::Value::undefined();
 }
 static jsi::Value __hostFunction_NativeRNFBTurboDatabaseCxxSpecJSI_setPersistenceEnabled(jsi::Runtime &rt, TurboModule &turboModule, const jsi::Value* args, size_t count) {
   static_cast<NativeRNFBTurboDatabaseCxxSpecJSI *>(&turboModule)->setPersistenceEnabled(