feat: support interruptible transactions

Author: pmorris-dev

Cargo.lock

@@ -24,6 +24,7 @@ tokio = { version = "1.48.0", features = ["rt", "sync", "time"] }
 indexmap = { version = "2.12.1", features = ["serde"] }
 base64 = "0.22.1"
 tracing = { version = "0.1.41", default-features = false, features = ["std", "release_max_level_off"] }
+uuid = { version = "1.11.0", features = ["v4"] }
 
 # SQLx for types and queries (time feature enables datetime type decoding)
 sqlx = { version = "0.8.6", features = ["sqlite", "json", "time", "runtime-tokio"] }

Cargo.toml

@@ -238,7 +238,7 @@ const user = await db.fetchOne<User>(
 
 ### Transactions
 
-Execute multiple statements atomically:
+For most cases, use `executeTransaction()` to run multiple statements atomically:
 
 ```typescript
 const results = await db.executeTransaction([
@@ -250,6 +250,54 @@ const results = await db.executeTransaction([
 
 Transactions use `BEGIN IMMEDIATE`, commit on success, and rollback on any failure.
 
+#### Pausable Transactions
+
+**Use pausable transactions when you need to read data mid-transaction to decide how to
+proceed.** For example, inserting a record, reading back its generated ID or other
+computed values, then using that data in subsequent writes.
+
+```typescript
+// Begin transaction with initial insert
+const token = await db.executePausableTransaction([
+   ['INSERT INTO orders (user_id, total) VALUES ($1, $2)', [userId, 0]]
+])
+
+// Read the uncommitted data to get the generated order ID
+const orders = await db.transactionRead<Array<{ id: number }>>(
+   token,
+   'SELECT id FROM orders WHERE user_id = $1 ORDER BY id DESC LIMIT 1',
+   [userId]
+)
+const orderId = orders[0].id
+
+// Continue transaction with the order ID
+const newToken = await db.transactionContinue(token, {
+   type: 'Continue',
+   statements: [
+      { query: 'INSERT INTO order_items (order_id, product_id) VALUES ($1, $2)', values: [orderId, productId] },
+      { query: 'UPDATE orders SET total = $1 WHERE id = $2', values: [itemTotal, orderId] }
+   ]
+})
+
+// Commit the transaction
+await db.transactionContinue(newToken!, { type: 'Commit' })
+```
+
+**Important:**
+
+   * Only one pausable transaction can be active per database at a time
+   * The write lock is held for the entire duration - keep transactions short
+   * Uncommitted writes are visible only within `transactionRead()` on the same
+     transaction
+   * Always commit or rollback - abandoned transactions will rollback automatically
+     on app exit
+
+To rollback instead of committing:
+
+```typescript
+await db.transactionContinue(token, { type: 'Rollback' })
+```
+
 ### Error Handling
 
 ```typescript
@@ -296,7 +344,10 @@ await db.remove()          // Close and DELETE database file(s) - irreversible!
 | Method | Description |
 | ------ | ----------- |
 | `execute(query, values?)` | Execute write query, returns `{ rowsAffected, lastInsertId }` |
-| `executeTransaction(statements)` | Execute statements atomically |
+| `executeTransaction(statements)` | Execute statements atomically (use for batch writes) |
+| `executePausableTransaction(statements)` | Begin pausable transaction, returns token |
+| `transactionContinue(token, action)` | Continue, commit, or rollback pausable transaction |
+| `transactionRead<T>(token, query, values?)` | Read uncommitted data within transaction |
 | `fetchAll<T>(query, values?)` | Execute SELECT, return all rows |
 | `fetchOne<T>(query, values?)` | Execute SELECT, return single row or `undefined` |
 | `close()` | Close connection, returns `true` if was loaded |

README.md

@@ -15,11 +15,23 @@ beforeEach(() => {
       if (cmd === 'plugin:sqlite|load') return (args as { db: string }).db
       if (cmd === 'plugin:sqlite|execute') return [1, 1]
       if (cmd === 'plugin:sqlite|execute_transaction') return []
+      if (cmd === 'plugin:sqlite|execute_pausable_transaction') {
+         return { dbPath: (args as { db: string }).db, transactionId: 'test-tx-id' }
+      }
+      if (cmd === 'plugin:sqlite|transaction_continue') {
+         const action = (args as { action: { type: string } }).action
+         if (action.type === 'Continue') {
+            return { dbPath: 'test.db', transactionId: 'test-tx-id' }
+         }
+         return undefined
+      }
+      if (cmd === 'plugin:sqlite|transaction_read') return []
       if (cmd === 'plugin:sqlite|fetch_all') return []
       if (cmd === 'plugin:sqlite|fetch_one') return null
       if (cmd === 'plugin:sqlite|close') return true
       if (cmd === 'plugin:sqlite|close_all') return undefined
       if (cmd === 'plugin:sqlite|remove') return true
+      if (cmd === 'plugin:sqlite|get_migration_events') return []
       return undefined
    })
 })
