extralite 1.18 → 1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a40752d79cd5d28d8c9367c973f86b7e6a80d05e3878b5c70a6a98e0a70f3838
-  data.tar.gz: d72e040c85a2e34a07ea513fd7b28cc558a0b8c71a8b4f211b21aa3a9f492387
+  metadata.gz: f9dba60a33188d5c3c7cfb09c7c746f64bcd723d53a20da4b110037ca395a50b
+  data.tar.gz: 2b5d8de6e19fe38800fbd30b2465ef6788cf50ac73f79be7e07d8d1f2165ad8b
 SHA512:
-  metadata.gz: 4bc536fb4a5590fbae92abb1f99189f57812f5440addb49964908fcb6c45f1bfea575fc2421bfd4ddddcaaf7d00e9285ea3db4db9162afe4df71c27349dd1342
-  data.tar.gz: a1a158d144c3f97f3bd281ba050419d42c95566408cb168f35f3a0fe8d328705f662fbc1c9ac22e788a44f1120ff90db7e237e8ad1f2505b29a643c05589b331
+  metadata.gz: 4723dd3278f61a7dc95aa48260a5d974f3da7383463f538f3e0d647f1591f6759f239e633b6d3efe4e17d81c7841f0670c2847d318b1fdd78e7f1365fe509aad
+  data.tar.gz: 5fface9ad5152b0a11bb259267a1db2d6a214a02ca3a6ad0207f707e6de7aa674a28180fd6e109d55745bb3453d17b4e3244aaeba89bf75b40ec472dda1789bc

data/.github/workflows/test.yml

