extralite 1.19 → 1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2fbd9028327105949e5f4fcc225ccb4ec89cdb2f324d949c17c4690f8b4653f
-  data.tar.gz: 226c07bfa8e8848dc322399ee386e8f15e6bd9e41c6912850709b1cc8fd24ad3
+  metadata.gz: 9b705a2d1c970cb3e73c784a6322ea92e8f7618531b4d8b9c2d4e036bf135b0f
+  data.tar.gz: fceaaf8976cac3d5e5328d64e8e76d07fe5979e4897ad7f20bb6295f697659b7
 SHA512:
-  metadata.gz: ca3c24e4be2cedee6d20101ce56018ed9f037cbe29d4e5c6fb63116a77c988390992b770586a1973acc0c42a521389369ed79cf1553464e5f775fe420c9bf421
-  data.tar.gz: f9ffb7dbe2a5d00ea2c15cca1407462897590f299acecf88de6a040f463f4f28715ae98ae34a6a0539f97b1cf2f12902803217517014661208b6238618013287
+  metadata.gz: c1b1bc996aa69b8f4abd4888a23a3aeae0aa15069b5d7c13027389e6165529186949ed8679571b55c00f3b76bd5360f396e874dd4c73f3d88cd8443c8931fca9
+  data.tar.gz: aca5d4470770f5c635d2d3b42a1897c45535efd29a38137c3164c07629f3f68a3cc1f74f95cef180efe06b9cb5423bb8fe95e183c7001c98a05baa0f3532718e

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,15 @@
+# 1.21 2023-01-23
+
+- Update bundled sqlite to version 3.40.1 (#18)
+
+# 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`

data/Gemfile.lock

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

data/README.md

@@ -55,6 +55,10 @@ latest features and enhancements.
 - 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
 

data/Rakefile

@@ -44,3 +44,8 @@ task :release do
   puts "Cleaning up..."
   `rm *.gem`
 end
+
+task :build_bundled do
+  puts 'Building extralite-bundle...'
+  `gem build extralite-bundle.gemspec`
+end

data/ext/extralite/common.c

@@ -243,6 +243,8 @@ 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:

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;
@@ -386,43 +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, "execute_multi", Database_execute_multi, 2);
-  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;
@@ -49,6 +50,12 @@ typedef struct {
   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);

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

@@ -283,27 +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, "execute_multi", PreparedStatement_execute_multi, 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);
 }