@@ -92,6 +104,66 @@ describe('Database commands', () => {
       expect(events).toEqual(mockEvents)
    })
 
+   it('getMigrationEvents - empty array', async () => {
+      const events = await Database.get('test.db').getMigrationEvents()
+      expect(lastCmd).toBe('plugin:sqlite|get_migration_events')
+      expect(lastArgs.db).toBe('test.db')
+      expect(events).toEqual([])
+   })
+
+   it('executePausableTransaction', async () => {
+      const token = await Database.get('t.db').executePausableTransaction([
+         ['INSERT INTO users (name) VALUES ($1)', ['Alice']]
+      ])
+      expect(lastCmd).toBe('plugin:sqlite|execute_pausable_transaction')
+      expect(lastArgs.db).toBe('t.db')
+      expect(lastArgs.initialStatements).toEqual([
+         { query: 'INSERT INTO users (name) VALUES ($1)', values: ['Alice'] }
+      ])
+      expect(token.dbPath).toBe('t.db')
+      expect(token.transactionId).toBe('test-tx-id')
+   })
+
+   it('transactionContinue - Continue action', async () => {
+      const token = { dbPath: 'test.db', transactionId: 'test-tx-id' }
+      const newToken = await Database.get('test.db').transactionContinue(token, {
+         type: 'Continue',
+         statements: [{ query: 'INSERT INTO users (name) VALUES ($1)', values: ['Bob'] }]
+      })
+      expect(lastCmd).toBe('plugin:sqlite|transaction_continue')
+      expect(lastArgs.token).toEqual(token)
+      expect((lastArgs.action as { type: string }).type).toBe('Continue')
+      expect(newToken).toBeDefined()
+      expect(newToken?.transactionId).toBe('test-tx-id')
+   })
+
+   it('transactionContinue - Commit action', async () => {
+      const token = { dbPath: 'test.db', transactionId: 'test-tx-id' }
+      const result = await Database.get('test.db').transactionContinue(token, { type: 'Commit' })
+      expect(lastCmd).toBe('plugin:sqlite|transaction_continue')
+      expect(lastArgs.token).toEqual(token)
+      expect((lastArgs.action as { type: string }).type).toBe('Commit')
+      expect(result).toBeUndefined()
+   })
+
+   it('transactionContinue - Rollback action', async () => {
+      const token = { dbPath: 'test.db', transactionId: 'test-tx-id' }
+      const result = await Database.get('test.db').transactionContinue(token, { type: 'Rollback' })
+      expect(lastCmd).toBe('plugin:sqlite|transaction_continue')
+      expect(lastArgs.token).toEqual(token)
+      expect((lastArgs.action as { type: string }).type).toBe('Rollback')
+      expect(result).toBeUndefined()
+   })
+
+   it('transactionRead', async () => {
+      const token = { dbPath: 'test.db', transactionId: 'test-tx-id' }
+      await Database.get('test.db').transactionRead(token, 'SELECT * FROM users WHERE name = $1', ['Alice'])
+      expect(lastCmd).toBe('plugin:sqlite|transaction_read')
+      expect(lastArgs.token).toEqual(token)
+      expect(lastArgs.query).toBe('SELECT * FROM users WHERE name = $1')
+      expect(lastArgs.values).toEqual(['Alice'])
+   })
+
    it('handles errors from backend', async () => {
       mockIPC(() => {
          throw new Error('Database error')

api-iife.js

@@ -38,6 +38,25 @@ export interface SqliteError {
    message: string
 }
 
+/**
+ * Token representing an active pausable transaction.
+ * Used to continue, commit, or rollback the transaction.
+ */
+export interface TransactionToken {
+   /** Database path */
+   dbPath: string
+   /** Unique transaction ID */
+   transactionId: string
+}
+
+/**
+ * Actions that can be performed on a pausable transaction.
+ */
+export type TransactionAction =
+   | { type: 'Continue'; statements: Array<{ query: string; values: SqlValue[] }> }
+   | { type: 'Commit' }
+   | { type: 'Rollback' }
+
 /**
  * Custom configuration for SQLite database connection
  */
@@ -196,6 +215,10 @@ export default class Database {
     * Executes multiple write statements atomically within a transaction.
     * All statements either succeed together or fail together.
     *
+    * **Use this method** when you have a batch of writes to execute and don't need to
+    * read data mid-transaction. For transactions that require reading uncommitted data
+    * to decide how to proceed, use `executePausableTransaction()` instead.
+    *
     * The function automatically:
     * - Begins a transaction (BEGIN)
     * - Executes all statements in order
@@ -365,6 +388,154 @@ export default class Database {
       return success
    }
 
+   /**
+    * **executePausableTransaction**
+    *
+    * Begins a pausable transaction for cases where you need to **read data mid-transaction
+    * to decide how to proceed**. For example, inserting a record and then reading its
+    * generated ID or computed values before continuing with related writes.
+    *
+    * The transaction remains open, holding a write lock on the database, until you
+    * commit or rollback using `transactionContinue()`.
+    *
+    * **Use this method when:**
+    * - You need to read back generated IDs (e.g., AUTOINCREMENT columns)
+    * - You need to see computed values (e.g., triggers, default values)
+    * - Your next writes depend on data from earlier writes in the same transaction
+    *
+    * **Use `executeTransaction()` instead when:**
+    * - You just need to execute a batch of writes atomically
+    * - You know all the data upfront and don't need to read mid-transaction
+    *
+    * While paused, you can:
+    * - Read uncommitted data using `transactionRead()`
+    * - Continue with more statements using `transactionContinue()` with Continue action
+    * - Commit the transaction using `transactionContinue()` with Commit action
+    * - Rollback the transaction using `transactionContinue()` with Rollback action
+    *
+    * **Important:** Only one transaction can be active per database at a time. The
+    * writer connection is held for the entire duration - keep transactions short.
+    *
+    * @param initialStatements - Array of [query, values?] tuples to execute initially
+    * @returns Promise that resolves with a transaction token
+    *
+    * @example
+    * ```ts
+    * // Insert an order and read back its ID
+    * const token = await db.executePausableTransaction([
+    *    ['INSERT INTO orders (user_id, total) VALUES ($1, $2)', [userId, 0]]
+    * ]);
+    *
+    * // Read the generated order ID
+    * const orders = await db.transactionRead<Array<{ id: number }>>(
+    *    token,
+    *    'SELECT id FROM orders WHERE user_id = $1 ORDER BY id DESC LIMIT 1',
+    *    [userId]
+    * );
+    * const orderId = orders[0].id;
+    *
+    * // Use the ID in subsequent writes
+    * const newToken = await db.transactionContinue(token, {
+    *    type: 'Continue',
+    *    statements: [
+    *       { query: 'INSERT INTO order_items (order_id, product_id) VALUES ($1, $2)', values: [orderId, productId] }
+    *    ]
+    * });
+    *
+    * await db.transactionContinue(newToken!, { type: 'Commit' });
+    * ```
+    */
+   async executePausableTransaction(
+      initialStatements: Array<[string, SqlValue[]?]>
+   ): Promise<TransactionToken> {
+      return await invoke<TransactionToken>('plugin:sqlite|execute_pausable_transaction', {
+         db: this.path,
+         initialStatements: initialStatements.map(([query, values]) => ({
+            query,
+            values: values ?? []
+         }))
+      })
+   }
+
+   /**
+    * **transactionContinue**
+    *
+    * Continue, commit, or rollback a pausable transaction.
+    *
+    * Actions:
+    * - `{ type: 'Continue', statements: [...] }` - Execute more statements and return updated token
+    * - `{ type: 'Commit' }` - Commit the transaction and release the write lock
+    * - `{ type: 'Rollback' }` - Rollback the transaction and release the write lock
+    *
+    * @param token - Transaction token from executePausableTransaction
+    * @param action - Action to perform
+    * @returns Promise that resolves with a new token if continuing, or undefined if committed/rolled back
+    *
+    * @example
+    * ```ts
+    * const token = await db.executePausableTransaction([
+    *    ['INSERT INTO users (name) VALUES ($1)', ['Alice']]
+    * ]);
+    *
+    * const newToken = await db.transactionContinue(token, {
+    *    type: 'Continue',
+    *    statements: [{ query: 'INSERT INTO users (name) VALUES ($1)', values: ['Bob'] }]
+    * });
+    *
+    * await db.transactionContinue(newToken!, { type: 'Commit' });
+    * ```
+    */
+   async transactionContinue(
+      token: TransactionToken,
+      action: TransactionAction
+   ): Promise<TransactionToken | undefined> {
+      return await invoke<TransactionToken | undefined>('plugin:sqlite|transaction_continue', {
+         token,
+         action
+      })
+   }
+
+   /**
+    * **transactionRead**
+    *
+    * Read data from the database within a pausable transaction context.
+    * This allows you to see uncommitted writes from the current transaction.
+    *
+    * The query executes on the same connection as the transaction, so you can
+    * read data that hasn't been committed yet.
+    *
+    * @param token - Transaction token from executePausableTransaction
+    * @param query - SELECT query to execute
+    * @param bindValues - Optional parameter values
+    * @returns Promise that resolves with query results
+    *
+    * @example
+    * ```ts
+    * const token = await db.executePausableTransaction([
+    *    ['INSERT INTO users (name) VALUES ($1)', ['Alice']]
+    * ]);
+    *
+    * const users = await db.transactionRead<User[]>(
+    *    token,
+    *    'SELECT * FROM users WHERE name = $1',
+    *    ['Alice']
+    * );
+    *
+    * await db.transactionContinue(token, { type: 'Commit' });
+    * ```
+    */
+   async transactionRead<T>(
+      token: TransactionToken,
+      query: string,
+      bindValues?: SqlValue[]
+   ): Promise<T> {
+      return await invoke<T>('plugin:sqlite|transaction_read', {
+         token,
+         query,
+         values: bindValues ?? []
+      })
+   }
+
    /**
     * **getMigrationEvents**
     *