From a881c666e1225a6519d357db326a61948a6ef8f8 Mon Sep 17 00:00:00 2001
From: damlayildiz <damlayildiz19@ku.edu.tr>
Date: Wed, 17 Dec 2025 18:44:39 +0100
Subject: [PATCH 1/4] refactor: implement dual database connections

---
 README.md                                     | 293 +++++++++++++++---
 examples/sync-demo/src/App.tsx                |  17 +-
 src/SQLiteDbContext.tsx                       |   3 +-
 src/SQLiteSyncActionsContext.tsx              |   6 +-
 src/SQLiteSyncProvider.tsx                    |  99 ++++--
 src/hooks/useOnSqliteSync.ts                  |   6 +-
 src/hooks/useOnTableUpdate.ts                 |  17 +-
 src/hooks/useSqliteExecute.ts                 |   8 +-
 src/hooks/useSqliteSyncQuery.ts               |  11 +-
 ...seSyncStatus.ts => useSqliteSyncStatus.ts} |   4 +-
 src/hooks/useSqliteTransaction.ts             |  80 +++++
 src/index.tsx                                 |   3 +-
 src/types/SQLiteDbContextValue.ts             |  17 +-
 src/types/SQLiteSyncActionsContextValue.ts    |   2 +-
 14 files changed, 451 insertions(+), 115 deletions(-)
 rename src/hooks/{useSyncStatus.ts => useSqliteSyncStatus.ts} (87%)
 create mode 100644 src/hooks/useSqliteTransaction.ts

