fix: reuse existing DB connection for background-alive push notification sync

Author: damlayildiz

.claude/plans/background-alive-sync.md

@@ -0,0 +1,205 @@
+# Plan: Background-Alive Sync Path
+
+**Date:** 2026-04-02  
+**Status:** Implemented
+
+---
+
+## Problem Statement
+
+When a push notification arrives while the app is **backgrounded but not terminated**, the current code falls through to `executeBackgroundSync()` and opens a second write connection even though the provider is still mounted with an existing open connection. This creates concurrent writers and relies on SQLite locking rather than single-connection ownership.
+
+---
+
+## Three-State Model
+
+| App State | Connection | Behavior |
+|-----------|-----------|----------|
+| `active` | reuse existing | `performSync()` via `foregroundSyncCallback` |
+| backgrounded + alive | reuse existing | `performSync()` via `foregroundSyncCallback` — same callback |
+| terminated | open new | `executeBackgroundSync` → `registerBackgroundSyncCallback` |
+
+Both the active and backgrounded-alive cases call the same `foregroundSyncCallback` (`() => performSyncRef.current?.() ?? Promise.resolve()`). This is correct because `performSync` already has all necessary guards built in (`isSyncingRef`, `writeDbRef`, `isSyncReady`, Android network check). React state updates (`isSyncing`, `lastSyncTime`, etc.) queued while backgrounded apply harmlessly on next render when the user returns.
+
+The distinction between active and backgrounded-alive is only relevant at the **notification layer** in the example app (see Phase 3).
+
+---
+
+## Why Not a Separate `backgroundAliveSyncCallback`
+
+The callback would be identical to `foregroundSyncCallback`. Two module-level variables holding the same function serves no purpose. `performSync` already guards against all the failure modes that would require a different implementation.
+
+---
+
+## Will `useOnTableUpdate` Fire When Backgrounded?
+
+OP-SQLite's `updateHook` is a SQLite C callback that fires synchronously on the thread executing the write. When the app is backgrounded but alive, the JS runtime thread is still active and running the background task. The hook dispatch should work.
+
+**Caveat:** Depends on whether OP-SQLite dispatches the hook synchronously on the current thread or schedules it. If scheduled, delivery may be delayed until foregrounding. Behavior is correct either way — timing may vary.
+
+**Verification:** manually confirm `useOnTableUpdate` fires during a background-alive sync in testing.
+
+---
+
+## Signal: How to Detect "Provider Is Mounted"
+
+`foregroundSyncCallback` is set by `usePushNotificationSync` inside a React hook. React hooks only run when the component tree is mounted. In a terminated → background launch there is no component tree, so the callback is never set.
+
+Therefore: **`getForegroundSyncCallback() !== null` is a reliable proxy for "provider is mounted, `writeDbRef.current` is valid."**
+
+---
+
+## Implementation Plan
+
+### Phase 1 — Update `pushNotificationSyncTask.ts` (one-line change)
+
+Remove the `AppState.currentState === 'active'` guard. The callback's existence is sufficient — it implies the provider is mounted and the connection is live.
+
+```typescript
+// Before:
+if (AppState.currentState === 'active' && foregroundCallback) {
+
+// After:
+if (foregroundCallback) {
+```
+
+Full updated task:
+
+```typescript
+const foregroundCallback = getForegroundSyncCallback();
+
+/** FOREGROUND / BACKGROUND-ALIVE MODE */
+// foregroundCallback being non-null means the provider is mounted
+// (React hooks only run when the component tree is alive).
+// Safe for both active and backgrounded states — performSync guards internally.
+if (foregroundCallback) {
+  logger.info('📲 Provider is mounted, using existing sync');
+  try {
+    await foregroundCallback();
+    logger.info('✅ Sync completed');
+  } catch (syncError) {
+    logger.error('❌ Sync failed:', syncError);
+  }
+  return;
+}
+
+/** TERMINATED / NO PROVIDER MODE */
+if (!config) {
+  logger.info('📲 No config found, skipping background sync');
+  return;
+}
+
+await executeBackgroundSync(config);
+```
+
+The `AppState` import can be removed from this file if it is no longer used elsewhere.
+
+---
+
+### Phase 2 — Tests
+
+**Update:** `src/core/pushNotifications/__tests__/pushNotificationSyncTask.test.ts`
+
+New cases to add:
+- When `foregroundCallback` is set and `AppState === 'background'`: callback is called, `executeBackgroundSync` is NOT called
+- When `foregroundCallback` is set and `AppState === 'inactive'`: callback is called, `executeBackgroundSync` is NOT called
+- When `foregroundCallback` is set and `AppState === 'active'`: callback is called (existing test, now also covers removal of the AppState guard)
+- When `foregroundCallback` is null and `AppState === 'background'`: `executeBackgroundSync` is called (terminated path)
+
+---
+
+### Phase 3 — Update Expo Example App
+
+`registerBackgroundSyncCallback` handles the **terminated** case — no component tree, so the app must schedule a push notification to alert the user. This stays as-is.
+
+The **background-alive** case now goes through `performSync`, which means `useOnTableUpdate` hooks fire. The example should demonstrate sending a notification from `useOnTableUpdate` when the app is backgrounded — this is how users handle the background-alive notification scenario.
+
+**Update `examples/sync-demo-expo/src/App.tsx`:**
+
+Add `AppState` import from `react-native`. Update the existing `useOnTableUpdate` callback to schedule a notification when the app is not active and the operation is an INSERT:
+
+```typescript
+import { ..., AppState } from 'react-native';
+
+useOnTableUpdate<{ id: string; value: string; created_at: string }>({
+  tables: [TABLE_NAME],
+  onUpdate: async (data) => {
+    /** BACKGROUND-ALIVE NOTIFICATION */
+    // When app is backgrounded but alive, useOnTableUpdate fires normally.
+    // Schedule a local notification so the user is alerted, same as the
+    // terminated path handled by registerBackgroundSyncCallback.
+    if (AppState.currentState !== 'active' && data.operation === 'INSERT' && data.row) {
+      await Notifications.scheduleNotificationAsync({
+        content: {
+          title: 'New item synced',
+          body: data.row.value || 'New data is available',
+          data: { rowId: data.row.id },
+        },
+        trigger: null,
+      });
+      return;
+    }
+
+    /** FOREGROUND UI UPDATE */
+    const operationName =
+      data.operation === 'INSERT'
+        ? 'added'
+        : data.operation === 'UPDATE'
+        ? 'updated'
+        : 'deleted';
+
+    if (data.row) {
+      setRowNotification(
+        `🔔 Row ${operationName}: "${data.row.value.substring(0, 20)}${
+          data.row.value.length > 20 ? '...' : ''
+        }"`
+      );
+    } else {
+      setRowNotification(`🔔 Row ${operationName}`);
+    }
+    setTimeout(() => setRowNotification(null), 2000);
+  },
+});
+```
+
+The callback needs to be `async` — add that. Also update the JSDoc comment above the `registerBackgroundSyncCallback` block and the `useOnTableUpdate` comment to explain the two-path split:
+
+- `registerBackgroundSyncCallback` → terminated case
+- `useOnTableUpdate` with AppState check → background-alive case
+
+---
+
+## File Impact
+
+| File | Change | Risk |
+|------|--------|------|
+| `src/core/pushNotifications/pushNotificationSyncTask.ts` | Remove `AppState.currentState === 'active' &&` guard; remove `AppState` import if unused | Very Low |
+| `src/core/pushNotifications/__tests__/pushNotificationSyncTask.test.ts` | Add background/inactive AppState test cases | None |
+| `examples/sync-demo-expo/src/App.tsx` | Add AppState check + notification in `useOnTableUpdate`; make callback async | Low |
+
+No new files. No new module-level variables. No changes to `useSyncManager`, `usePushNotificationSync`, or `pushNotificationSyncCallbacks`.
+
+---
+
+## Failure Scenarios Covered
+
+| Scenario | Handled by |
+|----------|-----------|
+| Notification while app active | `foregroundCallback` → `performSync` (unchanged) |
+| Notification while app backgrounded, provider mounted | `foregroundCallback` → `performSync`; `useOnTableUpdate` fires → notification sent |
+| Notification while app terminated | `executeBackgroundSync` → `registerBackgroundSyncCallback` (unchanged) |
+| Concurrent sync (foreground + background-alive race) | `isSyncingRef` guard inside `performSync` |
+| Provider unmounted before callback fires | `foregroundCallback` is null → falls through to `executeBackgroundSync` |
+
+---
+
+## Verification Criteria
+
+- [ ] `AppState === 'background'`: `foregroundCallback` is called, `executeBackgroundSync` is NOT called
+- [ ] `AppState === 'inactive'`: same as above
+- [ ] `AppState === 'active'`: same behavior as before (existing tests still pass)
+- [ ] `foregroundCallback` null + any AppState: `executeBackgroundSync` is called
+- [ ] `useOnTableUpdate` fires during a background-alive sync (manual test)
+- [ ] Example app: notification is sent when `useOnTableUpdate` fires while app is backgrounded
+- [ ] Example app: UI notification still shows when app is active
+- [ ] All existing tests pass

.claude/plans/test-suite.md

@@ -61,7 +61,7 @@ Test utilities in `src/testUtils.tsx` provide `createTestWrapper` for provider-w
 | `core/pushNotifications/__tests__/isSqliteCloudNotification.test.ts` | isSqliteCloudNotification | 13 | Foreground valid/invalid URI, iOS background body, Android JSON string body, Android dataString fallback, invalid JSON, wrong URI, empty data |
 | `core/common/__tests__/logger.test.ts` | logger | 9 | debug=true logs info/warn, debug=false suppresses, error always logs, [SQLiteSync] prefix, ISO timestamp, default debug=false |
 | `core/pushNotifications/__tests__/pushNotificationSyncCallbacks.test.ts` | pushNotificationSyncCallbacks | 5 | Register/get background callback, null default, set/get/clear foreground callback |
-| `core/__tests__/constants.test.ts` | constants | 2 | FOREGROUND_DEBOUNCE_MS value, BACKGROUND_SYNC_TASK_NAME non-empty |
+| `core/__tests__/constants.test.ts` | constants | 2 | FOREGROUND_DEBOUNCE_MS value, PUSH_NOTIFICATION_SYNC_TASK_NAME non-empty |
 
 ### Layer 2: Core Logic (97 tests)
 

README.md

@@ -338,11 +338,11 @@ npx expo install expo-notifications expo-constants expo-application expo-secure-
 
 ### `notificationListening` Modes
 
-| App State  | `notificationListening="foreground"`                     | `notificationListening="always"`                                                                                       |
-| ---------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Foreground | Notification triggers sync on the existing DB connection | Same behavior                                                                                                          |
-| Background | Notification ignored                                     | Background task opens a DB connection, syncs, then calls `registerBackgroundSyncCallback` if registered                |
-| Terminated | Notification ignored                                     | Background task wakes the app, opens a DB connection, syncs, then calls `registerBackgroundSyncCallback` if registered |
+| App State             | `notificationListening="foreground"`                     | `notificationListening="always"`                                                                                                                                    |
+| --------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Foreground            | Notification triggers sync on the existing DB connection | Same behavior                                                                                                                                                       |
+| Background (alive)    | Notification ignored                                     | Sync runs on the existing DB connection — no second connection opened. `useOnTableUpdate` hooks fire normally; `registerBackgroundSyncCallback` is **not** called   |
+| Terminated            | Notification ignored                                     | Background task wakes the app, opens a DB connection, syncs, then calls `registerBackgroundSyncCallback` if registered                                              |
 
 > Note: If push mode cannot be used because required Expo packages are missing, notification permissions are denied, or push token retrieval fails, the provider logs a warning and falls back to polling mode.
 
@@ -421,12 +421,15 @@ Main provider component that enables sync functionality.
 
 #### Background Sync Callback
 
-When using push mode with `notificationListening="always"`, you can register a callback that runs after a background sync completes.
+When using push mode with `notificationListening="always"`, notifications are handled differently depending on whether the app was terminated or just backgrounded.
+
+**Terminated app** — use `registerBackgroundSyncCallback` at module level (outside any component). This runs after the background sync completes with a list of changed rows and a DB handle for querying:
 
 ```typescript
 import { registerBackgroundSyncCallback } from '@sqliteai/sqlite-sync-react-native';
 import * as Notifications from 'expo-notifications';
 
