Merge pull request #29 from pmorris-dev/use_transactions_api_from_rust

Support the transaction API from Rust

Author: jjhafer

README.md

@@ -140,7 +140,7 @@ const db = await Database.load('mydb.db')
 // Get all migration events (including ones emitted before listener could be registered)
 const events = await db.getMigrationEvents()
 for (const event of events) {
-   console.log(`${event.status}: ${event.dbPath}`)
+   console.info(`${event.status}: ${event.dbPath}`)
    if (event.status === 'failed') {
       console.error(`Migration error: ${event.error}`)
    }
@@ -156,7 +156,7 @@ import type { MigrationEvent } from '@silvermine/tauri-plugin-sqlite'
 
 await listen<MigrationEvent>('sqlite:migration', (event) => {
    const { dbPath, status, migrationCount, error } = event.payload
-   // status: 'running' | 'completed' | 'failed'
+   console.info(`Migration ${status} for ${dbPath}: ${migrationCount} migrations`, error)
 })
 ```
 
@@ -166,16 +166,16 @@ await listen<MigrationEvent>('sqlite:migration', (event) => {
 import Database from '@silvermine/tauri-plugin-sqlite'
 
 // Path is relative to app config directory (no sqlite: prefix needed)
-const db = await Database.load('mydb.db')
+let db = await Database.load('mydb.db')
 
 // With custom configuration
-const db = await Database.load('mydb.db', {
+db = await Database.load('mydb.db', {
    maxReadConnections: 10, // default: 6
    idleTimeoutSecs: 60     // default: 30
 })
 
 // Lazy initialization (connects on first query)
-const db = Database.get('mydb.db')
+db = Database.get('mydb.db')
 ```
 
 ### Parameter Binding
@@ -211,7 +211,7 @@ const result = await db.execute(
    'INSERT INTO users (name, email) VALUES ($1, $2)',
    ['Alice', 'alice@example.com']
 )
-console.log(result.rowsAffected, result.lastInsertId)
+console.info(`Inserted ${result.rowsAffected} row(s), ID: ${result.lastInsertId}`)
 ```
 
 ### Read Operations
@@ -224,12 +224,16 @@ const users = await db.fetchAll<User[]>(
    'SELECT * FROM users WHERE email LIKE $1',
    ['%@example.com']
 )
+console.info(`Found ${users.length} users`)
 
 // Single row (returns undefined if not found, throws if multiple rows)
 const user = await db.fetchOne<User>(
    'SELECT * FROM users WHERE id = $1',
    [42]
 )
+if (user) {
+   console.info(`Found user: ${user.name}`)
+}
 ```
 
 ### Transactions
@@ -242,6 +246,7 @@ const results = await db.executeTransaction([
    ['UPDATE accounts SET balance = balance + $1 WHERE id = $2', [100, 2]],
    ['INSERT INTO transfers (from_id, to_id, amount) VALUES ($1, $2, $3)', [1, 2, 100]]
 ])
+console.info(`Transaction completed: ${results.length} statements executed`)
 ```
 
 Transactions use `BEGIN IMMEDIATE`, commit on success, and rollback on any failure.
@@ -253,8 +258,13 @@ 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
+// Assuming userId, productId, itemTotal are defined in your application context
+const userId = 123
+const productId = 456
+const itemTotal = 99.99
+
 // Begin transaction with initial insert
-let tx = await db.executeInterruptibleTransaction([
+let tx = await db.beginInterruptibleTransaction([
    ['INSERT INTO orders (user_id, total) VALUES ($1, $2)', [userId, 0]]
 ])
 
@@ -266,7 +276,7 @@ const orders = await tx.read<Array<{ id: number }>>(
 const orderId = orders[0].id
 
 // Continue transaction with the order ID
-tx = await tx.continue([
+tx = await tx.continueWith([
    ['INSERT INTO order_items (order_id, product_id) VALUES ($1, $2)', [orderId, productId]],
    ['UPDATE orders SET total = $1 WHERE id = $2', [itemTotal, orderId]]
 ])
@@ -311,6 +321,7 @@ const results = await db.fetchAll(
       mode: 'readOnly'
    }
 ])
+console.info(`Found ${results.length} results from cross-database query`)
 
 // Update main database using data from attached database
 await db.execute(
@@ -325,6 +336,10 @@ await db.execute(
 ])
 
 // Atomic writes across multiple databases
+// Assuming userId and total are defined in your application context
+const userId = 123
+const total = 99.99
+
 await db.executeTransaction([
    ['INSERT INTO main.orders (user_id, total) VALUES ($1, $2)', [userId, total]],
    ['UPDATE stats.order_count SET count = count + 1', []]
@@ -397,7 +412,7 @@ await db.remove()           // Close and DELETE database file(s) - irreversible!
 | ------ | ----------- |
 | `execute(query, values?)` | Execute write query, returns `{ rowsAffected, lastInsertId }` |
 | `executeTransaction(statements)` | Execute statements atomically (use for batch writes) |
-| `executeInterruptibleTransaction(statements)` | Begin interruptible transaction, returns `InterruptibleTransaction` |
+| `beginInterruptibleTransaction(statements)` | Begin interruptible transaction, returns `InterruptibleTransaction` |
 | `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 |
@@ -418,7 +433,7 @@ return builders that are directly awaitable and support method chaining:
 | Method | Description |
 | ------ | ----------- |
 | `read<T>(query, values?)` | Read uncommitted data within this transaction |
-| `continue(statements)` | Execute additional statements, returns new `InterruptibleTransaction` |
+| `continueWith(statements)` | Execute additional statements, returns new `InterruptibleTransaction` |
 | `commit()` | Commit transaction and release write lock |
 | `rollback()` | Rollback transaction and release write lock |
 
@@ -447,6 +462,182 @@ interface SqliteError {
 }
 ```
 
+## Rust-Only API
+
+For Rust code that needs direct database access without going through Tauri commands,
+use `DatabaseWrapper`.
+
+### Setup (Rust)
+
+```rust
+use tauri_plugin_sqlite::DatabaseWrapper;
+use std::path::PathBuf;
+
+// Load a database
+let mut db = DatabaseWrapper::load(PathBuf::from("/path/to/mydb.db"), None).await?;
+
+// With custom configuration
+use tauri_plugin_sqlite::CustomConfig;
+let config = CustomConfig {
+    max_read_connections: Some(10),
+    idle_timeout_secs: Some(60),
+};
+db = DatabaseWrapper::load(PathBuf::from("/path/to/mydb.db"), Some(config)).await?;
+```
+
+### Basic Operations
+
+```rust
+use serde_json::json;
+
+// Write operations
+let result = db.execute(
+    "INSERT INTO users (name, email) VALUES (?, ?)".into(),
+    vec![json!("Alice"), json!("alice@example.com")]
+).await?;
+
+println!("Inserted row {}", result.last_insert_id);
+
+// Read multiple rows
+let users = db.fetch_all(
+    "SELECT * FROM users WHERE active = ?".into(),
+    vec![json!(true)]
+).await?;
+
+println!("Found {} users", users.len());
+
+// Read single row
+let user = db.fetch_one(
+    "SELECT * FROM users WHERE id = ?".into(),
+    vec![json!(42)]
+).await?;
+
+if let Some(user_data) = user {
+    println!("Found user: {:?}", user_data);
+}
+```
+
+### Simple Transactions
+
+Use `execute_transaction()` for atomic execution of multiple statements:
+
+```rust
+let results = db.execute_transaction(vec![
+    ("UPDATE accounts SET balance = balance - ? WHERE id = ?", vec![json!(100), json!(1)]),
+    ("UPDATE accounts SET balance = balance + ? WHERE id = ?", vec![json!(100), json!(2)]),
+    ("INSERT INTO transfers (from_id, to_id, amount) VALUES (?, ?, ?)", vec![json!(1), json!(2), json!(100)]),
+]).await?;
+
+println!("Transaction completed: {} statements executed", results.len());
+
+// Returns Vec<WriteQueryResult> on success, rolls back on any failure
+```
+
+### Interruptible Transactions (Rust)
+
+For transactions that need to read data mid-transaction:
+
+```rust
+// Assuming user_id, product_id, item_total are defined in your application context
+let user_id = 123;
+let product_id = 456;
+let item_total = 99.99;
+
+// Begin transaction with initial statements
+let mut tx = db.begin_interruptible_transaction()
+    .execute(vec![
+        ("INSERT INTO orders (user_id, total) VALUES (?, ?)", vec![json!(user_id), json!(0)]),
+    ])
+    .await?;
+
+// Read uncommitted data
+let orders = tx.read(
+    "SELECT id FROM orders WHERE user_id = ? ORDER BY id DESC LIMIT 1".into(),
+    vec![json!(user_id)]
+).await?;
+
+let order_id = orders[0].get("id").unwrap().as_i64().unwrap();
+
+// Continue with more statements
+tx.continue_with(vec![
+    ("INSERT INTO order_items (order_id, product_id) VALUES (?, ?)", vec![json!(order_id), json!(product_id)]),
+    ("UPDATE orders SET total = ? WHERE id = ?", vec![json!(item_total), json!(order_id)]),
+]).await?;
+
+// Commit (or rollback)
+tx.commit().await?;
+// tx.rollback().await?;  // Alternative: rollback changes
+```
+
+### Cross-Database Operations
+
+Attach other databases for cross-database queries:
+
+```rust
+use tauri_plugin_sqlite::AttachedDatabaseSpec;
+
+// Simple transaction with attached database
+let results = db.execute_transaction(vec![
+    ("INSERT INTO main.orders (user_id) VALUES (?)", vec![json!(1)]),
+    ("UPDATE stats.order_count SET count = count + 1", vec![]),
+])
+.attach(vec![AttachedDatabaseSpec {
+    database_path: "stats.db".into(),
+    schema_name: "stats".into(),
+    mode: tauri_plugin_sqlite::AttachedDatabaseMode::ReadWrite,
+}])
+.await?;
+
+println!("Cross-database transaction completed: {} statements", results.len());
+
+// Interruptible transaction with attached database
+// Assuming product_id is defined in your application context
+let product_id = 789;
+
+let _tx = db.begin_interruptible_transaction()
+    .attach(vec![AttachedDatabaseSpec {
+        database_path: "inventory.db".into(),
+        schema_name: "inv".into(),
+        mode: tauri_plugin_sqlite::AttachedDatabaseMode::ReadWrite,
+    }])
+    .execute(vec![
+        ("UPDATE inv.stock SET quantity = quantity - ? WHERE product_id = ?", vec![json!(1), json!(product_id)]),
+    ])
+    .await?;
+// Continue with transaction operations...
+```
+
+### Cleanup
+
+```rust
+db.close().await?;   // Close connection
+db.remove().await?;  // Close and DELETE database file(s)
+```
+
+### Rust API Reference
+
+#### DatabaseWrapper Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `load(path, config?)` | Load database, returns `DatabaseWrapper` |
+| `execute(query, values)` | Execute write query |
+| `execute_transaction(statements)` | Execute statements atomically (builder) |
+| `begin_interruptible_transaction()` | Begin interruptible transaction (builder) |
+| `fetch_all(query, values)` | Fetch all rows |
+| `fetch_one(query, values)` | Fetch single row |
+| `close()` | Close connection |
+| `remove()` | Close and delete database file(s) |
+
+#### InterruptibleTransaction Methods (Rust)
+
+| Method | Description |
+| ------ | ----------- |
+| `read(query, values)` | Read uncommitted data within transaction |
+| `continue_with(statements)` | Execute additional statements |
+| `commit()` | Commit and release write lock |
+| `rollback()` | Rollback and release write lock |
+
 ## Tracing and Logging
 
 The plugin uses [`tracing`](https://crates.io/crates/tracing) with
@@ -476,7 +667,7 @@ fn init_tracing() {}
 fn main() {
     init_tracing();
     tauri::Builder::default()
-        .plugin(tauri_plugin_sqlite::init())
+        .plugin(tauri_plugin_sqlite::Builder::new().build())
         .run(tauri::generate_context!())
         .expect("error while running tauri application");
 }