bindings/rust: test methods on rusqlite::Transaction

Author: mlin

bindings/rust/src/lib.rs

@@ -170,6 +170,8 @@ pub struct RefSeq {
 }
 
 /// Methods for GenomicSQLite [rusqlite::Connection]s; see [Programming Guide](https://mlin.github.io/GenomicSQLite/guide/#tuning-options)
+/// for each method's semantics. The methods can also be invoked on an open
+/// [rusqlite::Transaction], via its implicit `Deref<Target=Connection>`.
 pub trait ConnectionMethods {
     /// Get Genomics Extension version
     fn genomicsqlite_version(&self) -> String;
@@ -415,7 +417,7 @@ mod tests {
         );
         let mut config = json::object::Object::new();
         config.insert("threads", json::JsonValue::from(3));
-        let conn = super::open(
+        let mut conn = super::open(
             dbfn,
             OpenFlags::SQLITE_OPEN_CREATE | OpenFlags::SQLITE_OPEN_READ_WRITE,
             &config,
@@ -428,18 +430,25 @@ mod tests {
             .unwrap();
         assert_eq!(ans, 3);
 
-        // load table & create GRI
-        conn.execute_batch(
-            "CREATE TABLE feature(rid INTEGER, beg INTEGER, end INTEGER);
-             INSERT INTO feature VALUES(3, 12, 34);
-             INSERT INTO feature VALUES(3, 0, 23);
-             INSERT INTO feature VALUES(3, 34, 56)",
-        )
-        .unwrap();
-        let gri_sql = conn
-            .create_genomic_range_index_sql("feature", "rid", "beg", "end")
+        // begin transaction
+        {
+            let txn = conn.transaction().unwrap();
+
+            // load table & create GRI
+            txn.execute_batch(
+                "CREATE TABLE feature(rid INTEGER, beg INTEGER, end INTEGER);
+                INSERT INTO feature VALUES(3, 12, 34);
+                INSERT INTO feature VALUES(3, 0, 23);
+                INSERT INTO feature VALUES(3, 34, 56)",
+            )
             .unwrap();
-        conn.execute_batch(&gri_sql).unwrap();
+            let gri_sql = txn
+                .create_genomic_range_index_sql("feature", "rid", "beg", "end")
+                .unwrap();
+            txn.execute_batch(&gri_sql).unwrap();
+
+            txn.commit().unwrap();
+        }
 
         // GRI query
         ans = conn

docs/guide.md

@@ -28,33 +28,35 @@ The Genomics Extension integrates with your programming language's existing SQLi
     use rusqlite::{Connection, OpenFlags, params, NO_PARAMS};
     ```
 
+    The `genomicsqlite::ConnectionMethods` trait makes available GenomicSQLite-specific methods for
+    `rusqlite::Connection` (and `rusqlite::Transaction`). See [rustdoc](https://docs.rs/genomicsqlite)
+    for some extra details.
+
 === "C++"
     ``` c++
-    // link program to sqlite3 and genomicsqlite libraries; optionally, SQLiteCpp:
-    //     https://github.com/SRombauts/SQLiteCpp
     #include <sqlite3.h>
     #include "SQLiteCpp/SQLiteCpp.h" // optional 
     #include "genomicsqlite.h"
-
-    // General note: most GenomicSQLite C++ routines are liable to throw.
     ```
 
+    Link the program to `sqlite3` and `genomicsqlite` libraries; optionally,
+    [SQLiteCpp](https://github.com/SRombauts/SQLiteCpp).
+
+    General note: GenomicSQLite C++ routines are liable to throw exceptions.
+
 === "C"
     ``` c
-    /* link program to sqlite3 and genomicsqlite libraries */
     #include <sqlite3.h>
     #include "genomicsqlite.h"
-
-    /* General note: all GenomicSQLite C routines returning a char* string use
-     * the following convention:
-     * If the operation suceeds then it's a nonempty, null-terminated string.
-     * Otherwise it points to a null byte followed immediately by a nonempty,
-     * null-terminated error message.
-     * IN EITHER CASE, the caller should free the string with sqlite3_free().
-     * Null is returned only if malloc failed.
-     */
     ```
 
+    Link the program to `sqlite3` and `genomicsqlite` libraries.
+
+    All GenomicSQLite C routines returning a `char*` string use the following convention. If the
+    operation succeeds, then it's a nonempty, null-terminated string. Otherwise, it points to a
+    null byte followed immediately by a nonempty, null-terminated error message. *In either case,*
+    the caller must free the string with `sqlite3_free()`. NULL is returned only if out of memory.
+
 ## Opening a compressed database
 
 **↪ GenomicSQLite Open:** create or open a compressed database, returning a connection object with various settings pre-tuned for large datasets.

docs/index.md

@@ -75,7 +75,7 @@ It's usually easiest to obtain the extension as a pre-compiled shared library (L
     version = "^0"
     ```
 
-    The crate will build a bundled shared library file appropriate for your platform into your compilation unit. To disable this, add `default-features = false` and at runtime, set environment variable `LIBGENOMICSQLITE` to a filename or place the library file somewhere it'll be found by `dlopen("libgenomicsqlite")`.
+    Building with the crate will include a platform-appropriate shared library file within your compilation unit, to be extracted & loaded at runtime. To disable this, add `default-features = false` and at runtime, set environment variable `LIBGENOMICSQLITE` to a filename or place the library file somewhere it'll be found by `dlopen("libgenomicsqlite")`.
 
 === "C/C++"
     Download zip of shared library and `genomicsqlite.h` from [GitHub Releases](https://github.com/mlin/GenomicSQLite/releases). Build your program with them, and also ensure the dynamic linker will find the shared library at runtime, by either: (1) installing it in a system or user lib directory & refreshing cache, (2) setting `LD_LIBRARY_PATH` environment variable, (3) building with `-rpath`.