+// Must be called at module level — this runs even when the app was terminated
 registerBackgroundSyncCallback(async ({ changes, db }) => {
   const newItems = changes.filter(
     (c) => c.table === 'tasks' && c.operation === 'INSERT'
@@ -450,6 +453,33 @@ registerBackgroundSyncCallback(async ({ changes, db }) => {
 });
 ```
 
+**Backgrounded but alive** — the sync runs on the existing DB connection. Your `useOnTableUpdate` hooks fire normally. Use an `AppState` check inside the hook to send a local notification instead of updating UI:
+
+```typescript
+import { AppState } from 'react-native';
+import { useOnTableUpdate } from '@sqliteai/sqlite-sync-react-native';
+import * as Notifications from 'expo-notifications';
+
+useOnTableUpdate({
+  tables: ['tasks'],
+  onUpdate: async (data) => {
+    if (AppState.currentState !== 'active' && data.operation === 'INSERT' && data.row) {
+      // App is backgrounded — notify the user instead of updating UI
+      await Notifications.scheduleNotificationAsync({
+        content: {
+          title: 'New task synced',
+          body: data.row.title || 'New data available',
+        },
+        trigger: null,
+      });
+      return;
+    }
+
+    // App is in foreground — update UI normally
+  },
+});
+```
+
 #### Database Migrations With `onDatabaseReady`
 
 Use `onDatabaseReady` to run migrations or setup after the database opens and before sync initialization.

examples/sync-demo-expo/src/App.tsx

@@ -10,6 +10,7 @@ import {
   FlatList,
   Modal,
   Clipboard,
+  AppState,
 } from 'react-native';
 import {
   SQLiteSyncProvider,
@@ -34,7 +35,8 @@ const TABLE_NAME = Constants.expoConfig?.extra?.tableName;
 
 /**
  * Register background sync handler at module level (outside components).
- * This is called when new data is synced while app is in background/terminated.
+ * This is called when new data is synced while the app is TERMINATED.
+ * For the backgrounded-but-alive case, useOnTableUpdate handles notifications instead.
  */
 registerBackgroundSyncCallback(
   async ({ changes, db }: BackgroundSyncResult) => {
@@ -142,10 +144,31 @@ function TestApp({ deviceToken }: { deviceToken: string | null }) {
   }, [allRows, searchText]);
 
   // Hook 2: useOnTableUpdate - Row-level update notifications
-  // Fires for individual row changes with automatic row data fetching
+  // Fires for individual row changes with automatic row data fetching.
+  // Also handles the backgrounded-but-alive notification case: when the app is
+  // in the background, the sync runs on the existing connection and this hook
+  // fires normally — we schedule a local notification here instead of updating UI.
   useOnTableUpdate<{ id: string; value: string; created_at: string }>({
     tables: [TABLE_NAME],
-    onUpdate: (data) => {
+    onUpdate: async (data) => {
+      /** BACKGROUND-ALIVE: schedule notification instead of updating UI */
+      if (
+        AppState.currentState !== 'active' &&
+        data.operation === 'INSERT' &&
+        data.row
+      ) {
+        await Notifications.scheduleNotificationAsync({
+          content: {
+            title: 'New item synced',
+            body: data.row.value || 'New data is available',
+            data: { rowId: data.row.id },
+          },
+          trigger: null,
+        });
+        return;
+      }
+
+      /** FOREGROUND: update in-app UI */
       const operationName =
         data.operation === 'INSERT'
           ? 'added'

src/core/__tests__/constants.test.ts

@@ -1,6 +1,6 @@
 import {
   FOREGROUND_DEBOUNCE_MS,
-  BACKGROUND_SYNC_TASK_NAME,
+  PUSH_NOTIFICATION_SYNC_TASK_NAME,
   CLOUDSYNC_BASE_URL,
 } from '../constants';
 
@@ -9,9 +9,9 @@ describe('constants', () => {
     expect(FOREGROUND_DEBOUNCE_MS).toBe(2000);
   });
 
-  it('BACKGROUND_SYNC_TASK_NAME is a non-empty string', () => {
-    expect(typeof BACKGROUND_SYNC_TASK_NAME).toBe('string');
-    expect(BACKGROUND_SYNC_TASK_NAME.length).toBeGreaterThan(0);
+  it('PUSH_NOTIFICATION_SYNC_TASK_NAME is a non-empty string', () => {
+    expect(typeof PUSH_NOTIFICATION_SYNC_TASK_NAME).toBe('string');
+    expect(PUSH_NOTIFICATION_SYNC_TASK_NAME.length).toBeGreaterThan(0);
   });
 
   it('CLOUDSYNC_BASE_URL is a non-empty string', () => {

src/core/background/__tests__/backgroundSyncRegistry.test.ts

@@ -22,7 +22,7 @@ import {
   isBackgroundSyncAvailable,
 } from '../../common/optionalDependencies';
 import { persistConfig, clearPersistedConfig } from '../backgroundSyncConfig';
-import { BACKGROUND_SYNC_TASK_NAME } from '../../constants';
+import { PUSH_NOTIFICATION_SYNC_TASK_NAME } from '../../constants';
 
 const mockConfig: BackgroundSyncConfig = {
   databaseId: 'db_test_database_id',
@@ -47,7 +47,7 @@ describe('registerBackgroundSync', () => {
     await registerBackgroundSync(mockConfig);
 
     expect(ExpoNotifications.registerTaskAsync).toHaveBeenCalledWith(
-      BACKGROUND_SYNC_TASK_NAME
+      PUSH_NOTIFICATION_SYNC_TASK_NAME
     );
   });
 
@@ -71,7 +71,7 @@ describe('unregisterBackgroundSync', () => {
     await unregisterBackgroundSync();
 
     expect(ExpoNotifications.unregisterTaskAsync).toHaveBeenCalledWith(
-      BACKGROUND_SYNC_TASK_NAME
+      PUSH_NOTIFICATION_SYNC_TASK_NAME
     );
   });