extralite 1.4 → 1.8.1

data/ext/extralite/extralite.c

@@ -1,11 +1,15 @@
 #include <stdio.h>
 #include "ruby.h"
+#include "ruby/thread.h"
 #include <sqlite3.h>
 
 VALUE cError;
 VALUE cSQLError;
 VALUE cBusyError;
+
+ID ID_KEYS;
 ID ID_STRIP;
+ID ID_TO_S;
 
 typedef struct Database_t {
   sqlite3 *sqlite3_db;
@@ -47,6 +51,10 @@ static VALUE Database_allocate(VALUE klass) {
   } \
 }
 
+/* call-seq: initialize(path)
+ *
+ * Initializes a new SQLite database with the given path.
+ */
 
 VALUE Database_initialize(VALUE self, VALUE path) {
   int rc;
@@ -68,6 +76,10 @@ VALUE Database_initialize(VALUE self, VALUE path) {
   return Qnil;
 }
 
+/* call-seq: close
+ *
+ * Closes the database.
+ */
 VALUE Database_close(VALUE self) {
   int rc;
   Database_t *db;
@@ -82,6 +94,10 @@ VALUE Database_close(VALUE self) {
   return self;
 }
 
+/* call-seq: closed?
+ *
+ * Returns true if the database is closed.
+ */
 VALUE Database_closed_p(VALUE self) {
   Database_t *db;
   GetDatabase(self, db);
@@ -108,8 +124,35 @@ inline VALUE get_column_value(sqlite3_stmt *stmt, int col, int type) {
   return Qnil;
 }
 
+static void bind_parameter_value(sqlite3_stmt *stmt, int pos, VALUE value);
+
+static inline void bind_hash_parameter_values(sqlite3_stmt *stmt, VALUE hash) {
+  VALUE keys = rb_funcall(hash, ID_KEYS, 0);
+  int len = RARRAY_LEN(keys);
+  for (int i = 0; i < len; i++) {
+    VALUE k = RARRAY_AREF(keys, i);
+    VALUE v = rb_hash_aref(hash, k);
+
+    switch (TYPE(k)) {
+      case T_FIXNUM:
+        bind_parameter_value(stmt, NUM2INT(k), v);
+        return;
+      case T_SYMBOL:
+        k = rb_funcall(k, ID_TO_S, 0);
+      case T_STRING:
+        if(RSTRING_PTR(k)[0] != ':') k = rb_str_plus(rb_str_new2(":"), k);
+        int pos = sqlite3_bind_parameter_index(stmt, StringValuePtr(k));
+        bind_parameter_value(stmt, pos, v);
+        return;
+      default:
+      rb_raise(cError, "Cannot bind hash key value idx %d", i);
+    }
+  }
+  RB_GC_GUARD(keys);
+}
+
 static inline void bind_parameter_value(sqlite3_stmt *stmt, int pos, VALUE value) {
-  switch (TYPE(value)) { 
+  switch (TYPE(value)) {
     case T_NIL:
       sqlite3_bind_null(stmt, pos);
       return;
@@ -128,6 +171,9 @@ static inline void bind_parameter_value(sqlite3_stmt *stmt, int pos, VALUE value
     case T_STRING:
       sqlite3_bind_text(stmt, pos, RSTRING_PTR(value), RSTRING_LEN(value), SQLITE_TRANSIENT);
       return;
+    case T_HASH:
+      bind_hash_parameter_values(stmt, value);
+      return;
     default:
       rb_raise(cError, "Cannot bind parameter at position %d", pos);
   }
@@ -143,7 +189,7 @@ static inline void bind_all_parameters(sqlite3_stmt *stmt, int argc, VALUE *argv
 
 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++) { 
+  for (int i = 0; i < column_count; i++) {
     VALUE name = ID2SYM(rb_intern(sqlite3_column_name(stmt, i)));
     rb_ary_push(arr, name);
   }
@@ -168,36 +214,80 @@ static inline VALUE row_to_ary(sqlite3_stmt *stmt, int column_count) {
   return row;
 }
 
-inline void prepare_multi_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
-  const char *rest = 0;
-  const char *ptr = RSTRING_PTR(sql);
-  const char *end = ptr + RSTRING_LEN(sql);
+struct multi_stmt_ctx {
+  sqlite3 *db;
+  sqlite3_stmt **stmt;
+  const char *str;
+  int len;
+  int rc;
+};
+
+void *prepare_multi_stmt_without_gvl(void *ptr) {
+  struct multi_stmt_ctx *ctx = (struct multi_stmt_ctx *)ptr;
+  const char *rest = NULL;
+  const char *str = ctx->str;
+  const char *end = ctx->str + ctx->len;
   while (1) {
-    int rc = sqlite3_prepare(db, ptr, end - ptr, stmt, &rest);
-    if (rc) {
-      sqlite3_finalize(*stmt);
-      rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
+    ctx->rc = sqlite3_prepare_v2(ctx->db, str, end - str, ctx->stmt, &rest);
+    if (ctx->rc) {
+      sqlite3_finalize(*ctx->stmt);
+      return NULL;
     }
 
-    if (rest == end) return;
-    
+    if (rest == end) return NULL;
+
     // perform current query, but discard its results
-    rc = sqlite3_step(*stmt);
-    sqlite3_finalize(*stmt);
-    switch (rc) {
+    ctx->rc = sqlite3_step(*ctx->stmt);
+    sqlite3_finalize(*ctx->stmt);
+    switch (ctx->rc) {
     case SQLITE_BUSY:
-      rb_raise(cBusyError, "Database is busy");
     case SQLITE_ERROR:
-      rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
+    case SQLITE_MISUSE:
+      return NULL;
     }
-    ptr = rest;
+    str = rest;
   }
+  return NULL;
 }
 
-inline int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db) {
+/*
+This function prepares a statement from an SQL string containing one or more SQL
+statements. It will release the GVL while the statements are being prepared and
+executed. All statements excluding the last one are executed. The last statement
+is not executed, but instead handed back to the caller for looping over results.
+*/
+inline void prepare_multi_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
+  struct multi_stmt_ctx ctx = {db, stmt, RSTRING_PTR(sql), RSTRING_LEN(sql), 0};
+  rb_thread_call_without_gvl(prepare_multi_stmt_without_gvl, (void *)&ctx, RUBY_UBF_IO, 0);
+  RB_GC_GUARD(sql);
+
+  switch (ctx.rc) {
+  case 0:
+    return;
+  case SQLITE_BUSY:
+    rb_raise(cBusyError, "Database is busy");
+  case SQLITE_ERROR:
+    rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
+  default:
+    rb_raise(cError, "Invalid return code for prepare_multi_stmt_without_gvl: %d (please open an issue on https://github.com/digital-fabric/extralite)", ctx.rc);
+  }
+}
+
+struct step_ctx {
+  sqlite3_stmt *stmt;
   int rc;
-  rc = sqlite3_step(stmt);
-  switch (rc) {
+};
+
+void *stmt_iterate_without_gvl(void *ptr) {
+  struct step_ctx *ctx = (struct step_ctx *)ptr;
+  ctx->rc = sqlite3_step(ctx->stmt);
+  return NULL;
+}
+
+inline 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) {
     case SQLITE_ROW:
       return 1;
     case SQLITE_DONE:
@@ -207,7 +297,7 @@ inline int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db) {
     case SQLITE_ERROR:
       rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
     default:
-      rb_raise(cError, "Invalid return code for sqlite3_step: %d", rc);
+      rb_raise(cError, "Invalid return code for sqlite3_step: %d (please open an issue on https://github.com/digital-fabric/extralite)", ctx.rc);
   }
 
   return 0;
@@ -264,6 +354,29 @@ VALUE safe_query_hash(VALUE arg) {
   return result;
 }
 
+/* call-seq:
+ *    query(sql, *parameters, &block)
+ *    query_hash(sql, *parameters, &block)
+ *
+ * Runs a query returning rows as hashes (with symbol keys). If a block is
+ * given, it will be called for each row. Otherwise, an array containing all
+ * rows is returned.
+ * 
+ * Query parameters to be bound to placeholders in the query can be specified as
+ * a list of values or as a hash mapping parameter names to values. When
+ * parameters are given as a least, the query should specify parameters using
+ * `?`:
+ * 
+ *     db.query('select * from foo where x = ?', 42)
+ *
+ * Named placeholders are specified using `:`. The placeholder values are
+ * specified using a hash, where keys are either strings are symbols. String
+ * keys can include or omit the `:` prefix. The following are equivalent:
+ * 
+ *     db.query('select * from foo where x = :bar', bar: 42)
+ *     db.query('select * from foo where x = :bar', 'bar' => 42)
+ *     db.query('select * from foo where x = :bar', ':bar' => 42)
+ */
 VALUE Database_query_hash(int argc, VALUE *argv, VALUE self) {
   query_ctx ctx = { self, argc, argv, 0 };
   return rb_ensure(safe_query_hash, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
@@ -292,12 +405,32 @@ VALUE safe_query_ary(VALUE arg) {
     row = row_to_ary(ctx->stmt, column_count);
     if (yield_to_block) rb_yield(row); else rb_ary_push(result, row);
   }
-  
+
   RB_GC_GUARD(row);
   RB_GC_GUARD(result);
   return result;
 }
 
+/* call-seq: query_ary(sql, *parameters, &block)
+ *
+ * Runs a query returning rows as arrays. If a block is given, it will be called
+ * for each row. Otherwise, an array containing all rows is returned.
+ *
+ * Query parameters to be bound to placeholders in the query can be specified as
+ * a list of values or as a hash mapping parameter names to values. When
+ * parameters are given as a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_ary('select * from foo where x = ?', 42)
+ *
+ * Named placeholders are specified using `:`. The placeholder values are
+ * specified using a hash, where keys are either strings are symbols. String
+ * keys can include or omit the `:` prefix. The following are equivalent:
+ *
+ *     db.query_ary('select * from foo where x = :bar', bar: 42)
+ *     db.query_ary('select * from foo where x = :bar', 'bar' => 42)
+ *     db.query_ary('select * from foo where x = :bar', ':bar' => 42)
+ */
 VALUE Database_query_ary(int argc, VALUE *argv, VALUE self) {
   query_ctx ctx = { self, argc, argv, 0 };
   return rb_ensure(safe_query_ary, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
@@ -327,6 +460,25 @@ VALUE safe_query_single_row(VALUE arg) {
   return row;
 }
 
+/* call-seq: query_single_row(sql, *parameters)
+ *
+ * Runs a query returning a single row as a hash.
+ *
+ * Query parameters to be bound to placeholders in the query can be specified as
+ * a list of values or as a hash mapping parameter names to values. When
+ * parameters are given as a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_single_row('select * from foo where x = ?', 42)
+ *
+ * Named placeholders are specified using `:`. The placeholder values are
+ * specified using a hash, where keys are either strings are symbols. String
+ * keys can include or omit the `:` prefix. The following are equivalent:
+ *
+ *     db.query_single_row('select * from foo where x = :bar', bar: 42)
+ *     db.query_single_row('select * from foo where x = :bar', 'bar' => 42)
+ *     db.query_single_row('select * from foo where x = :bar', ':bar' => 42)
+ */
 VALUE Database_query_single_row(int argc, VALUE *argv, VALUE self) {
   query_ctx ctx = { self, argc, argv, 0 };
   return rb_ensure(safe_query_single_row, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
@@ -364,6 +516,26 @@ VALUE safe_query_single_column(VALUE arg) {
   return result;
 }
 
+/* call-seq: query_single_column(sql, *parameters, &block)
+ *
+ * Runs a query returning single column values. If a block is given, it will be called
+ * for each value. Otherwise, an array containing all values is returned.
+ *
+ * Query parameters to be bound to placeholders in the query can be specified as
+ * a list of values or as a hash mapping parameter names to values. When
+ * parameters are given as a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_single_column('select x from foo where x = ?', 42)
+ *
+ * Named placeholders are specified using `:`. The placeholder values are
+ * specified using a hash, where keys are either strings are symbols. String
+ * keys can include or omit the `:` prefix. The following are equivalent:
+ *
+ *     db.query_single_column('select x from foo where x = :bar', bar: 42)
+ *     db.query_single_column('select x from foo where x = :bar', 'bar' => 42)
+ *     db.query_single_column('select x from foo where x = :bar', ':bar' => 42)
+ */
 VALUE Database_query_single_column(int argc, VALUE *argv, VALUE self) {
   query_ctx ctx = { self, argc, argv, 0 };
   return rb_ensure(safe_query_single_column, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
@@ -392,11 +564,34 @@ VALUE safe_query_single_value(VALUE arg) {
   return value;
 }
 
+/* call-seq: query_single_value(sql, *parameters)
+ *
+ * Runs a query returning a single value from the first row.
+ *
+ * Query parameters to be bound to placeholders in the query can be specified as
+ * a list of values or as a hash mapping parameter names to values. When
+ * parameters are given as a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_single_value('select x from foo where x = ?', 42)
+ *
+ * Named placeholders are specified using `:`. The placeholder values are
+ * specified using a hash, where keys are either strings are symbols. String
+ * keys can include or omit the `:` prefix. The following are equivalent:
+ *
+ *     db.query_single_value('select x from foo where x = :bar', bar: 42)
+ *     db.query_single_value('select x from foo where x = :bar', 'bar' => 42)
+ *     db.query_single_value('select x from foo where x = :bar', ':bar' => 42)
+ */
 VALUE Database_query_single_value(int argc, VALUE *argv, VALUE self) {
   query_ctx ctx = { self, argc, argv, 0 };
   return rb_ensure(safe_query_single_value, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
 }
 
+/* call-seq: last_insert_rowid
+ *
+ * Returns the rowid of the last inserted row.
+ */
 VALUE Database_last_insert_rowid(VALUE self) {
   Database_t *db;
   GetOpenDatabase(self, db);
@@ -404,6 +599,10 @@ VALUE Database_last_insert_rowid(VALUE self) {
   return INT2NUM(sqlite3_last_insert_rowid(db->sqlite3_db));
 }
 
+/* call-seq: changes
+ *
+ * Returns the number of changes made to the database by the last operation.
+ */
 VALUE Database_changes(VALUE self) {
   Database_t *db;
   GetOpenDatabase(self, db);
@@ -411,6 +610,10 @@ VALUE Database_changes(VALUE self) {
   return INT2NUM(sqlite3_changes(db->sqlite3_db));
 }
 
+/* call-seq: filename
+ *
+ * Returns the database filename.
+ */
 VALUE Database_filename(int argc, VALUE *argv, VALUE self) {
   const char *db_name;
   const char *filename;
@@ -423,6 +626,10 @@ VALUE Database_filename(int argc, VALUE *argv, VALUE self) {
   return filename ? rb_str_new_cstr(filename) : Qnil;
 }
 
+/* call-seq: transaction_active?
+ *
+ * Returns true if a transaction is currently in progress.
+ */
 VALUE Database_transaction_active_p(VALUE self) {
   Database_t *db;
   GetOpenDatabase(self, db);
@@ -430,6 +637,10 @@ VALUE Database_transaction_active_p(VALUE self) {
   return sqlite3_get_autocommit(db->sqlite3_db) ? Qfalse : Qtrue;
 }
 
+/* call-seq: load_extension(path)
+ *
+ * Loads an extension with the given path.
+ */
 VALUE Database_load_extension(VALUE self, VALUE path) {
   Database_t *db;
   GetOpenDatabase(self, db);
@@ -453,14 +664,14 @@ void Init_Extralite() {
   rb_define_method(cDatabase, "initialize", Database_initialize, 1);
   rb_define_method(cDatabase, "close", Database_close, 0);
   rb_define_method(cDatabase, "closed?", Database_closed_p, 0);
-  
+
   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_single_column", Database_query_single_column, -1);
   rb_define_method(cDatabase, "query_single_value", Database_query_single_value, -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);
@@ -474,5 +685,7 @@ void Init_Extralite() {
   rb_gc_register_mark_object(cSQLError);
   rb_gc_register_mark_object(cBusyError);
 
-  ID_STRIP = rb_intern("strip");
+  ID_KEYS   = rb_intern("keys");
+  ID_STRIP  = rb_intern("strip");
+  ID_TO_S   = rb_intern("to_s");
 }

data/extralite.gemspec

@@ -11,7 +11,6 @@ Gem::Specification.new do |s|
   s.homepage    = 'https://github.com/digital-fabric/extralite'
   s.metadata    = {
     "source_code_uri" => "https://github.com/digital-fabric/extralite",
-    "documentation_uri" => "https://github.com/digital-fabric/extralite",
     "homepage_uri" => "https://github.com/digital-fabric/extralite",
     "changelog_uri" => "https://github.com/digital-fabric/extralite/blob/master/CHANGELOG.md"
   }
@@ -21,9 +20,10 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.required_ruby_version = '>= 2.6'
 
-  s.add_development_dependency  'rake-compiler',        '1.1.1'
-  s.add_development_dependency  'minitest',             '5.14.4'
+  s.add_development_dependency  'rake-compiler',        '1.1.6'
+  s.add_development_dependency  'minitest',             '5.15.0'
   s.add_development_dependency  'simplecov',            '0.17.1'
-  s.add_development_dependency  'rubocop',              '0.85.1'
-  s.add_development_dependency  'pry',                  '0.13.1'
+  s.add_development_dependency  'yard',                 '0.9.27'
+
+  s.add_development_dependency  'sequel',               '5.51.0'
 end

data/lib/extralite/version.rb

@@ -1,3 +1,3 @@
 module Extralite
-  VERSION = '1.4'
+  VERSION = '1.8.1'
 end

data/lib/extralite.rb

@@ -1 +1,21 @@
 require_relative './extralite_ext'
+
+# Extralite is a Ruby gem for working with SQLite databases
+module Extralite
+  # A base class for Extralite exceptions
+  class Error < RuntimeError
+  end
+
+  # An exception representing an SQL error emitted by SQLite
+  class SQLError < Error
+  end
+
+  # An exception raised when an SQLite database is busy (locked by another
+  # thread or process)
+  class BusyError < Error
+  end
+
+  # An SQLite database
+  class Database
+  end
+end