@@ -15,7 +15,7 @@ jobs:
 
     runs-on: ${{matrix.os}}
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v3
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{matrix.ruby}}

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+# 1.20 2023-01-21
+
+- Fix compilation error (#15 @sitano)
+- Add status methods `Extralite.runtime_status`, `Database#status`, `PreparedStatement#status` (#14 @sitano)
+- Add `Database#interrupt` (#13 @sitano)
+- Add `Database#backup` (#11 @sitano)
+- Derive `Extralite::Error` from `StandardError` (#10 @sitano)
+
+## 1.19 2022-12-01
+
+- Add `Database#execute_multi`
+- Add `PreparedStatement#execute_multi`
+
 ## 1.18 2022-12-01
 
 - Fix usage with system sqlite3 lib where `load_extension` is disabled

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    extralite (1.18)
+    extralite (1.20)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -51,9 +51,14 @@ latest features and enhancements.
   queries (handy for creating/modifying schemas).
 - Get last insert rowid.
 - Get number of rows changed by last query.
+- Execute the same query with multiple parameter lists (useful for inserting records).
 - Load extensions (loading of extensions is autmatically enabled. You can find
   some useful extensions here: https://github.com/nalgeon/sqlean.)
 - Includes a [Sequel adapter](#usage-with-sequel).
+- Other features:
+  - Backup databases
+  - Interrupt long-running queries (from another thread)
+  - Get runtime status, database status and prepared statement status values.
 
 ## Installation
 
@@ -123,6 +128,10 @@ db.query('select * from foo where bar = :bar', bar: 42)
 db.query('select * from foo where bar = :bar', 'bar' => 42)
 db.query('select * from foo where bar = :bar', ':bar' => 42)
 
+# insert multiple rows
+db.execute_multi('insert into foo values (?)', ['bar', 'baz'])
+db.execute_multi('insert into foo values (?, ?)', [[1, 2], [3, 4]])
+
 # prepared statements
 stmt = db.prepare('select ? as foo, ? as bar') #=> Extralite::PreparedStatement
 stmt.query(1, 2) #=> [{ :foo => 1, :bar => 2 }]

data/ext/extralite/common.c

@@ -81,6 +81,16 @@ void bind_all_parameters(sqlite3_stmt *stmt, int argc, VALUE *argv) {
   }
 }
 
+void bind_all_parameters_from_object(sqlite3_stmt *stmt, VALUE obj) {
+  if (TYPE(obj) == T_ARRAY) {
+    int count = RARRAY_LEN(obj);
+    for (int i = 0; i < count; i++)
+      bind_parameter_value(stmt, i + 1, RARRAY_AREF(obj, i));
+  }
+  else
+    bind_parameter_value(stmt, 1, obj);
+}
+
 static inline VALUE get_column_names(sqlite3_stmt *stmt, int column_count) {
   VALUE arr = rb_ary_new2(column_count);
   for (int i = 0; i < column_count; i++) {
@@ -223,7 +233,7 @@ void *stmt_iterate_without_gvl(void *ptr) {
   return NULL;
 }
 
-static inline int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db) {
+int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db) {
   struct step_ctx ctx = {stmt, 0};
   rb_thread_call_without_gvl(stmt_iterate_without_gvl, (void *)&ctx, RUBY_UBF_IO, 0);
   switch (ctx.rc) {
@@ -233,6 +243,8 @@ static inline int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db) {
       return 0;
     case SQLITE_BUSY:
       rb_raise(cBusyError, "Database is busy");
+    case SQLITE_INTERRUPT:
+      rb_raise(cInterruptError, "Query was interrupted");
     case SQLITE_ERROR:
       rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
     default:
@@ -262,7 +274,8 @@ VALUE safe_query_hash(query_ctx *ctx) {
 
   while (stmt_iterate(ctx->stmt, ctx->sqlite3_db)) {
     row = row_to_hash(ctx->stmt, column_count, column_names);
-    if (yield_to_block) rb_yield(row); else rb_ary_push(result, row);
+    if (yield_to_block) rb_yield(row);
+    else                rb_ary_push(result, row);
   }
 
   RB_GC_GUARD(column_names);
@@ -284,7 +297,8 @@ VALUE safe_query_ary(query_ctx *ctx) {
 
   while (stmt_iterate(ctx->stmt, ctx->sqlite3_db)) {
     row = row_to_ary(ctx->stmt, column_count);
-    if (yield_to_block) rb_yield(row); else rb_ary_push(result, row);
+    if (yield_to_block) rb_yield(row);
+    else                rb_ary_push(result, row);
   }
 
   RB_GC_GUARD(row);
@@ -346,6 +360,22 @@ VALUE safe_query_single_value(query_ctx *ctx) {
   return value;
 }
 
+VALUE safe_execute_multi(query_ctx *ctx) {
+  int count = RARRAY_LEN(ctx->params);
+  int changes = 0;
+
+  for (int i = 0; i < count; i++) {
+    sqlite3_reset(ctx->stmt);
+    sqlite3_clear_bindings(ctx->stmt);
+    bind_all_parameters_from_object(ctx->stmt, RARRAY_AREF(ctx->params, i));
+
+    while (stmt_iterate(ctx->stmt, ctx->sqlite3_db));
+    changes += sqlite3_changes(ctx->sqlite3_db);
+  }
+
+  return INT2FIX(changes);
+}
+
 VALUE safe_query_columns(query_ctx *ctx) {
   return get_column_names(ctx->stmt, sqlite3_column_count(ctx->stmt));
 }

data/ext/extralite/database.c

@@ -5,6 +5,7 @@ VALUE cDatabase;
 VALUE cError;
 VALUE cSQLError;
 VALUE cBusyError;
+VALUE cInterruptError;
 
 ID ID_KEYS;
 ID ID_NEW;
@@ -265,6 +266,34 @@ VALUE Database_query_single_value(int argc, VALUE *argv, VALUE self) {
   return Database_perform_query(argc, argv, self, safe_query_single_value);
 }
 
+/* call-seq:
+ *   db.execute_multi(sql, params_array) -> changes
+ *
+ * Executes the given query for each list of parameters in params_array. Returns
+ * the number of changes effected. This method is designed for inserting
+ * multiple records.
+ *
+ *     records = [
+ *       [1, 2, 3],
+ *       [4, 5, 6]
+ *     ]
+ *     db.execute_multi_query('insert into foo values (?, ?, ?)', records)
+ *
+ */
+VALUE Database_execute_multi(VALUE self, VALUE sql, VALUE params_array) {
+  Database_t *db;
+  sqlite3_stmt *stmt;
+
+  if (RSTRING_LEN(sql) == 0) return Qnil;
+
+  // prepare query ctx
+  GetOpenDatabase(self, db);
+  prepare_single_stmt(db->sqlite3_db, &stmt, sql);
+  query_ctx ctx = { self, db->sqlite3_db, stmt, params_array };
+
+  return rb_ensure(SAFE(safe_execute_multi), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
+}
+
 /* call-seq:
  *   db.columns(sql) -> columns
  *
@@ -358,42 +387,213 @@ VALUE Database_prepare(VALUE self, VALUE sql) {
   return rb_funcall(cPreparedStatement, ID_NEW, 2, self, sql);
 }
 
-void Init_ExtraliteDatabase() {
+/* call-seq:
+ *   db.interrupt -> db
+ *
+ * Interrupts a long running query. This method is to be called from a different
+ * thread than the one running the query. Upon calling `#interrupt` the running
+ * query will stop and raise an `Extralite::InterruptError` exception.
+ *
+ * It is not safe to call `#interrupt` on a database that is about to be closed.
+ * For more information, consult the [sqlite3 API docs](https://sqlite.org/c3ref/interrupt.html).
+ */
+VALUE Database_interrupt(VALUE self) {
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  sqlite3_interrupt(db->sqlite3_db);
+  return self;
+}
+
+typedef struct {
+  sqlite3 *dst;
+  int close_dst_on_cleanup;
+  sqlite3_backup *backup;
+  int block_given;
+  int rc;
+} backup_ctx;
+
+#define BACKUP_STEP_MAX_PAGES 16
+#define BACKUP_SLEEP_MS       100
+
+void *backup_step_without_gvl(void *ptr) {
+  backup_ctx *ctx = (backup_ctx *)ptr;
+  ctx->rc = sqlite3_backup_step(ctx->backup, BACKUP_STEP_MAX_PAGES);
+  return NULL;
+}
+
+void *backup_sleep_without_gvl(void *unused) {
+  sqlite3_sleep(BACKUP_SLEEP_MS);
+  return NULL;
+}
+
+VALUE backup_safe_iterate(VALUE ptr) {
+  backup_ctx *ctx = (backup_ctx *)ptr;
+  int done = 0;
+
+  while (!done) {
+    rb_thread_call_without_gvl(backup_step_without_gvl, (void *)ctx, RUBY_UBF_IO, 0);
+    switch(ctx->rc) {
+      case SQLITE_DONE:
+        if (ctx->block_given) {
+          VALUE total     = INT2FIX(sqlite3_backup_pagecount(ctx->backup));
+          rb_yield_values(2, total, total);
+        }
+        done = 1;
+        continue;
+      case SQLITE_OK:
+        if (ctx->block_given) {
+          VALUE remaining = INT2FIX(sqlite3_backup_remaining(ctx->backup));
+          VALUE total     = INT2FIX(sqlite3_backup_pagecount(ctx->backup));
+          rb_yield_values(2, remaining, total);
+        }
+        continue;
+      case SQLITE_BUSY:
+      case SQLITE_LOCKED:
+        rb_thread_call_without_gvl(backup_sleep_without_gvl, NULL, RUBY_UBF_IO, 0);
+        continue;
+      default:
+        rb_raise(cError, "%s", sqlite3_errstr(ctx->rc));
+    }
+  };
+
+  return Qnil;
+}
+
+VALUE backup_cleanup(VALUE ptr) {
+  backup_ctx *ctx = (backup_ctx *)ptr;
+
+  sqlite3_backup_finish(ctx->backup);
+
+  if (ctx->close_dst_on_cleanup)
+    sqlite3_close(ctx->dst);
+  return Qnil;
+}
+
+VALUE Database_backup(int argc, VALUE *argv, VALUE self) {
+  VALUE dst;
+  VALUE src_name;
+  VALUE dst_name;
+  rb_scan_args(argc, argv, "12", &dst, &src_name, &dst_name);
+  if (src_name == Qnil) src_name = rb_str_new_literal("main");
+  if (dst_name == Qnil) dst_name = rb_str_new_literal("main");
+
+  int dst_is_fn = TYPE(dst) == T_STRING;
+
+  Database_t *src;
+  GetOpenDatabase(self, src);
+  sqlite3 *dst_db;
+
+  if (dst_is_fn) {
+    int rc = sqlite3_open(StringValueCStr(dst), &dst_db);
+    if (rc) {
+      sqlite3_close(dst_db);
+      rb_raise(cError, "%s", sqlite3_errmsg(dst_db));
+    }
+  }
+  else {
+    Database_t *dst_struct;
+    GetOpenDatabase(dst, dst_struct);
+    dst_db = dst_struct->sqlite3_db;
+  }
+
+  // TODO: add possibility to use different src and dest db names (main, tmp, or
+  // attached db's).
+  sqlite3_backup *backup;
+  backup = sqlite3_backup_init(dst_db, StringValueCStr(dst_name), src->sqlite3_db, StringValueCStr(src_name));
+  if (!backup) {
+    if (dst_is_fn)
+      sqlite3_close(dst_db);
+    rb_raise(cError, "%s", sqlite3_errmsg(dst_db));
+  }
+
+  backup_ctx ctx = { dst_db, dst_is_fn, backup, rb_block_given_p(), 0 };
+  rb_ensure(SAFE(backup_safe_iterate), (VALUE)&ctx, SAFE(backup_cleanup), (VALUE)&ctx);
+
+  return self;
+}
+
+/*
+ * Extralite.runtime_status(op[, reset]) -> [value, highwatermark]
+ *
+ * Returns runtime status values for the given op as an array containing the
+ * current value and the high water mark value. To reset the high water mark,
+ * pass true as reset.
+ */
+VALUE Extralite_runtime_status(int argc, VALUE* argv, VALUE self) {
+  VALUE op, reset;
+  sqlite3_int64 cur, hwm;
+
+  rb_scan_args(argc, argv, "11", &op, &reset);
+
+  int rc = sqlite3_status64(NUM2INT(op), &cur, &hwm, RTEST(reset) ? 1 : 0);
+  if (rc != SQLITE_OK) rb_raise(cError, "%s", sqlite3_errstr(rc));
+
+  return rb_ary_new3(2, LONG2FIX(cur), LONG2FIX(hwm));
+}
+
+/* call-seq:
+ *   db.status(op[, reset]) -> [value, highwatermark]
+ *
+ * Returns database status values for the given op as an array containing the
+ * current value and the high water mark value. To reset the high water mark,
+ * pass true as reset.
+ */
+VALUE Database_status(int argc, VALUE* argv, VALUE self) {
+  VALUE op, reset;
+  int cur, hwm;
+
+  rb_scan_args(argc, argv, "11", &op, &reset);
+
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  int rc = sqlite3_db_status(db->sqlite3_db, NUM2INT(op), &cur, &hwm, RTEST(reset) ? 1 : 0);
+  if (rc != SQLITE_OK) rb_raise(cError, "%s", sqlite3_errstr(rc));
+
+  return rb_ary_new3(2, INT2NUM(cur), INT2NUM(hwm));
+}
+
+void Init_ExtraliteDatabase(void) {
   VALUE mExtralite = rb_define_module("Extralite");
+  rb_define_singleton_method(mExtralite, "runtime_status", Extralite_runtime_status, -1);
   rb_define_singleton_method(mExtralite, "sqlite3_version", Extralite_sqlite3_version, 0);
 
   cDatabase = rb_define_class_under(mExtralite, "Database", rb_cObject);
   rb_define_alloc_func(cDatabase, Database_allocate);
 
-  rb_define_method(cDatabase, "initialize", Database_initialize, 1);
+  rb_define_method(cDatabase, "backup", Database_backup, -1);
+  rb_define_method(cDatabase, "changes", Database_changes, 0);
   rb_define_method(cDatabase, "close", Database_close, 0);
   rb_define_method(cDatabase, "closed?", Database_closed_p, 0);
-
+  rb_define_method(cDatabase, "columns", Database_columns, 1);
+  rb_define_method(cDatabase, "execute_multi", Database_execute_multi, 2);
+  rb_define_method(cDatabase, "filename", Database_filename, -1);
+  rb_define_method(cDatabase, "initialize", Database_initialize, 1);
+  rb_define_method(cDatabase, "interrupt", Database_interrupt, 0);
+  rb_define_method(cDatabase, "last_insert_rowid", Database_last_insert_rowid, 0);
+  rb_define_method(cDatabase, "prepare", Database_prepare, 1);
   rb_define_method(cDatabase, "query", Database_query_hash, -1);
-  rb_define_method(cDatabase, "query_hash", Database_query_hash, -1);
   rb_define_method(cDatabase, "query_ary", Database_query_ary, -1);
-  rb_define_method(cDatabase, "query_single_row", Database_query_single_row, -1);
+  rb_define_method(cDatabase, "query_hash", Database_query_hash, -1);
   rb_define_method(cDatabase, "query_single_column", Database_query_single_column, -1);
+  rb_define_method(cDatabase, "query_single_row", Database_query_single_row, -1);
   rb_define_method(cDatabase, "query_single_value", Database_query_single_value, -1);
-  rb_define_method(cDatabase, "columns", Database_columns, 1);
-
-  rb_define_method(cDatabase, "last_insert_rowid", Database_last_insert_rowid, 0);
-  rb_define_method(cDatabase, "changes", Database_changes, 0);
-  rb_define_method(cDatabase, "filename", Database_filename, -1);
+  rb_define_method(cDatabase, "status", Database_status, -1);
   rb_define_method(cDatabase, "transaction_active?", Database_transaction_active_p, 0);
 
 #ifdef HAVE_SQLITE3_LOAD_EXTENSION
   rb_define_method(cDatabase, "load_extension", Database_load_extension, 1);
 #endif
 
-  rb_define_method(cDatabase, "prepare", Database_prepare, 1);
-
-  cError = rb_define_class_under(mExtralite, "Error", rb_eRuntimeError);
+  cError = rb_define_class_under(mExtralite, "Error", rb_eStandardError);
   cSQLError = rb_define_class_under(mExtralite, "SQLError", cError);
   cBusyError = rb_define_class_under(mExtralite, "BusyError", cError);
+  cInterruptError = rb_define_class_under(mExtralite, "InterruptError", cError);
   rb_gc_register_mark_object(cError);
   rb_gc_register_mark_object(cSQLError);
   rb_gc_register_mark_object(cBusyError);
+  rb_gc_register_mark_object(cInterruptError);
 
   ID_KEYS   = rb_intern("keys");
   ID_NEW    = rb_intern("new");

data/ext/extralite/extralite.h

@@ -25,6 +25,7 @@ extern VALUE cPreparedStatement;
 extern VALUE cError;
 extern VALUE cSQLError;
 extern VALUE cBusyError;
+extern VALUE cInterruptError;
 
 extern ID ID_KEYS;
 extern ID ID_NEW;
@@ -46,18 +47,28 @@ typedef struct {
   VALUE self;
   sqlite3 *sqlite3_db;
   sqlite3_stmt *stmt;
+  VALUE params;
 } query_ctx;
 
+typedef struct {
+  VALUE dst;
+  VALUE src;
+  sqlite3_backup *p;
+} backup_t;
+
 VALUE safe_query_ary(query_ctx *ctx);
 VALUE safe_query_hash(query_ctx *ctx);
 VALUE safe_query_single_column(query_ctx *ctx);
 VALUE safe_query_single_row(query_ctx *ctx);
 VALUE safe_query_single_value(query_ctx *ctx);
+VALUE safe_execute_multi(query_ctx *ctx);
 VALUE safe_query_columns(query_ctx *ctx);
 
 void prepare_single_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql);
 void prepare_multi_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql);
 void bind_all_parameters(sqlite3_stmt *stmt, int argc, VALUE *argv);
+void bind_all_parameters_from_object(sqlite3_stmt *stmt, VALUE obj);
+int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db);
 VALUE cleanup_stmt(query_ctx *ctx);
 
 sqlite3 *Database_sqlite3_db(VALUE self);

data/ext/extralite/extralite_ext.c

@@ -1,7 +1,7 @@
 void Init_ExtraliteDatabase();
 void Init_ExtralitePreparedStatement();
 
-void Init_extralite_ext() {
+void Init_extralite_ext(void) {
   Init_ExtraliteDatabase();
   Init_ExtralitePreparedStatement();
 }

data/ext/extralite/prepared_statement.c

@@ -197,6 +197,32 @@ VALUE PreparedStatement_query_single_value(int argc, VALUE *argv, VALUE self) {
   return PreparedStatement_perform_query(argc, argv, self, safe_query_single_value);
 }
 
+/* call-seq:
+ *   stmt.execute_multi(params_array) -> changes
+ *
+ * Executes the prepared statment for each list of parameters in params_array.
+ * Returns the number of changes effected. This method is designed for inserting
+ * multiple records.
+ *
+ *     stmt = db.prepare('insert into foo values (?, ?, ?)')
+ *     records = [
+ *       [1, 2, 3],
+ *       [4, 5, 6]
+ *     ]
+ *     stmt.execute_multi_query(records)
+ *
+ */
+VALUE PreparedStatement_execute_multi(VALUE self, VALUE params_array) {
+  PreparedStatement_t *stmt;
+  GetPreparedStatement(self, stmt);
+
+  if (!stmt->stmt)
+    rb_raise(cError, "Prepared statement is closed");
+
+  query_ctx ctx = { self, stmt->sqlite3_db, stmt->stmt, params_array };
+  return safe_execute_multi(&ctx);
+}
+
 /* call-seq:
  *   stmt.database -> database
  *   stmt.db -> database
@@ -257,26 +283,43 @@ VALUE PreparedStatement_closed_p(VALUE self) {
   return stmt->stmt ? Qfalse : Qtrue;
 }
 
-void Init_ExtralitePreparedStatement() {
+/* call-seq:
+ *   stmt.status(op[, reset]) -> value
+ *
+ * Returns the current status value for the given op. To reset the value, pass
+ * true as reset.
+ */
+VALUE PreparedStatement_status(int argc, VALUE* argv, VALUE self) {
+  VALUE op, reset;
+
+  rb_scan_args(argc, argv, "11", &op, &reset);
+
+  PreparedStatement_t *stmt;
+  GetPreparedStatement(self, stmt);
+
+  int value = sqlite3_stmt_status(stmt->stmt, NUM2INT(op), RTEST(reset) ? 1 : 0);
+  return INT2NUM(value);
+}
+
+void Init_ExtralitePreparedStatement(void) {
   VALUE mExtralite = rb_define_module("Extralite");
 
   cPreparedStatement = rb_define_class_under(mExtralite, "PreparedStatement", rb_cObject);
   rb_define_alloc_func(cPreparedStatement, PreparedStatement_allocate);
 
-  rb_define_method(cPreparedStatement, "initialize", PreparedStatement_initialize, 2);
+  rb_define_method(cPreparedStatement, "close", PreparedStatement_close, 0);
+  rb_define_method(cPreparedStatement, "closed?", PreparedStatement_closed_p, 0);
+  rb_define_method(cPreparedStatement, "columns", PreparedStatement_columns, 0);
   rb_define_method(cPreparedStatement, "database", PreparedStatement_database, 0);
   rb_define_method(cPreparedStatement, "db", PreparedStatement_database, 0);
-  rb_define_method(cPreparedStatement, "sql", PreparedStatement_sql, 0);
-
+  rb_define_method(cPreparedStatement, "execute_multi", PreparedStatement_execute_multi, 1);
+  rb_define_method(cPreparedStatement, "initialize", PreparedStatement_initialize, 2);
   rb_define_method(cPreparedStatement, "query", PreparedStatement_query_hash, -1);
   rb_define_method(cPreparedStatement, "query_hash", PreparedStatement_query_hash, -1);
   rb_define_method(cPreparedStatement, "query_ary", PreparedStatement_query_ary, -1);
   rb_define_method(cPreparedStatement, "query_single_row", PreparedStatement_query_single_row, -1);
   rb_define_method(cPreparedStatement, "query_single_column", PreparedStatement_query_single_column, -1);
   rb_define_method(cPreparedStatement, "query_single_value", PreparedStatement_query_single_value, -1);
-
-  rb_define_method(cPreparedStatement, "columns", PreparedStatement_columns, 0);
-
-  rb_define_method(cPreparedStatement, "close", PreparedStatement_close, 0);
-  rb_define_method(cPreparedStatement, "closed?", PreparedStatement_closed_p, 0);
+  rb_define_method(cPreparedStatement, "sql", PreparedStatement_sql, 0);
+  rb_define_method(cPreparedStatement, "status", PreparedStatement_status, -1);
 }

data/lib/extralite/version.rb

@@ -1,3 +1,3 @@
 module Extralite
-  VERSION = '1.18'
+  VERSION = '1.20'
 end

data/lib/extralite.rb

@@ -2,8 +2,48 @@ require_relative './extralite_ext'
 
 # Extralite is a Ruby gem for working with SQLite databases
 module Extralite
+  
+  SQLITE_STATUS_MEMORY_USED           =  0
+  SQLITE_STATUS_PAGECACHE_USED        =  1
+  SQLITE_STATUS_PAGECACHE_OVERFLOW    =  2
+  SQLITE_STATUS_SCRATCH_USED          =  3 # NOT USED
+  SQLITE_STATUS_SCRATCH_OVERFLOW      =  4 # NOT USED
+  SQLITE_STATUS_MALLOC_SIZE           =  5
+  SQLITE_STATUS_PARSER_STACK          =  6
+  SQLITE_STATUS_PAGECACHE_SIZE        =  7
+  SQLITE_STATUS_SCRATCH_SIZE          =  8 # NOT USED
+  SQLITE_STATUS_MALLOC_COUNT          =  9
+
+  SQLITE_DBSTATUS_LOOKASIDE_USED      =  0
+  SQLITE_DBSTATUS_CACHE_USED          =  1
+  SQLITE_DBSTATUS_SCHEMA_USED         =  2
+  SQLITE_DBSTATUS_STMT_USED           =  3
+  SQLITE_DBSTATUS_LOOKASIDE_HIT       =  4
+  SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE =  5
+  SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL =  6
+  SQLITE_DBSTATUS_CACHE_HIT           =  7
+  SQLITE_DBSTATUS_CACHE_MISS          =  8
+  SQLITE_DBSTATUS_CACHE_WRITE         =  9
+  SQLITE_DBSTATUS_DEFERRED_FKS        = 10
+  SQLITE_DBSTATUS_CACHE_USED_SHARED   = 11
+  SQLITE_DBSTATUS_CACHE_SPILL         = 12
+
+  SQLITE_STMTSTATUS_FULLSCAN_STEP     =  1
+  SQLITE_STMTSTATUS_SORT              =  2
+  SQLITE_STMTSTATUS_AUTOINDEX         =  3
+  SQLITE_STMTSTATUS_VM_STEP           =  4
+  SQLITE_STMTSTATUS_REPREPARE         =  5
+  SQLITE_STMTSTATUS_RUN               =  6
+  SQLITE_STMTSTATUS_FILTER_MISS       =  7
+  SQLITE_STMTSTATUS_FILTER_HIT        =  8
+  SQLITE_STMTSTATUS_MEMUSED           = 99
+
+  # The following class definitions are not really needed, as they're already
+  # defined in the C extension. We put them here for the sake of generating
+  # docs.
+
   # A base class for Extralite exceptions
-  class Error < RuntimeError
+  class Error < ::StandardError
   end
 
   # An exception representing an SQL error emitted by SQLite
@@ -15,6 +55,11 @@ module Extralite
   class BusyError < Error
   end
 
+  # An exception raised when a query is interrupted by calling
+  # `Database#interrupt` from another thread
+  class InterruptError < Error
+  end
+
   # An SQLite database
   class Database
     alias_method :execute, :query
@@ -42,4 +87,18 @@ module Extralite
       query("pragma #{key}")
     end
   end
+
+  # An SQLite backup
+  class Backup
+    # def initialize(dst, dst_name, src, src_name); end
+
+    # def dst; end
+    # def src; end
+
+    # def step(pages); end
+    # def finish; end
+
+    # def pagecount; end
+    # def remaining; end
+  end
 end

data/test/test_database.rb

@@ -207,6 +207,68 @@ end
     assert_equal [{schema_version: 33}], @db.pragma(:schema_version)
     assert_equal [{recursive_triggers: 1}], @db.pragma(:recursive_triggers)
   end
+
+  def test_execute_multi
+    @db.query('create table foo (a, b, c)')
+    assert_equal [], @db.query('select * from foo')
+
+    records = [
+      [1, '2', 3],
+      ['4', 5, 6]
+    ]
+
+    changes = @db.execute_multi('insert into foo values (?, ?, ?)', records)
+
+    assert_equal 2, changes
+    assert_equal [
+      { a: 1, b: '2', c: 3 },
+      { a: '4', b: 5, c: 6 }
+    ], @db.query('select * from foo')
+  end
+
+  def test_execute_multi_single_values
+    @db.query('create table foo (bar)')
+    assert_equal [], @db.query('select * from foo')
+
+    records = [
+      'hi',
+      'bye'
+    ]
+
+    changes = @db.execute_multi('insert into foo values (?)', records)
+
+    assert_equal 2, changes
+    assert_equal [
+      { bar: 'hi' },
+      { bar: 'bye' }
+    ], @db.query('select * from foo')
+  end
+
+  def test_interrupt
+    t = Thread.new do
+      sleep 0.5
+      @db.interrupt
+    end
+
+    n = 2**31
+    assert_raises(Extralite::InterruptError) {
+      @db.query <<-SQL
+        WITH RECURSIVE
+          fibo (curr, next)
+        AS
+        ( SELECT 1,1
+          UNION ALL
+          SELECT next, curr+next FROM fibo
+          LIMIT #{n} )
+        SELECT curr, next FROM fibo LIMIT 1 OFFSET #{n}-1;
+      SQL
+    }
+    t.join
+  end
+
+  def test_database_status
+    assert_operator 0, :<, @db.status(Extralite::SQLITE_DBSTATUS_SCHEMA_USED).first
+  end
 end
 
 class ScenarioTest < MiniTest::Test
@@ -275,3 +337,39 @@ class ScenarioTest < MiniTest::Test
     assert_equal [1, 4, 7], result
   end
 end
+
+class BackupTest < MiniTest::Test
+  def setup
+    @src = Extralite::Database.new(':memory:')
+    @dst = Extralite::Database.new(':memory:')
+
+    @src.query('create table t (x,y,z)')
+    @src.query('insert into t values (1, 2, 3)')
+    @src.query('insert into t values (4, 5, 6)')
+  end
+
+  def test_backup
+    @src.backup(@dst)
+    assert_equal [[1, 2, 3], [4, 5, 6]], @dst.query_ary('select * from t')
+  end
+
+  def test_backup_with_block
+    progress = []
+    @src.backup(@dst) { |r, t| progress << [r, t] }
+    assert_equal [[1, 2, 3], [4, 5, 6]], @dst.query_ary('select * from t')
+    assert_equal [[2, 2]], progress
+  end
+
+  def test_backup_with_schema_names
+    @src.backup(@dst, 'main', 'temp')
+    assert_equal [[1, 2, 3], [4, 5, 6]], @dst.query_ary('select * from temp.t')
+  end
+
+  def test_backup_with_fn
+    tmp_fn = "/tmp/#{rand(86400)}.db"
+    @src.backup(tmp_fn)
+
+    db = Extralite::Database.new(tmp_fn)
+    assert_equal [[1, 2, 3], [4, 5, 6]], db.query_ary('select * from t')
+  end
+end

data/test/test_extralite.rb

@@ -6,4 +6,28 @@ class ExtraliteTest < MiniTest::Test
   def test_sqlite3_version
     assert_match /^3\.\d+\.\d+$/, Extralite.sqlite3_version
   end
+
+  def test_status
+    db = Extralite::Database.new(':memory:')
+    db.query('create table if not exists t (x,y,z)')
+    db.query('insert into t values (1, 2, 3)')
+
+    begin
+      a = Extralite::runtime_status(Extralite::SQLITE_STATUS_MEMORY_USED, false)
+      b = Extralite::runtime_status(Extralite::SQLITE_STATUS_MEMORY_USED)
+      c = Extralite::runtime_status(Extralite::SQLITE_STATUS_MEMORY_USED, true)
+      d = Extralite::runtime_status(Extralite::SQLITE_STATUS_MEMORY_USED, true)
+
+      assert_operator 0, :<, a[0]
+      assert_operator a[0], :<=, a[1]
+      
+      assert_equal a, b
+      assert_equal a, c
+
+      assert_equal a[0], d[0]
+      assert_equal a[0], d[1]
+    ensure
+      db.close
+    end
+  end
 end

data/test/test_prepared_statement.rb

@@ -181,4 +181,34 @@ end
 
     assert_raises { p.query_single_value }
   end
+
+  def test_prepared_statement_execute_multi
+    @db.query('create table foo (a, b, c)')
+    assert_equal [], @db.query('select * from foo')
+
+    records = [
+      [1, '2', 3],
+      ['4', 5, 6]
+    ]
+
+    p = @db.prepare('insert into foo values (?, ?, ?)')
+    changes = p.execute_multi(records)
+
+    assert_equal 2, changes
+    assert_equal [
+      { a: 1, b: '2', c: 3 },
+      { a: '4', b: 5, c: 6 }
+    ], @db.query('select * from foo')
+  end  
+
+  def test_prepared_statement_status
+    assert_equal 0, @stmt.status(Extralite::SQLITE_STMTSTATUS_RUN)
+    @stmt.query
+    assert_equal 1, @stmt.status(Extralite::SQLITE_STMTSTATUS_RUN)
+    @stmt.query
+    assert_equal 2, @stmt.status(Extralite::SQLITE_STMTSTATUS_RUN)
+    @stmt.query
+    assert_equal 3, @stmt.status(Extralite::SQLITE_STMTSTATUS_RUN, true)
+    assert_equal 0, @stmt.status(Extralite::SQLITE_STMTSTATUS_RUN)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: extralite
 version: !ruby/object:Gem::Version
-  version: '1.18'
+  version: '1.20'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-01 00:00:00.000000000 Z
+date: 2023-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -153,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.1
 signing_key: 
 specification_version: 4
 summary: Extra-lightweight SQLite3 wrapper for Ruby