diff --git a/README.md b/README.md
index ea1dc0f..9f2ac21 100644
--- a/README.md
+++ b/README.md
@@ -34,12 +34,14 @@ Build real-time, collaborative mobile apps that work seamlessly offline and auto
     - [SQLiteSyncActionsContext](#sqlitesyncactionscontext)
   - [Hooks](#hooks)
     - [useSqliteDb](#usesqlitedb)
-    - [useSyncStatus](#usesyncstatus)
+    - [useSqliteSyncStatus](#useSqliteSyncStatus)
     - [useSqliteSync](#usesqlitesync)
     - [useTriggerSqliteSync](#usetriggersqlitesync)
     - [useOnSqliteSync](#useonsqlitesync)
     - [useSqliteSyncQuery](#usesqlitesyncquery)
     - [useOnTableUpdate](#useontableupdate)
+    - [useSqliteTransaction](#usesqlitetransaction)
+    - [useSqliteExecute](#usesqliteexecute)
   - [Types](#types)
 - [Error Handling](#-error-handling)
 - [Debug Logging](#-debug-logging)
@@ -157,6 +159,7 @@ import {
   useOnTableUpdate,
   useTriggerSqliteSync,
   useOnSqliteSync,
+  useSqliteTransaction,
 } from '@sqliteai/sqlite-sync-react-native';
 
 interface Task {
@@ -191,14 +194,13 @@ function TaskList() {
   });
 
   // 4. WRITING DATA: Use transactions to trigger reactive queries
-  const { db } = useSqliteDb();
+  const { executeTransaction, isExecuting } = useSqliteTransaction();
   const { triggerSync, isSyncing } = useTriggerSqliteSync();
 
   const addTask = useCallback(
     async (title: string) => {
-      if (!db) return;
       // Use transaction to trigger reactive query update
-      await db.transaction(async (tx) => {
+      await executeTransaction(async (tx) => {
         await tx.execute(
           'INSERT INTO tasks (id, title) VALUES (cloudsync_uuid(), ?);',
           [title]
@@ -207,7 +209,7 @@ function TaskList() {
       // Optional: Push changes to cloud immediately
       triggerSync();
     },
-    [db, triggerSync]
+    [executeTransaction, triggerSync]
   );
 
   if (isLoading) return <Text>Loading local DB...</Text>;
@@ -225,7 +227,11 @@ function TaskList() {
         <Text key={task.id}>{task.title}</Text>
       ))}
 
-      <Button title="Add Task" onPress={() => addTask('New Task')} />
+      <Button
+        title="Add Task"
+        onPress={() => addTask('New Task')}
+        disabled={isExecuting}
+      />
     </View>
   );
 }
@@ -374,21 +380,32 @@ The library provides three separate React Contexts for optimized re-renders:
 
 #### `SQLiteDbContext`
 
-Provides database instance and initialization errors. **Rarely changes** (only on init/error).
+Provides database connections and initialization errors. **Rarely changes** (only on init/error).
 
 ```typescript
 import { useContext } from 'react';
 import { SQLiteDbContext } from '@sqliteai/sqlite-sync-react-native';
 
-const { db, initError } = useContext(SQLiteDbContext);
+const { writeDb, readDb, initError } = useContext(SQLiteDbContext);
 ```
 
 **Values:**
 
-| Property    | Type            | Description                                                                                                          |
-| ----------- | --------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `db`        | `DB \| null`    | [op-sqlite](https://op-engineering.github.io/op-sqlite/docs/api) database instance with SQLite Sync extension loaded |
-| `initError` | `Error \| null` | Fatal database error (db unavailable)                                                                                |
+| Property    | Type            | Description                                                       |
+| ----------- | --------------- | ----------------------------------------------------------------- |
+| `writeDb`   | `DB \| null`    | Write connection for INSERT, UPDATE, DELETE, and sync operations. |
+| `readDb`    | `DB \| null`    | Read connection for SELECT queries.                               |
+| `initError` | `Error \| null` | Fatal database error (db unavailable)                             |
+
+**About the database connections:**
+
+The library uses **dual database connections** for optimal performance:
+
+- **`writeDb`**: Write connection configured with WAL mode and NORMAL synchronous. Has the **SQLite Sync extension loaded** with access to all [SQLite Sync functions](https://github.com/sqliteai/sqlite-sync/blob/main/API.md) like `cloudsync_uuid()`, `cloudsync_changes()`, etc. Use for all INSERT, UPDATE, DELETE, and sync operations.
+
+- **`readDb`**: Read-only connection configured with `query_only = true`. Use for all SELECT queries to prevent blocking during writes and sync operations. Does not have access to SQLite Sync extension functions.
+
+Both connections are `DB` instances from [`@op-engineering/op-sqlite`](https://op-engineering.github.io/op-sqlite/docs/api) with full access to the op-sqlite API.
 
 #### `SQLiteSyncStatusContext`
 
@@ -426,62 +443,63 @@ const { triggerSync } = useContext(SQLiteSyncActionsContext);
 
 **Values:**
 
-| Property      | Type                                   | Description                                                               |
-| ------------- | -------------------------------------- | ------------------------------------------------------------------------- |
-| `triggerSync` | `() => Promise<void>`                  | Function to manually trigger a sync operation                             |
-| `subscribe`   | `(callback: () => void) => () => void` | Subscribe to sync events without re-renders. Returns unsubscribe function |
+| Property          | Type                                   | Description                                                               |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------------------- |
+| `triggerSync`     | `() => Promise<void>`                  | Function to manually trigger a sync operation                             |
+| `subscribeToSync` | `(callback: () => void) => () => void` | Subscribe to sync events without re-renders. Returns unsubscribe function |
 
 **Note:** Most users should use the [specialized hooks](#hooks) instead of accessing contexts directly.
 
-**About the `db` instance:**
-
-The `db` property is a `DB` instance from [`@op-engineering/op-sqlite`](https://op-engineering.github.io/op-sqlite/docs/api) with the **SQLite Sync extension loaded**. This means you can:
-
-- Use the full [op-sqlite API](https://op-engineering.github.io/op-sqlite/docs/api) for standard database operations
-- Use any [SQLite Sync functions](https://github.com/sqliteai/sqlite-sync/blob/main/API.md) like `cloudsync_uuid()`, `cloudsync_changes()`, etc.
-
 ### Hooks
 
 The library provides specialized hooks for different use cases. Choose the right hook based on what data your component needs to avoid unnecessary re-renders.
 
 #### `useSqliteDb()`
 
-Access the database instance and initialization errors **without subscribing to sync updates**. This hook is optimized for components that only need database access and won't re-render on every sync.
+Access the database connections and initialization errors **without subscribing to sync updates**. This hook is optimized for components that only need database access and won't re-render on every sync.
+
+**Important:** The library uses dual connections for optimal performance. Use `readDb` for queries and `writeDb` for write operations.
 
 ```typescript
-const { db, initError } = useSqliteDb();
+const { writeDb, readDb, initError } = useSqliteDb();
 
 if (initError) {
   return <Text>Error: {initError.message}</Text>;
 }
 
-if (!db) {
+if (!writeDb || !readDb) {
   return <Text>Loading...</Text>;
 }
 
-// Use db for queries without re-rendering on sync
+// Use writeDb for write operations
 const addTask = async (title: string) => {
-  await db.execute(
-    'INSERT INTO tasks (id, title) VALUES (cloudsync_uuid(), ?);',
-    [title]
-  );
+  await writeDb.transaction(async (tx) => {
+    await tx.execute(
+      'INSERT INTO tasks (id, title) VALUES (cloudsync_uuid(), ?);',
+      [title]
+    );
+  });
 };
+
+// Use readDb for queries (won't block during sync)
+const result = await readDb.execute('SELECT * FROM tasks');
 ```
 
 **Returns:**
 
-- `db`: Database instance
+- `writeDb`: Write database connection (use for INSERT, UPDATE, DELETE)
+- `readDb`: Read database connection (use for SELECT queries)
 - `initError`: Fatal initialization error
 
-**Best for:** Components that write data or need database access but don't need sync status.
+**Best for:** Components that need direct database access but don't need sync status.
 
-#### `useSyncStatus()`
+#### `useSqliteSyncStatus()`
 
 Access sync status information, use this when you need to display sync state in your UI.
 
 ```typescript
 const { isSyncing, lastSyncTime, syncError, isSyncReady, lastSyncChanges } =
-  useSyncStatus();
+  useSqliteSyncStatus();
 
 return (
   <View>
@@ -521,7 +539,7 @@ return (
 );
 ```
 
-**Returns:** All properties from `useSqliteDb()` + `useSyncStatus()` + `triggerSync` function
+**Returns:** All properties from `useSqliteDb()` + `useSqliteSyncStatus()` hooks and `triggerSync()` + `subscribeToSync()` functions
 
 **Best for:** Components that need access to everything (use sparingly to avoid unnecessary re-renders).
 
@@ -701,6 +719,190 @@ useOnTableUpdate<Task>({
 
 **Note:** For DELETE operations, `row` will be `null` since the row no longer exists in the database.
 
+#### `useSqliteTransaction()`
+
+Execute database transactions with state tracking.
+
+**Important:** Always use transactions for write operations to ensure reactive queries update automatically.
+
+**Returns:**
+
+```typescript
+{
+  executeTransaction: (callback: (tx: Transaction) => Promise<void>) =>
+    Promise<void>;
+  isExecuting: boolean; // True while transaction is executing
+  error: Error | null; // Transaction error if any
+}
+```
+
+**Example:**
+
+```typescript
+const { executeTransaction, isExecuting, error } = useSqliteTransaction();
+
+const handleSave = async () => {
+  try {
+    await executeTransuseSqliteSyncStatus(tx) => {
+      // All operations run in a single transaction
+      await tx.execute(
+        'INSERT INTO tasks (id, title) VALUES (?, ?)',
+        [id, 'New Task']
+      );
+      await tx.execute(
+        'UPDATE counters SET count = count + 1 WHERE type = ?',
+        ['tasks']
+      );
+    });
+    // Transaction committed - reactive queries will update
+    navigation.goBack();
+  } catch (e) {
+    Alert.alert('Error', 'Could not save task');
+  }
+};
+
+return (
+  <Button
+    title="Save"
+    onPress={handleSave}
+    disabled={isExecuting}
+  />
+);
+```
+
+#### `useSqliteExecute()`
+
+Execute single SQL commands (INSERT, UPDATE, DELETE) with state tracking.
+
+**Note:** For most use cases, prefer `useSqliteTransaction` since transactions are required to trigger reactive query updates.
+
+**Returns:**
+
+```typescript
+{
+  execute: (sql: string, params?: any[]) => Promise<QueryResult | undefined>;
+  isExecuting: boolean; // True while executing
+  error: Error | null; // Execution error if any
+}
+```
+
+**Example:**
+
+```typescript
+const { execute, isExecuting, error } = useSqliteExecute();
+
+const handleDelete = async (id: string) => {
+  try {
+    await execute('DELETE FROM tasks WHERE id = ?', [id]);
+    // Note: Reactive queries won't update unless this is in a transaction
+  } catch (e) {
+    Alert.alert('Error', 'Could not delete task');
+  }
+};
+```
+
+### Types
+
+The library exports TypeScript types for all configuration objects and data structures.
+
+#### `ReactiveQueryConfig`
+
+Configuration for reactive queries with table-level granularity.
+
+```typescript
+interface ReactiveQueryConfig {
+  /**
+   * The SQL query to execute
+   */
+  query: string;
+
+  /**
+   * Query parameters/arguments (optional)
+   */
+  arguments?: any[];
+
+  /**
+   * Tables to monitor for changes
+   */
+  fireOn: Array<{
+    /** Table name to monitor */
+    table: string;
+    /** Optional: specific operation to monitor (INSERT, UPDATE, or DELETE) */
+    operation?: 'INSERT' | 'UPDATE' | 'DELETE';
+  }>;
+}
+```
+
+#### `TableUpdateData<T>`
+
+Row-level update event data from op-sqlite's updateHook.
+
+```typescript
+interface TableUpdateData<T = any> {
+  /**
+   * The table that was modified
+   */
+  table: string;
+
+  /**
+   * The type of operation that occurred
+   *
+   * Possible values:
+   * - 'DELETE' - Row was deleted
+   * - 'INSERT' - Row was inserted
+   * - 'UPDATE' - Row was updated
+   */
+  operation: 'INSERT' | 'UPDATE' | 'DELETE';
+
+  /**
+   * SQLite's internal rowid (NOT your table's primary key)
+   */
+  rowId: number;
+
+  /**
+   * The row data retrieved from the database
+   *
+   * The hook automatically queries the database to fetch the row data.
+   * For DELETE operations, this will be null since the row no longer exists.
+   */
+  row: T | null;
+}
+```
+
+#### `TableUpdateConfig<T>`
+
+Configuration for row-level table update listeners.
+
+```typescript
+interface TableUpdateConfig<T = any> {
+  /**
+   * List of table names to monitor for changes
+   */
+  tables: string[];
+
+  /**
+   * Callback function executed when a monitored table is updated
+   *
+   * Receives detailed information about the row-level change
+   * including the operation type (INSERT/UPDATE/DELETE) and row data
+   */
+  onUpdate: (data: TableUpdateData<T>) => void;
+}
+```
+
+#### `TableConfig`
+
+Configuration for tables to sync (used in `SQLiteSyncProvider`).
+
+```typescript
+interface TableConfig {
+  /** Table name (must match cloud table) */
+  name: string;
+  /** CREATE TABLE SQL statement */
+  createTableSql: string;
+}
+```
+
 ## 🚨 Error Handling
 
 The library separates **fatal database errors** from **recoverable sync errors** to enable true offline-first operation.
@@ -710,7 +912,7 @@ The library separates **fatal database errors** from **recoverable sync errors**
 **Fatal errors** that prevent the database from working at all. The app cannot function when these occur.
 
 ```typescript
-const { initError, db } = useSqliteDb();
+const { writeDb, readDb, initError } = useSqliteDb();
 
 if (initError) {
   return <ErrorScreen message="Database unavailable" />;
@@ -724,19 +926,24 @@ if (initError) {
 - Failed to open database file
 - Failed to create tables
 
-**When this happens:** The `db` instance will be `null` and the app cannot work offline or online.
+**When this happens:** Both `writeDb` and `readDb` will be `null` and the app cannot work offline or online.
 
 ### Sync Errors (`syncError`)
 
 **Recoverable errors** that prevent syncing but allow full offline database access.
 
 ```typescript
-const { db } = useSqliteDb();
-const { syncError } = useSyncStatus();
+const { writeDb } = useSqliteDb();
+const { syncError } = useSqliteSyncStatus();
 
 // Database still works offline even with syncError!
-if (db) {
-  await db.execute('INSERT INTO tasks ...');
+if (writeDb) {
+  await writeDb.transaction(async (tx) => {
+    await tx.execute('INSERT INTO tasks (id, title) VALUES (?, ?)', [
+      id,
+      title,
+    ]);
+  });
 }
 
 // Show non-blocking warning
@@ -753,7 +960,7 @@ if (db) {
 - Network initialization failed
 - Temporary network connectivity issues
 
-**When this happens:** The `db` instance is available and fully functional for local-only operations. Sync will be retried on the next interval or when credentials are provided.
+**When this happens:** Both database connections (`writeDb` and `readDb`) are available and fully functional for local-only operations. Sync will be retried on the next interval or when credentials are provided.
 
 **Important:** Sync errors automatically clear on the next successful sync.
 
diff --git a/examples/sync-demo/src/App.tsx b/examples/sync-demo/src/App.tsx
index d3a91e6..536c343 100644
--- a/examples/sync-demo/src/App.tsx
+++ b/examples/sync-demo/src/App.tsx
@@ -16,7 +16,8 @@ import {
   useSqliteSyncQuery,
   useOnTableUpdate,
   useSqliteDb,
-  useSyncStatus,
+  useSqliteSyncStatus,
+  useSqliteTransaction,
 } from '@sqliteai/sqlite-sync-react-native';
 import {
   SQLITE_CLOUD_CONNECTION_STRING,
@@ -41,13 +42,15 @@ import {
  *    - Fires when cloud sync completes
  */
 function TestApp() {
-  const { db, initError } = useSqliteDb();
-  const { isSyncReady, isSyncing, lastSyncTime, syncError } = useSyncStatus();
+  const { writeDb, readDb, initError } = useSqliteDb();
+  const { isSyncReady, isSyncing, lastSyncTime, syncError } =
+    useSqliteSyncStatus();
   const [searchText, setSearchText] = useState('');
   const [text, setText] = useState('');
   const [rowNotification, setRowNotification] = useState<string | null>(null);
   const [syncNotification, setSyncNotification] = useState<string | null>(null);
   const { triggerSync } = useTriggerSqliteSync();
+  const { executeTransaction, isExecuting } = useSqliteTransaction();
 
   // Hook 1: useSqliteSyncQuery - Reactive query with table-level granularity
   // Uses op-sqlite's reactiveExecute to automatically re-run when the table changes
@@ -97,12 +100,12 @@ function TestApp() {
   });
 
   const addRow = async () => {
-    if (!text.trim() || !db) return;
+    if (!text.trim()) return;
 
     try {
       // Use transaction to trigger reactive query updates
       // Reactive queries only fire on committed transactions, not on direct execute
-      await db.transaction(async (tx) => {
+      await executeTransaction(async (tx) => {
         await tx.execute(
           `INSERT INTO ${TABLE_NAME} (id, value) VALUES (cloudsync_uuid(), ?);`,
           [text]
@@ -158,7 +161,7 @@ function TestApp() {
         {/* Status Section */}
         <View style={styles.statusSection}>
           <Text style={styles.status}>
-            Database: {db ? '✅ Ready' : '⏳ Initializing...'}
+            Database: {writeDb && readDb ? '✅ Ready' : '⏳ Initializing...'}
           </Text>
           <Text style={styles.status}>
             Sync: {isSyncReady ? '✅ Enabled' : '⚠️ Offline-only'}
@@ -202,7 +205,7 @@ function TestApp() {
             value={text}
             onChangeText={setText}
           />
-          <Button title="Add Row" onPress={addRow} disabled={!db} />
+          <Button title="Add Row" onPress={addRow} disabled={isExecuting} />
 
           <TouchableOpacity
             style={[styles.button, styles.syncButton]}
diff --git a/src/SQLiteDbContext.tsx b/src/SQLiteDbContext.tsx
index 8bdf6cf..7ed5b91 100644
--- a/src/SQLiteDbContext.tsx
+++ b/src/SQLiteDbContext.tsx
@@ -5,7 +5,8 @@ import type { SQLiteDbContextValue } from './types/SQLiteDbContextValue';
  * Default context value used before SQLiteSyncProvider initializes
  */
 const defaultContextValue: SQLiteDbContextValue = {
-  db: null,
+  writeDb: null,
+  readDb: null,
   initError: null,
 };
 
diff --git a/src/SQLiteSyncActionsContext.tsx b/src/SQLiteSyncActionsContext.tsx
index 948fad3..9178aa5 100644
--- a/src/SQLiteSyncActionsContext.tsx
+++ b/src/SQLiteSyncActionsContext.tsx
@@ -11,10 +11,10 @@ const defaultContextValue: SQLiteSyncActionsContextValue = {
       '⚠️ triggerSync called before SQLiteSyncProvider is mounted'
     );
   },
-  subscribe: () => {
+  subscribeToSync: () => {
     console.warn(
       '[SQLiteSync]',
-      '⚠️ subscribe called before SQLiteSyncProvider is mounted'
+      '⚠️ subscribeToSync called before SQLiteSyncProvider is mounted'
     );
     return () => {};
   },
@@ -23,7 +23,7 @@ const defaultContextValue: SQLiteSyncActionsContextValue = {
 /**
  * React Context for SQLite Sync Actions
  *
- * Provides access to sync actions (like triggerSync).
+ * Provides access to sync actions.
  * This context never changes (stable function reference).
  */
 export const SQLiteSyncActionsContext =
diff --git a/src/SQLiteSyncProvider.tsx b/src/SQLiteSyncProvider.tsx
index fb2a25e..0cbe393 100644
--- a/src/SQLiteSyncProvider.tsx
+++ b/src/SQLiteSyncProvider.tsx
@@ -59,7 +59,8 @@ export function SQLiteSyncProvider({
   ...authProps
 }: SQLiteSyncProviderProps) {
   /** PUBLIC CONTEXT STATE - Values exposed to consumers via Context */
-  const [db, setDb] = useState<DB | null>(null);
+  const [writeDb, setWriteDb] = useState<DB | null>(null);
+  const [readDb, setReadDb] = useState<DB | null>(null);
   const [isSyncReady, setIsSyncReady] = useState(false);
   const [isSyncing, setIsSyncing] = useState(false);
   const [lastSyncTime, setLastSyncTime] = useState<number | null>(null);
@@ -68,7 +69,8 @@ export function SQLiteSyncProvider({
   const [syncError, setSyncError] = useState<Error | null>(null);
 
   /** REFS - Used for internal async logic to avoid closure staleness **/
-  const dbRef = useRef<DB | null>(null);
+  const writeDbRef = useRef<DB | null>(null);
+  const readDbRef = useRef<DB | null>(null);
   const isSyncingRef = useRef(false);
 
   /** SYNC LISTENERS - Subscription pattern for sync events **/
@@ -78,7 +80,7 @@ export function SQLiteSyncProvider({
 
   /** SUBSCRIBE FUNCTION - Allows components to listen for sync events without re-rendering **/
   // Returns an unsubscribe function for cleanup
-  const subscribe = useCallback((callback: () => void) => {
+  const subscribeToSync = useCallback((callback: () => void) => {
     syncListenersRef.current.add(callback);
     return () => {
       syncListenersRef.current.delete(callback);
@@ -105,7 +107,7 @@ export function SQLiteSyncProvider({
   /** SYNC FUNCTION - used for both manual and automatic sync **/
   const performSync = useCallback(async () => {
     /** GUARD: DB **/
-    if (!dbRef.current) {
+    if (!writeDbRef.current) {
       return;
     }
 
@@ -146,7 +148,7 @@ export function SQLiteSyncProvider({
        * `db.reactiveExecute`. Reactive queries are designed to re-run only
        * after a transaction successfully commits, providing a single, efficient update.
        */
-      await dbRef.current.transaction(async (tx) => {
+      await writeDbRef.current.transaction(async (tx) => {
         syncResult = await tx.execute('SELECT cloudsync_network_sync();');
       });
 
@@ -196,18 +198,37 @@ export function SQLiteSyncProvider({
           );
         }
 
-        /** OPEN DATABASE **/
+        /** OPEN DATABASE CONNECTIONS **/
         if (!databaseName) {
           throw new Error('Database name is required');
         }
 
-        const localDb = open({ name: databaseName });
-        dbRef.current = localDb;
+        // Open write connection
+        const localWriteDb = open({ name: databaseName });
+
+        // Configure write connection for optimal write performance
+        await localWriteDb.execute('PRAGMA journal_mode = WAL');
+        await localWriteDb.execute('PRAGMA synchronous = NORMAL');
+
+        writeDbRef.current = localWriteDb;
+        if (isMounted) {
+          setWriteDb(localWriteDb);
+        }
+
+        logger.info('✅ Write database opened:', databaseName);
+
+        // Open read connection
+        const localReadDb = open({ name: databaseName });
+
+        // Configure read connection as read-only to prevent blocking
+        await localReadDb.execute('PRAGMA query_only = true');
+
+        readDbRef.current = localReadDb;
         if (isMounted) {
-          setDb(localDb);
+          setReadDb(localReadDb);
         }
 
-        logger.info('✅ Database opened:', databaseName);
+        logger.info('✅ Read database opened:', databaseName);
 
         /** CREATE TABLES **/
         if (tablesToBeSynced.length === 0) {
@@ -215,7 +236,7 @@ export function SQLiteSyncProvider({
         } else {
           for (const table of tablesToBeSynced) {
             try {
-              await localDb.execute(table.createTableSql);
+              await localWriteDb.execute(table.createTableSql);
               logger.info(`✅ Table created: ${table.name}`);
             } catch (createErr) {
               logger.error(
@@ -254,11 +275,11 @@ export function SQLiteSyncProvider({
             extensionPath = 'cloudsync';
           }
 
-          localDb.loadExtension(extensionPath);
+          localWriteDb.loadExtension(extensionPath);
           logger.info('✅ CloudSync extension loaded');
 
           /** VERIFY CLOUDSYNC EXTENSION **/
-          const versionResult = await localDb.execute(
+          const versionResult = await localWriteDb.execute(
             'SELECT cloudsync_version();'
           );
           const version = versionResult.rows?.[0]?.['cloudsync_version()'];
@@ -270,7 +291,7 @@ export function SQLiteSyncProvider({
 
           /** INITIALIZE CLOUDSYNC FOR TABLES **/
           for (const table of tablesToBeSynced) {
-            const initResult = await localDb.execute(
+            const initResult = await localWriteDb.execute(
               'SELECT cloudsync_init(?);',
               [table.name]
             );
@@ -286,21 +307,23 @@ export function SQLiteSyncProvider({
           }
 
           /** INITIALIZE NETWORK CONNECTION **/
-          await localDb.execute('SELECT cloudsync_network_init(?);', [
+          await localWriteDb.execute('SELECT cloudsync_network_init(?);', [
             connectionString,
           ]);
           logger.info('✅ Network initialized');
 
           /** SET AUTHENTICATION **/
           if (apiKey) {
-            await localDb.execute('SELECT cloudsync_network_set_apikey(?);', [
-              apiKey,
-            ]);
+            await localWriteDb.execute(
+              'SELECT cloudsync_network_set_apikey(?);',
+              [apiKey]
+            );
             logger.info('✅ API key set');
           } else if (accessToken) {
-            await localDb.execute('SELECT cloudsync_network_set_token(?);', [
-              accessToken,
-            ]);
+            await localWriteDb.execute(
+              'SELECT cloudsync_network_set_token(?);',
+              [accessToken]
+            );
             logger.info('✅ Access token set');
           }
 
@@ -343,16 +366,27 @@ export function SQLiteSyncProvider({
     return () => {
       isMounted = false;
 
-      /** CLEANUP - close database safeguard **/
-      const closingDb = dbRef.current;
-      dbRef.current = null;
+      /** CLEANUP - close database connections **/
+      const closingWriteDb = writeDbRef.current;
+      const closingReadDb = readDbRef.current;
+      writeDbRef.current = null;
+      readDbRef.current = null;
+
+      if (closingWriteDb) {
+        try {
+          closingWriteDb.close();
+          logger.info('Write database closed');
+        } catch (err) {
+          logger.error('❌ Error closing write database:', err);
+        }
+      }
 
-      if (closingDb) {
+      if (closingReadDb) {
         try {
-          closingDb.close();
-          logger.info('Database closed');
+          closingReadDb.close();
+          logger.info('Read database closed');
         } catch (err) {
-          logger.error('❌ Error closing database:', err);
+          logger.error('❌ Error closing read database:', err);
         }
       }
     };
@@ -377,10 +411,11 @@ export function SQLiteSyncProvider({
   /** SPLIT CONTEXT VALUES - for optimized rendering */
   const dbContextValue = useMemo<SQLiteDbContextValue>(
     () => ({
-      db,
+      writeDb,
+      readDb,
       initError,
     }),
-    [db, initError]
+    [writeDb, readDb, initError]
   );
   const syncStatusContextValue = useMemo<SQLiteSyncStatusContextValue>(
     () => ({
@@ -395,9 +430,9 @@ export function SQLiteSyncProvider({
   const syncActionsContextValue = useMemo<SQLiteSyncActionsContextValue>(
     () => ({
       triggerSync: performSync,
-      subscribe,
+      subscribeToSync,
     }),
-    [performSync, subscribe]
+    [performSync, subscribeToSync]
   );
 
   return (
diff --git a/src/hooks/useOnSqliteSync.ts b/src/hooks/useOnSqliteSync.ts
index 3746b67..f03a523 100644
--- a/src/hooks/useOnSqliteSync.ts
+++ b/src/hooks/useOnSqliteSync.ts
@@ -29,7 +29,7 @@ import { SQLiteSyncActionsContext } from '../SQLiteSyncActionsContext';
  * ```
  */
 export function useOnSqliteSync(callback: () => void) {
-  const { subscribe } = useContext(SQLiteSyncActionsContext);
+  const { subscribeToSync } = useContext(SQLiteSyncActionsContext);
 
   // Store callback in ref to allow inline functions without causing infinite loops
   const savedCallback = useRef(callback);
@@ -43,10 +43,10 @@ export function useOnSqliteSync(callback: () => void) {
   // 2. Subscribe to sync events
   // This does NOT cause re-renders - it's a pure subscription
   useEffect(() => {
-    const unsubscribe = subscribe(() => {
+    const unsubscribe = subscribeToSync(() => {
       savedCallback.current();
     });
 
     return unsubscribe;
-  }, [subscribe]);
+  }, [subscribeToSync]);
 }
diff --git a/src/hooks/useOnTableUpdate.ts b/src/hooks/useOnTableUpdate.ts
index 9624fe8..20d5bc3 100644
--- a/src/hooks/useOnTableUpdate.ts
+++ b/src/hooks/useOnTableUpdate.ts
@@ -54,7 +54,7 @@ import type { TableUpdateConfig } from '../types/TableUpdateConfig';
  * For DELETE operations, `row` will be `null` since the row no longer exists.
  */
 export function useOnTableUpdate<T = any>(config: TableUpdateConfig<T>) {
-  const { db } = useContext(SQLiteDbContext);
+  const { writeDb, readDb } = useContext(SQLiteDbContext);
 
   // Store callback in ref to allow inline functions without causing infinite loops
   const savedCallback = useRef(config.onUpdate);
@@ -67,23 +67,21 @@ export function useOnTableUpdate<T = any>(config: TableUpdateConfig<T>) {
   }, [config.onUpdate, config.tables]);
 
   useEffect(() => {
-    if (!db) return;
+    if (!writeDb || !readDb) return;
 
-    // Subscribe to update hook - fires on every row change
-    db.updateHook(async (hookData) => {
-      // Only fire callback if the updated table is in our watch list
+    // Subscribe to update hook on write connection - fires on every row change
+    writeDb.updateHook(async (hookData) => {
       if (!savedTables.current.includes(hookData.table)) {
         return;
       }
 
-      // Fetch the row data using SQLite's internal rowid
       let row: T | null = null;
 
       // For DELETE operations, the row no longer exists, so row will be null
       // For INSERT and UPDATE, we can fetch the row data
       if (hookData.operation !== 'DELETE') {
         try {
-          const result = await db.execute(
+          const result = await readDb.execute(
             `SELECT * FROM ${hookData.table} WHERE rowid = ?`,
             [hookData.rowId]
           );
@@ -93,7 +91,6 @@ export function useOnTableUpdate<T = any>(config: TableUpdateConfig<T>) {
         }
       }
 
-      // Call the user's callback with enriched data including the row
       savedCallback.current({
         table: hookData.table,
         operation: hookData.operation,
@@ -104,7 +101,7 @@ export function useOnTableUpdate<T = any>(config: TableUpdateConfig<T>) {
 
     // Cleanup: Remove the hook on unmount by passing null
     return () => {
-      db.updateHook(null);
+      writeDb.updateHook(null);
     };
-  }, [db]);
+  }, [writeDb, readDb]);
 }
diff --git a/src/hooks/useSqliteExecute.ts b/src/hooks/useSqliteExecute.ts
index 3ac95e7..a314701 100644
--- a/src/hooks/useSqliteExecute.ts
+++ b/src/hooks/useSqliteExecute.ts
@@ -32,7 +32,7 @@ import { SQLiteDbContext } from '../SQLiteDbContext';
  * ```
  */
 export function useSqliteExecute() {
-  const { db } = useContext(SQLiteDbContext);
+  const { writeDb } = useContext(SQLiteDbContext);
 
   const [isExecuting, setIsExecuting] = useState(false);
   const [error, setError] = useState<Error | null>(null);
@@ -52,7 +52,7 @@ export function useSqliteExecute() {
       sql: string,
       params: any[] = []
     ): Promise<QueryResult | undefined> => {
-      if (!db) {
+      if (!writeDb) {
         return undefined;
       }
 
@@ -60,7 +60,7 @@ export function useSqliteExecute() {
       setError(null);
 
       try {
-        const result = await db.execute(sql, params);
+        const result = await writeDb.execute(sql, params);
         return result;
       } catch (err) {
         const errorObj =
@@ -73,7 +73,7 @@ export function useSqliteExecute() {
         setIsExecuting(false);
       }
     },
-    [db]
+    [writeDb]
   );
 
   return {
diff --git a/src/hooks/useSqliteSyncQuery.ts b/src/hooks/useSqliteSyncQuery.ts
index 2692dc0..fc2b432 100644
--- a/src/hooks/useSqliteSyncQuery.ts
+++ b/src/hooks/useSqliteSyncQuery.ts
@@ -52,7 +52,7 @@ import type { ReactiveQueryConfig } from '../types/ReactiveQueryConfig';
  * will fire when cloud changes arrive.
  */
 export function useSqliteSyncQuery<T = any>(config: ReactiveQueryConfig) {
-  const { db } = useContext(SQLiteDbContext);
+  const { readDb } = useContext(SQLiteDbContext);
 
   const [data, setData] = useState<T[]>([]);
   const [isLoading, setIsLoading] = useState(true);
@@ -64,12 +64,13 @@ export function useSqliteSyncQuery<T = any>(config: ReactiveQueryConfig) {
   const serializedFireOn = JSON.stringify(config.fireOn);
 
   useEffect(() => {
-    if (!db) return;
+    if (!readDb) return;
 
     setIsLoading(true);
     setError(null);
 
-    db.execute(config.query, config.arguments || [])
+    readDb
+      .execute(config.query, config.arguments || [])
       .then((result) => {
         setData((result.rows || []) as T[]);
         setIsLoading(false);
@@ -80,7 +81,7 @@ export function useSqliteSyncQuery<T = any>(config: ReactiveQueryConfig) {
         setIsLoading(false);
       });
 
-    const unsubscribe = db.reactiveExecute({
+    const unsubscribe = readDb.reactiveExecute({
       query: config.query,
       arguments: config.arguments || [],
       fireOn: config.fireOn,
@@ -96,7 +97,7 @@ export function useSqliteSyncQuery<T = any>(config: ReactiveQueryConfig) {
       unsubscribeRef.current = null;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [db, config.query, serializedArgs, serializedFireOn]);
+  }, [readDb, config.query, serializedArgs, serializedFireOn]);
 
   const unsubscribe = useCallback(() => {
     if (unsubscribeRef.current) {
diff --git a/src/hooks/useSyncStatus.ts b/src/hooks/useSqliteSyncStatus.ts
similarity index 87%
rename from src/hooks/useSyncStatus.ts
rename to src/hooks/useSqliteSyncStatus.ts
index c680906..97216a7 100644
--- a/src/hooks/useSyncStatus.ts
+++ b/src/hooks/useSqliteSyncStatus.ts
@@ -12,7 +12,7 @@ import { SQLiteSyncStatusContext } from '../SQLiteSyncStatusContext';
  * @example
  * ```typescript
  * function SyncStatus() {
- *   const { isSyncing, lastSyncTime, syncError } = useSyncStatus();
+ *   const { isSyncing, lastSyncTime, syncError } = useSqliteSyncStatus();
  *
  *   return (
  *     <View>
@@ -26,6 +26,6 @@ import { SQLiteSyncStatusContext } from '../SQLiteSyncStatusContext';
  * }
  * ```
  */
-export function useSyncStatus() {
+export function useSqliteSyncStatus() {
   return useContext(SQLiteSyncStatusContext);
 }
diff --git a/src/hooks/useSqliteTransaction.ts b/src/hooks/useSqliteTransaction.ts
new file mode 100644
index 0000000..e552cea
--- /dev/null
+++ b/src/hooks/useSqliteTransaction.ts
@@ -0,0 +1,80 @@
+import { useContext, useState, useCallback } from 'react';
+import type { Transaction } from '@op-engineering/op-sqlite';
+import { SQLiteDbContext } from '../SQLiteDbContext';
+
+/**
+ * Hook for executing database transactions.
+ *
+ * Transactions are essential for:
+ * - Ensuring multiple operations succeed or fail together (atomicity)
+ * - Triggering reactive queries (only fire on committed transactions)
+ * - Better performance for bulk operations
+ *
+ * **Important:** Reactive queries (useSqliteSyncQuery) only update when transactions commit.
+ * Always use transactions for write operations to ensure reactive queries update.
+ *
+ * @returns Object containing the transaction function and execution state
+ *
+ * @example
+ * ```typescript
+ * const { executeTransaction, isExecuting, error } = useSqliteTransaction();
+ *
+ * const handleSave = async () => {
+ *   try {
+ *     await executeTransaction(async (tx) => {
+ *       await tx.execute('INSERT INTO todos (id, text) VALUES (?, ?)', [id, 'New Item']);
+ *       await tx.execute('UPDATE counters SET count = count + 1 WHERE type = ?', ['todos']);
+ *     });
+ *     navigation.goBack();
+ *   } catch (e) {
+ *     Alert.alert('Error', 'Could not save todo');
+ *   }
+ * };
+ * ```
+ */
+export function useSqliteTransaction() {
+  const { writeDb } = useContext(SQLiteDbContext);
+
+  const [isExecuting, setIsExecuting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  /**
+   * Executes a transaction against the local database.
+   *
+   * @param callback - Async function that receives the transaction object
+   *
+   * @returns Promise resolving when transaction commits
+   *
+   * @throws Error if transaction fails (allows for try/catch in UI handler)
+   */
+  const executeTransaction = useCallback(
+    async (callback: (tx: Transaction) => Promise<void>): Promise<void> => {
+      if (!writeDb) {
+        throw new Error('Database not initialized');
+      }
+
+      setIsExecuting(true);
+      setError(null);
+
+      try {
+        await writeDb.transaction(callback);
+      } catch (err) {
+        const errorObj =
+          err instanceof Error ? err : new Error('Transaction failed');
+
+        setError(errorObj);
+
+        throw errorObj;
+      } finally {
+        setIsExecuting(false);
+      }
+    },
+    [writeDb]
+  );
+
+  return {
+    executeTransaction,
+    isExecuting,
+    error,
+  };
+}
diff --git a/src/index.tsx b/src/index.tsx
index 14467b7..cbaf602 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -7,8 +7,9 @@ export { useOnSqliteSync } from './hooks/useOnSqliteSync';
 export { useSqliteSyncQuery } from './hooks/useSqliteSyncQuery';
 export { useOnTableUpdate } from './hooks/useOnTableUpdate';
 export { useSqliteExecute } from './hooks/useSqliteExecute';
+export { useSqliteTransaction } from './hooks/useSqliteTransaction';
 export { useSqliteDb } from './hooks/useSqliteDb';
-export { useSyncStatus } from './hooks/useSyncStatus';
+export { useSqliteSyncStatus } from './hooks/useSqliteSyncStatus';
 export { useSqliteSync } from './hooks/useSqliteSync';
 export type { SQLiteSyncProviderProps } from './types/SQLiteSyncProviderProps';
 export type { SQLiteDbContextValue } from './types/SQLiteDbContextValue';
diff --git a/src/types/SQLiteDbContextValue.ts b/src/types/SQLiteDbContextValue.ts
index 2166d21..77494a1 100644
--- a/src/types/SQLiteDbContextValue.ts
+++ b/src/types/SQLiteDbContextValue.ts
@@ -2,13 +2,24 @@ import type { DB } from '@op-engineering/op-sqlite';
 
 /**
  * Database context value - rarely changes (only on init/error)
+ *
+ * Uses separate read and write connections for optimal performance:
+ * - Write connection: WAL mode + NORMAL synchronous for fast writes
+ * - Read connection: query_only = true to prevent blocking during writes/sync
  */
 export interface SQLiteDbContextValue {
   /**
-   * Database instance for local operations
-   * Check `db !== null` to verify database is ready
+   * Write database connection for INSERT, UPDATE, DELETE, and sync operations
+   * Configured with WAL mode and NORMAL synchronous for optimal write performance
    */
-  db: DB | null;
+  writeDb: DB | null;
+
+  /**
+   * Read database connection for SELECT queries
+   * Configured with query_only = true to prevent blocking during writes
+   * Use this for all read operations to avoid blocking during sync
+   */
+  readDb: DB | null;
 
   /**
    * Initialization error (fatal - prevents database from working)
diff --git a/src/types/SQLiteSyncActionsContextValue.ts b/src/types/SQLiteSyncActionsContextValue.ts
index d91842d..40a4430 100644
--- a/src/types/SQLiteSyncActionsContextValue.ts
+++ b/src/types/SQLiteSyncActionsContextValue.ts
@@ -14,5 +14,5 @@ export interface SQLiteSyncActionsContextValue {
    * Returns an unsubscribe function
    * Callback is called when sync completes with changes (changes > 0)
    */
-  subscribe: (callback: () => void) => () => void;
+  subscribeToSync: (callback: () => void) => () => void;
 }

From da4acebb06e86fe8a7a40d150c7ec9e20f793412 Mon Sep 17 00:00:00 2001
From: damlayildiz <damlayildiz19@ku.edu.tr>
Date: Wed, 17 Dec 2025 19:09:45 +0100
Subject: [PATCH 2/4] fix: demo app - loading state

---
 examples/sync-demo/src/App.tsx | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/examples/sync-demo/src/App.tsx b/examples/sync-demo/src/App.tsx
index 536c343..41d73bb 100644
--- a/examples/sync-demo/src/App.tsx
+++ b/examples/sync-demo/src/App.tsx
@@ -132,8 +132,9 @@ function TestApp() {
     );
   }
 
-  // Show loading spinner only on first load (offline-first: data loads immediately from local DB)
-  if (isLoading) {
+  // Show full-screen loading spinner only on initial load (when we have no data yet)
+  // For subsequent queries (like search filter changes), we'll show an inline loader
+  if (isLoading && rows.length === 0) {
     return (
       <View style={styles.container}>
         <ActivityIndicator size="large" color="#007AFF" />
@@ -220,6 +221,7 @@ function TestApp() {
 
         <View style={styles.listHeader}>
           <Text style={styles.rowCount}>Rows: {rows.length}</Text>
+          {isLoading && <ActivityIndicator size="small" color="#007AFF" />}
         </View>
       </View>
 

From cdea1c34eae0fb576d8f5f9a9cc205f1bfd8d306 Mon Sep 17 00:00:00 2001
From: damlayildiz <damlayildiz19@ku.edu.tr>
Date: Wed, 17 Dec 2025 19:12:42 +0100
Subject: [PATCH 3/4] fix: demo app - remove global loading state

---
 examples/sync-demo/src/App.tsx | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/examples/sync-demo/src/App.tsx b/examples/sync-demo/src/App.tsx
index 41d73bb..d1aa34c 100644
--- a/examples/sync-demo/src/App.tsx
+++ b/examples/sync-demo/src/App.tsx
@@ -132,17 +132,6 @@ function TestApp() {
     );
   }
 
-  // Show full-screen loading spinner only on initial load (when we have no data yet)
-  // For subsequent queries (like search filter changes), we'll show an inline loader
-  if (isLoading && rows.length === 0) {
-    return (
-      <View style={styles.container}>
-        <ActivityIndicator size="large" color="#007AFF" />
-        <Text style={styles.status}>Loading data from local database...</Text>
-      </View>
-    );
-  }
-
   // Show query error
   if (error) {
     return (

From 36eecaf189d9517c9bba1ddef0d4803d512a61ff Mon Sep 17 00:00:00 2001
From: damlayildiz <damlayildiz19@ku.edu.tr>
Date: Thu, 18 Dec 2025 11:07:28 +0100
Subject: [PATCH 4/4] fix: SQLiteSyncProvider - read db config

---
 src/SQLiteSyncProvider.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/SQLiteSyncProvider.tsx b/src/SQLiteSyncProvider.tsx
index 0cbe393..c84ba4b 100644
--- a/src/SQLiteSyncProvider.tsx
+++ b/src/SQLiteSyncProvider.tsx
@@ -146,7 +146,7 @@ export function SQLiteSyncProvider({
       /**
        * Wrap the sync command in a transaction. It ensures compatibility with op-sqlite's
        * `db.reactiveExecute`. Reactive queries are designed to re-run only
-       * after a transaction successfully commits, providing a single, efficient update.
+       * after a transaction successfully commits, providing a single, efficient update.ÅÅ
        */
       await writeDbRef.current.transaction(async (tx) => {
         syncResult = await tx.execute('SELECT cloudsync_network_sync();');
@@ -206,7 +206,6 @@ export function SQLiteSyncProvider({
         // Open write connection
         const localWriteDb = open({ name: databaseName });
 
-        // Configure write connection for optimal write performance
         await localWriteDb.execute('PRAGMA journal_mode = WAL');
         await localWriteDb.execute('PRAGMA synchronous = NORMAL');
 
@@ -220,7 +219,8 @@ export function SQLiteSyncProvider({
         // Open read connection
         const localReadDb = open({ name: databaseName });
 
-        // Configure read connection as read-only to prevent blocking
+        await localReadDb.execute('PRAGMA journal_mode = WAL');
+        await localReadDb.execute('PRAGMA locking_mode = NORMAL');
         await localReadDb.execute('PRAGMA query_only = true');
 
         readDbRef.current = localReadDb;