docs: update readme

damlayildiz · damlayildiz · commit 5bd6cd22feb4 · 2026-01-27T20:47:56.000+01:00
diff --git a/README.md b/README.md
@@ -19,29 +19,18 @@ Build real-time, collaborative mobile apps that work seamlessly offline and auto
   No manual setup required — just access the full [SQLite Sync API](https://github.com/sqliteai/sqlite-sync/blob/main/API.md) directly through the `writeDb` / `readDb` instances.
 
 - 📱 **Native-Only, Ultra-Fast**  
-  Under the hood, we use OP-SQLite — a low-level, JSI-enabled SQLite engine for React Native With OP-SQLite, database operations run at near-native speed on iOS and Android.
+  Under the hood, we use OP-SQLite — a low-level, JSI-enabled SQLite engine for React Native. With OP-SQLite, database operations run at near-native speed on iOS and Android.
 
 ## 📚 Table of Contents
 
 - [Requirements](#-requirements)
 - [Installation](#-installation)
 - [Quick Start](#-quick-start)
+- [Sync Behavior](#-sync-behavior)
 - [API Reference](#-api-reference)
   - [SQLiteSyncProvider](#sqlitesyncprovider)
   - [Contexts](#contexts)
-    - [SQLiteDbContext](#sqlitedbcontext)
-    - [SQLiteSyncStatusContext](#sqlitesyncstatuscontext)
-    - [SQLiteSyncActionsContext](#sqlitesyncactionscontext)
   - [Hooks](#hooks)
-    - [useSqliteDb](#usesqlitedb)
-    - [useSyncStatus](#usesyncstatus)
-    - [useSqliteSync](#usesqlitesync)
-    - [useTriggerSqliteSync](#usetriggersqlitesync)
-    - [useSqliteSyncQuery](#usesqlitesyncquery)
-    - [useOnTableUpdate](#useontableupdate)
-    - [useSqliteExecute](#usesqliteexecute)
-    - [useSqliteTransaction](#usesqlitetransaction)
-  - [Types](#types)
 - [Error Handling](#-error-handling)
 - [Debug Logging](#-debug-logging)
 - [Examples](#-examples)
@@ -251,11 +240,17 @@ Synchronization happens automatically in response to meaningful events:
 - **App resume from background** → immediate sync (debounced to 5s)
 - **Network reconnection** → immediate sync
 
-**Secondary Trigger (Polling Mode):**
+**Secondary Triggers:**
+
+_Polling Mode:_
 
 - **Periodic polling while foreground** → interval adapts based on activity
 - **No polling when backgrounded**
 
+_Push Mode (Expo only):_
+
+- **Push notification from SQLite Cloud** → immediate sync when changes detected on server
+
 ### Adaptive Polling Algorithm
 
 In polling mode, the sync interval intelligently adjusts based on activity:
@@ -306,17 +301,20 @@ Main provider component that enables sync functionality.
 
 #### Props
 
-| Prop               | Type                    | Required | Description                                        |
-| ------------------ | ----------------------- | -------- | -------------------------------------------------- |
-| `connectionString` | `string`                | ✅       | SQLite Cloud connection string                     |
-| `databaseName`     | `string`                | ✅       | Local database file name                           |
-| `tablesToBeSynced` | `TableConfig[]`         | ✅       | Array of tables to sync                            |
-| `syncMode`         | `'polling' \| 'push'`   | ❌       | Sync mode (default: `'polling'`)                   |
-| `adaptivePolling`  | `AdaptivePollingConfig` | ❌       | Adaptive polling configuration (polling mode only) |
-| `apiKey`           | `string`                | \*       | API key for authentication                         |
-| `accessToken`      | `string`                | \*       | Access token for RLS authentication                |
-| `debug`            | `boolean`               | ❌       | Enable debug logging (default: `false`)            |
-| `children`         | `ReactNode`             | ✅       | Child components                                   |
+| Prop                            | Type                        | Required | Description                                                |
+| ------------------------------- | --------------------------- | -------- | ---------------------------------------------------------- |
+| `connectionString`              | `string`                    | ✅       | SQLite Cloud connection string                             |
+| `databaseName`                  | `string`                    | ✅       | Local database file name                                   |
+| `tablesToBeSynced`              | `TableConfig[]`             | ✅       | Array of tables to sync                                    |
+| `apiKey`                        | `string`                    | \*       | API key for authentication                                 |
+| `accessToken`                   | `string`                    | \*       | Access token for RLS authentication                        |
+| `syncMode`                      | `'polling' \| 'push'`       | ❌       | Sync mode (default: `'polling'`)                           |
+| `adaptivePolling`               | `AdaptivePollingConfig`     | ❌       | Adaptive polling configuration (polling mode only)         |
+| `notificationListening`         | `'foreground' \| 'always'`  | ❌       | When to listen for push notifications (push mode only)     |
+| `onBeforePushPermissionRequest` | `() => Promise<boolean>`    | ❌       | Custom UI before system permission prompt (push mode only) |
+| `onDatabaseReady`               | `(db: DB) => Promise<void>` | ❌       | Callback after DB opens, before sync init (for migrations) |
+| `debug`                         | `boolean`                   | ❌       | Enable debug logging (default: `false`)                    |
+| `children`                      | `ReactNode`                 | ✅       | Child components                                           |
 
 \* Either `apiKey` or `accessToken` is required
 
@@ -364,6 +362,63 @@ Uses push notifications from SQLite Cloud:
 >
 ```
 
+#### Background Sync Callback (Push Mode)
+
+When using push mode with `notificationListening: 'always'`, you can register a callback that runs after background sync completes. This is useful for showing local notifications about new data:
+
+```typescript
+import { registerBackgroundSyncCallback } from '@sqliteai/sqlite-sync-react-native';
+import * as Notifications from 'expo-notifications';
+
+// Register at module level (outside components)
+registerBackgroundSyncCallback(async ({ changes, db }) => {
+  // Find new inserts in your table
+  const newItems = changes.filter(
+    (c) => c.table === 'tasks' && c.operation === 'INSERT'
+  );
+
+  if (newItems.length === 0) return;
+
+  // Query the synced data
+  const result = await db.execute(
+    `SELECT * FROM tasks WHERE rowid IN (${newItems.map((c) => c.rowId).join(',')})`
+  );
+
+  // Show a local notification
+  await Notifications.scheduleNotificationAsync({
+    content: {
+      title: `${newItems.length} new tasks synced`,
+      body: result.rows?.[0]?.title || 'New data available',
+    },
+    trigger: null,
+  });
+});
+```
+
+#### Database Migrations with `onDatabaseReady`
+
+Use `onDatabaseReady` to run migrations or other setup after the database opens but before sync initialization:
+
+```typescript
+<SQLiteSyncProvider
+  connectionString="..."
+  databaseName="myapp.db"
+  apiKey="..."
+  tablesToBeSynced={[...]}
+  onDatabaseReady={async (db) => {
+    // Check current schema version
+    const { rows } = await db.execute('PRAGMA user_version');
+    const version = rows?.[0]?.user_version ?? 0;
+
+    // Run migrations
+    if (version < 1) {
+      await db.execute('ALTER TABLE tasks ADD COLUMN priority INTEGER DEFAULT 0');
+      await db.execute('PRAGMA user_version = 1');
+    }
+  }}
+>
+```
+
 #### `AdaptivePollingConfig`
 
 Configuration for adaptive polling behavior (polling mode only).
@@ -1049,7 +1104,8 @@ Enable detailed logging during development:
 
 Check out the [examples](./examples) directory for complete working examples:
 
-- **[sync-demo](./examples/sync-demo)** - Basic sync demonstration with CRUD operations
+- **[sync-demo-expo](./examples/sync-demo-expo)** - Expo development build with sync demonstration using push notifications
+- **[sync-demo-bare](./examples/sync-demo-bare)** - Bare React Native project with sync demonstration using polling
 
 ## 🔗 Links
 
diff --git a/examples/sync-demo-bare/README.md b/examples/sync-demo-bare/README.md
@@ -36,12 +36,12 @@ Before running the example, you need to set up a SQLite Cloud database:
 4. **Enable OffSync for the table**
 
    - Navigate to **Databases > OffSync** page in the dashboard
-   - Select \`test_table\` to enable synchronization
+   - Select `test_table` to enable synchronization
    - Learn more about [OffSync configuration](https://docs.sqlitecloud.io/docs/offsync#configuring-offsync)
 
 5. **Get your credentials**
    - Navigate to your database's **Configuration** tab
-   - Copy your **Connection String** (format: \`sqlitecloud://your-host.sqlite.cloud:8860/your-database\`)
+   - Copy your **Connection String** (format: `sqlitecloud://your-host.sqlite.cloud:8860/your-database`)
    - Copy your **API Key**
 
 ### 2. Set Up React Native Environment
@@ -50,14 +50,14 @@ Follow the [React Native environment setup guide](https://reactnative.dev/docs/s
 
 ### 3. Configure Environment Variables
 
-1. **Create a \`.env\` file**
+1. **Create a `.env` file**
 
    ```bash
    cd examples/sync-demo-bare
    cp .env.example .env
    ```
 
-2. **Fill in your credentials** in the \`.env\` file:
+2. **Fill in your credentials** in the `.env` file:
 
    ```env
    SQLITE_CLOUD_CONNECTION_STRING=sqlitecloud://your-host.sqlite.cloud:8860/your-database
@@ -66,7 +66,7 @@ Follow the [React Native environment setup guide](https://reactnative.dev/docs/s
    TABLE_NAME=test_table
    ```
 
-   **Note**: The \`TABLE_NAME\` must match the table name you created in SQLite Cloud and enabled for OffSync.
+   **Note**: The `TABLE_NAME` must match the table name you created in SQLite Cloud and enabled for OffSync.
 
 ### 4. Install Dependencies
 
@@ -75,64 +75,24 @@ Follow the [React Native environment setup guide](https://reactnative.dev/docs/s
 yarn install
 ```
 
-This will install dependencies for both the library and the example.
-
-### 5. Install iOS Pods (iOS only)
-
-```bash
-# From repository root
-cd examples/sync-demo-bare/ios
-pod install
-cd ../../..
-```
-
 ## Running the Example
 
-You can run the example from either the **repository root** or the **example directory**.
-
-### Option 1: Run from Root (Recommended)
-
-This automatically builds the library and runs the example:
+From the repository root:
 
 ```bash
-# From repository root
 yarn bare:ios      # Build library + run iOS
 yarn bare:android  # Build library + run Android
 ```
 
-### Option 2: Run from Example Directory
-
-If you prefer to run commands from the example directory:
-
-```bash
-# From repository root
-cd examples/sync-demo-bare
-
-# iOS
-yarn ios
-
-# Android
-yarn android
-```
-
-## Differences from Expo Version
-
-This bare React Native example:
-
-- Uses React Native CLI instead of Expo
-- Has direct access to native iOS and Android folders
-- Requires manual CocoaPods installation for iOS
-- Provides a more traditional React Native development experience
-- Ensures the library works correctly without Expo dependencies
-
 ## How It Works
 
-The demo app:
+The demo app demonstrates:
 
-1. Creates a local SQLite database that syncs with the cloud
-2. Allows you to add text entries that are automatically synced
-3. Displays sync status and last sync time
-4. Auto-reloads data when changes are received
+1. **SQLiteSyncProvider** - Creates a local SQLite database that syncs with the cloud
+2. **Adaptive polling sync** - Automatically syncs at intelligent intervals
+3. **Reactive queries** - Uses `useSqliteSyncQuery` for automatic UI updates
+4. **Row-level notifications** - Uses `useOnTableUpdate` for change tracking
+5. **Manual sync** - Uses `useTriggerSqliteSync` for on-demand sync
 
 ## Try It Out
 
@@ -143,7 +103,7 @@ The demo app:
 - Turn off your internet connection
 - Add entries in the app (they'll be saved locally)
 - Turn your internet back on
-- Watch the sync automatically happen and changes appear in the cloud!
+- Watch the sync automatically happen
 
 ## Learn More
 
diff --git a/examples/sync-demo-expo/README.md b/examples/sync-demo-expo/README.md
@@ -1,6 +1,6 @@
-# SQLite Sync React Native - Sync Demo
+# SQLite Sync React Native - Expo Demo
 
-This is an example Expo app demonstrating the usage of `@sqliteai/sqlite-sync-react-native`.
+This is an example **Expo** app demonstrating the usage of `@sqliteai/sqlite-sync-react-native` with push notification sync mode.
 
 ## Setup Instructions
 
@@ -51,7 +51,7 @@ Follow the [React Native environment setup guide](https://reactnative.dev/docs/s
 1. **Create a `.env` file**
 
    ```bash
-   cd examples/sync-demo
+   cd examples/sync-demo-expo
    cp .env.example .env
    ```
 
@@ -73,61 +73,38 @@ Follow the [React Native environment setup guide](https://reactnative.dev/docs/s
 yarn install
 ```
 
-This will install dependencies for both the library and the example.
-
 ## Running the Example
 
-You can run the example from either the **repository root** or the **example directory**.
-
-### Option 1: Run from Root (Recommended)
-
-This automatically builds the library and runs the example:
+From the repository root:
 
 ```bash
-# From repository root
-yarn ios      # Build library + run iOS
-yarn android  # Build library + run Android
+yarn expo:ios:device      # Build library + run iOS
+yarn expo:android:device  # Build library + run Android
 ```
 
-### Option 2: Run from Example Directory
-
-If you prefer to run commands from the example directory:
-
-```bash
-# From repository root
-cd examples/sync-demo
-
-# iOS
-yarn ios
-
-# Android
-yarn android
-```
-
-These commands will:
-1. Run `expo prebuild --clean` to generate native folders
-2. For iOS: install CocoaPods dependencies
-3. Build and launch the app
-
 ## How It Works
 
-The demo app:
+The demo app demonstrates:
 
-1. Creates a local SQLite database that syncs with the cloud
-2. Allows you to add text entries that are automatically synced
-3. Displays sync status and last sync time
-4. Auto-reloads data when changes are received
+1. **SQLiteSyncProvider** - Creates a local SQLite database that syncs with the cloud
+2. **Push notification sync** - Uses `expo-notifications` for real-time sync triggers
+3. **Reactive queries** - Uses `useSqliteSyncQuery` for automatic UI updates
+4. **Row-level notifications** - Uses `useOnTableUpdate` for change tracking
+5. **Manual sync** - Uses `useTriggerSqliteSync` for on-demand sync
+6. **Background sync callback** - Uses `registerBackgroundSyncCallback` for background notifications
 
 ## Try It Out
 
-**Test Real-Time Sync:**
-- Open the app on multiple devices or alongside the SQLite Cloud dashboard to see real-time synchronization in action!
+**Test Push Notification Sync:**
+1. Run the app on a real device (push notifications don't work on simulators)
+2. Grant push notification permissions when prompted
+3. Add data from the SQLite Cloud dashboard
+4. Watch the app sync instantly via push notification
 
-**Test Offline Mode:**
-- Turn off your internet connection
-- Add entries in the app (they'll be saved locally)
-- Turn your internet back on
-- Watch the sync automatically happen and changes appear in the cloud!
+**Test Permission Denial Fallback:**
+1. Deny push notification permissions when prompted
+2. The app automatically falls back to polling mode
+3. Data still syncs, just on a polling interval instead of instantly
 
 ## Learn More
 
