extralite 1.5 → 1.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad8337aebac5ef75132340d8336389fe0c927ed454b5792d57f80efa4f362664
-  data.tar.gz: 602ad3648312e810398fac215353b0fac5aa916ff7a3a7901ba1990c9e3fb145
+  metadata.gz: dd26d2937628e408ba8ee2f69e2e170755a43d5e1ffcdcbb82ca184cd5734576
+  data.tar.gz: c762b88c6e1671de5daab90f6f6fb574bb4dfb43fb0a866e8154fb8ac02f755f
 SHA512:
-  metadata.gz: a5831721c27d2eb27c8433bcd286ba826861946b7894eb2c1564f449d321d2eaeec7cce13a4166b10db799f9e9e391bc2ba65961edc7b144592d1994767e69b0
-  data.tar.gz: ce77ee584ec89bae2819a2c0384ca7cc08daf00f405d0bf379f322d6182b3bf55bceb0ac0136d52fddd3fe5a43e4e48eb23cbfc00eef74a0439ce25eeeb529f7
+  metadata.gz: 9ea096a28f15e8415b8e450a45035ffbe0c2186ebc7bba2ddd76c34e2328baaff307cee3c5079dda235992011497ef72b924bf3916628842e100ba8953ee7454
+  data.tar.gz: 0efd84d3a7fa1fd1157df43f65bd4fa6999a0943efc8c0b36030a8550bbb2bc1c3a96509d4bf6c7a8a2bb9c4bd071dc0a650cb45e54e75c7ec722ee29c8bb72e

data/.github/workflows/test.yml

@@ -8,7 +8,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        ruby: [2.6, 2.7, 3.0]
+        ruby: [2.6, 2.7, '3.0']
 
     name: >-
       ${{matrix.os}}, ${{matrix.ruby}}
@@ -16,15 +16,10 @@ jobs:
     runs-on: ${{matrix.os}}
     steps:
     - uses: actions/checkout@v1
-    - uses: actions/setup-ruby@v1
+    - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{matrix.ruby}}
-    - name: Install dependencies
-      run: |
-        gem install bundler
-        bundle install
-    - name: Show Linux kernel version
-      run: uname -r
+        bundler-cache: true # 'bundle install' and cache
     - name: Compile C-extension
       run: bundle exec rake compile
     - name: Run tests

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 1.8.2 2021-12-15
+
+- Add documentation
+
+## 1.7 2021-12-13
+
+- Add extralite Sequel adapter
+- Add support for binding hash parameters
+
+## 1.6 2021-12-13
+
+- Release GVL while fetching rows
+
 ## 1.5 2021-12-13
 
 - Release GVL while preparing statements

data/Gemfile.lock

@@ -1,58 +1,37 @@
 PATH
   remote: .
   specs:
-    extralite (1.5)
+    extralite (1.8.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
-    coderay (1.1.3)
     docile (1.4.0)
     json (2.5.1)
-    method_source (1.0.0)
-    minitest (5.14.4)
-    parallel (1.20.1)
-    parser (3.0.1.1)
-      ast (~> 2.4.1)
-    pry (0.13.1)
-      coderay (~> 1.1)
-      method_source (~> 1.0)
-    rainbow (3.0.0)
-    rake (13.0.3)
-    rake-compiler (1.1.1)
+    minitest (5.15.0)
+    rake (13.0.6)
+    rake-compiler (1.1.6)
       rake
-    regexp_parser (2.1.1)
-    rexml (3.2.5)
-    rubocop (0.85.1)
-      parallel (~> 1.10)
-      parser (>= 2.7.0.1)
-      rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.7)
-      rexml
-      rubocop-ast (>= 0.0.3)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (1.5.0)
-      parser (>= 3.0.1.1)
-    ruby-progressbar (1.11.0)
+    sequel (5.51.0)
     simplecov (0.17.1)
       docile (~> 1.1)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
-    unicode-display_width (1.7.0)
+    webrick (1.7.0)
+    yard (0.9.27)
+      webrick (~> 1.7.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   extralite!
-  minitest (= 5.14.4)
-  pry (= 0.13.1)
-  rake-compiler (= 1.1.1)
-  rubocop (= 0.85.1)
+  minitest (= 5.15.0)
+  rake-compiler (= 1.1.6)
+  sequel (= 5.51.0)
   simplecov (= 0.17.1)
+  yard (= 0.9.27)
 
 BUNDLED WITH
    2.1.4

data/README.md

@@ -6,22 +6,29 @@
 
 ## What is Extralite?
 
-Extralite is an extra-lightweight (less than 400 lines of C-code) SQLite3 wrapper for
-Ruby. It provides a single class with a minimal set of methods to interact with
-an SQLite3 database.
+Extralite is an extra-lightweight (less than 430 lines of C-code) SQLite3
+wrapper for Ruby. It provides a single class with a minimal set of methods to
+interact with an SQLite3 database.
 
 ## Features
 
-- A variety of methods for different data access patterns: row as hash, row as
-  array, single single row, single column, single value.
+- A variety of methods for different data access patterns: rows as hashes, rows
+  as arrays, single row, single column, single value.
+- Super fast - [up to 12.5x faster](#performance) than the
+  [sqlite3](https://github.com/sparklemotion/sqlite3-ruby) gem (see also
+  [comparison](#why-not-just-use-the-sqlite3-gem).)
+- Improved [concurrency](#what-about-concurrency) for multithreaded apps: the
+  Ruby GVL is released while preparing SQL statements and while iterating over
+  results.
 - Iterate over records with a block, or collect records into an array.
 - Parameter binding.
-- Correctly execute strings with multiple semicolon-separated queries (handy for
-  creating/modifying schemas).
+- Automatically execute SQL strings containing multiple semicolon-separated
+  queries (handy for creating/modifying schemas).
 - Get last insert rowid.
 - Get number of rows changed by last query.
 - 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) (an ActiveRecord)
 
 ## Usage
 
@@ -60,8 +67,13 @@ db.query_single_value("select 'foo'") #=> "foo"
 # parameter binding (works for all query_xxx methods)
 db.query_hash('select ? as foo, ? as bar', 1, 2) #=> [{ :foo => 1, :bar => 2 }]
 
+# parameter binding of named parameters
+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)
+
 # get last insert rowid
-rowid = db.last_insert_id
+rowid = db.last_insert_rowid
 
 # get number of rows changed in last query
 number_of_rows_affected = db.changes
@@ -77,23 +89,74 @@ db.close
 db.closed? #=> true
 ```
 
+## Usage with Sequel
+
+Extralite includes an adapter for
+[Sequel](https://github.com/jeremyevans/sequel). To use the Extralite adapter,
+just use the `extralite` scheme instead of `sqlite`:
+
+```ruby
+DB = Sequel.connect('extralite:blog.db')
+articles = DB[:articles]
+p articles.to_a
+```
+
+(Make sure you include `extralite` as a dependency in your `Gemfile`.)
+
 ## Why not just use the sqlite3 gem?
 
-The sqlite3-ruby gem is a popular, solid, well-maintained project, used by
-thousands of developers. I've been doing a lot of work with SQLite3 lately, and
-wanted to have a simpler API that gives me query results in a variety of ways.
-Thus extralite was born.
+The [sqlite3-ruby](https://github.com/sparklemotion/sqlite3-ruby) gem is a
+popular, solid, well-maintained project, used by thousands of developers. I've
+been doing a lot of work with SQLite3 databases lately, and wanted to have a
+simpler API that gives me query results in a variety of ways. Thus extralite was
+born.
+
+Extralite is quite a bit [faster](#performance) than sqlite3-ruby and is also
+[thread-friendly](#what-about-concurrency). On the other hand, Extralite does
+not have support for defining custom functions, aggregates and collations. If
+you're using those features, you'll need to stick with sqlite3-ruby.
+
+Here's a table summarizing the differences between the two gems:
+
+| |sqlite3-ruby|Extralite|
+|-|-|-|
+|API design|multiple classes|single class|
+|Query results|row as hash, row as array, single row, single value|row as hash, row as array, __single column__, single row, single value|
+|execute multiple statements|separate API (#execute_batch)|integrated|
+|custom functions in Ruby|yes|no|
+|custom collations|yes|no|
+|custom aggregate functions|yes|no|
+|Multithread friendly|no|[yes](#what-about-concurrency)|
+|Code size|~2650LoC|~500LoC|
+|Performance|1x|1.5x to 12.5x (see [below](#performance))|
 
 ## What about concurrency?
 
-Extralite currently does not release the GVL. This means that even if queries
-are executed on a separate thread, no other Ruby threads will be scheduled while
-SQLite3 is busy fetching the next record.
+Extralite releases the GVL while making blocking calls to the sqlite3 library,
+that is while preparing SQL statements and fetching rows. Releasing the GVL
+allows other threads to run while the sqlite3 library is busy compiling SQL into
+bytecode, or fetching the next row. This does not seem to hurt Extralite's
+performance:
+
+## Performance
+
+A benchmark script is
+[included](https://github.com/digital-fabric/extralite/blob/main/test/perf.rb),
+creating a table of various row counts, then fetching the entire table using
+either `sqlite3` or `extralite`. This benchmark shows Extralite to be up to 12.5
+times faster than `sqlite3` when fetching a large number of rows. Here are the
+results (using the `sqlite3` gem performance as baseline):
+
+|Row count|sqlite3-ruby (baseline)|Extralite (relative - rounded)|
+|-:|-:|-:|
+|10|1x|1.5x|
+|1K|1x|7x|
+|100K|1x|12.5x|
 
-In the future Extralite might be changed to release the GVL each time
-`sqlite3_step` is called.
+(If you're interested in checking this yourself, just run the script and let me
+know if your results are different.)
 
-## Can I use it with an ORM like ActiveRecord or Sequel?
+## Contributing
 
-Not yet, but you are welcome to contribute adapters for those projects. I will
-be releasing my own not-an-ORM tool in the near future.
+Contributions in the form of issues, PRs or comments will be greatly
+appreciated!

data/Rakefile

@@ -1,18 +1,27 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rake/clean"
+require 'bundler/gem_tasks'
+require 'rake/clean'
 
-require "rake/extensiontask"
-Rake::ExtensionTask.new("extralite_ext") do |ext|
-  ext.ext_dir = "ext/extralite"
+require 'rake/extensiontask'
+Rake::ExtensionTask.new('extralite_ext') do |ext|
+  ext.ext_dir = 'ext/extralite'
 end
 
 task :recompile => [:clean, :compile]
 
-task :default => [:compile, :test]
+task :default => [:compile, :doc, :test]
+task :doc => :yard
 task :test do
-  exec 'ruby test/test_database.rb'
+  exec 'ruby test/run.rb'
 end
 
-CLEAN.include "**/*.o", "**/*.so", "**/*.so.*", "**/*.a", "**/*.bundle", "**/*.jar", "pkg", "tmp"
+CLEAN.include '**/*.o', '**/*.so', '**/*.so.*', '**/*.a', '**/*.bundle', '**/*.jar', 'pkg', 'tmp'
+
+require 'yard'
+YARD_FILES = FileList['ext/extralite/extralite.c', 'lib/extralite.rb', 'lib/sequel/adapters/extralite.rb']
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = YARD_FILES
+  t.options = %w(-o doc --readme README.md)
+end

data/ext/extralite/extralite.c

@@ -6,7 +6,10 @@
 VALUE cError;
 VALUE cSQLError;
 VALUE cBusyError;
+
+ID ID_KEYS;
 ID ID_STRIP;
+ID ID_TO_S;
 
 typedef struct Database_t {
   sqlite3 *sqlite3_db;
@@ -48,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;
@@ -69,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;
@@ -83,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);
@@ -109,6 +124,33 @@ 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)) {
     case T_NIL:
@@ -129,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);
   }
@@ -228,10 +273,21 @@ inline void prepare_multi_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
   }
 }
 
-inline int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db) {
+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:
@@ -241,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 (please open an issue on https://github.com/digital-fabric/extralite)", 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;
@@ -298,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);
@@ -332,6 +411,26 @@ VALUE safe_query_ary(VALUE arg) {
   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);
@@ -361,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);
@@ -398,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);
@@ -426,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);
@@ -438,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);
@@ -445,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;
@@ -457,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);
@@ -464,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);
@@ -508,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,7 @@ 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",
+    "documentation_uri" => "https://www.rubydoc.info/gems/extralite",
     "homepage_uri" => "https://github.com/digital-fabric/extralite",
     "changelog_uri" => "https://github.com/digital-fabric/extralite/blob/master/CHANGELOG.md"
   }
@@ -21,9 +21,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.5'
+  VERSION = '1.8.2'
 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

data/lib/sequel/adapters/extralite.rb

@@ -0,0 +1,380 @@
+# frozen-string-literal: true
+
+# This file was adapted from the SQLite adapter included in Sequel:
+# https://github.com/jeremyevans/sequel
+# (distributed under the MIT license)
+
+require 'extralite'
+require 'sequel/adapters/shared/sqlite'
+
+module Sequel
+  module Extralite
+    FALSE_VALUES = (%w'0 false f no n'.each(&:freeze) + [0]).freeze
+
+    blob = Object.new
+    def blob.call(s)
+      Sequel::SQL::Blob.new(s.to_s)
+    end
+
+    boolean = Object.new
+    def boolean.call(s)
+      s = s.downcase if s.is_a?(String)
+      !FALSE_VALUES.include?(s)
+    end
+
+    date = Object.new
+    def date.call(s)
+      case s
+      when String
+        Sequel.string_to_date(s)
+      when Integer
+        Date.jd(s)
+      when Float
+        Date.jd(s.to_i)
+      else
+        raise Sequel::Error, "unhandled type when converting to date: #{s.inspect} (#{s.class.inspect})"
+      end
+    end
+
+    integer = Object.new
+    def integer.call(s)
+      s.to_i
+    end
+
+    float = Object.new
+    def float.call(s)
+      s.to_f
+    end
+
+    numeric = Object.new
+    def numeric.call(s)
+      s = s.to_s unless s.is_a?(String)
+      BigDecimal(s) rescue s
+    end
+
+    time = Object.new
+    def time.call(s)
+      case s
+      when String
+        Sequel.string_to_time(s)
+      when Integer
+        Sequel::SQLTime.create(s/3600, (s % 3600)/60, s % 60)
+      when Float
+        s, f = s.divmod(1)
+        Sequel::SQLTime.create(s/3600, (s % 3600)/60, s % 60, (f*1000000).round)
+      else
+        raise Sequel::Error, "unhandled type when converting to date: #{s.inspect} (#{s.class.inspect})"
+      end
+    end
+
+    # Hash with string keys and callable values for converting SQLite types.
+    SQLITE_TYPES = {}
+    {
+      %w'date' => date,
+      %w'time' => time,
+      %w'bit bool boolean' => boolean,
+      %w'integer smallint mediumint int bigint' => integer,
+      %w'numeric decimal money' => numeric,
+      %w'float double real dec fixed' + ['double precision'] => float,
+      %w'blob' => blob
+    }.each do |k,v|
+      k.each{|n| SQLITE_TYPES[n] = v}
+    end
+    SQLITE_TYPES.freeze
+
+    USE_EXTENDED_RESULT_CODES = false
+    
+    class Database < Sequel::Database
+      include ::Sequel::SQLite::DatabaseMethods
+      
+      set_adapter_scheme :extralite
+      
+      # Mimic the file:// uri, by having 2 preceding slashes specify a relative
+      # path, and 3 preceding slashes specify an absolute path.
+      def self.uri_to_options(uri) # :nodoc:
+        { :database => (uri.host.nil? && uri.path == '/') ? nil : "#{uri.host}#{uri.path}" }
+      end
+      
+      private_class_method :uri_to_options
+
+      # The conversion procs to use for this database
+      attr_reader :conversion_procs
+
+      # Connect to the database. Since SQLite is a file based database,
+      # available options are limited:
+      #
+      # :database :: database name (filename or ':memory:' or file: URI)
+      # :readonly :: open database in read-only mode; useful for reading
+      #              static data that you do not want to modify
+      # :timeout :: how long to wait for the database to be available if it
+      #             is locked, given in milliseconds (default is 5000)
+      def connect(server)
+        opts = server_opts(server)
+        opts[:database] = ':memory:' if blank_object?(opts[:database])
+        # sqlite3_opts = {}
+        # sqlite3_opts[:readonly] = typecast_value_boolean(opts[:readonly]) if opts.has_key?(:readonly)
+        db = ::Extralite::Database.new(opts[:database].to_s)#, sqlite3_opts)
+        # db.busy_timeout(typecast_value_integer(opts.fetch(:timeout, 5000)))
+
+        # if USE_EXTENDED_RESULT_CODES
+        #   db.extended_result_codes = true
+        # end
+        
+        connection_pragmas.each{|s| log_connection_yield(s, db){db.query(s)}}
+        
+        # class << db
+        #   attr_reader :prepared_statements
+        # end
+        # db.instance_variable_set(:@prepared_statements, {})
+        
+        db
+      end
+
+      # Disconnect given connections from the database.
+      def disconnect_connection(c)
+        # c.prepared_statements.each_value{|v| v.first.close}
+        c.close
+      end
+      
+      # Run the given SQL with the given arguments and yield each row.
+      def execute(sql, opts=OPTS, &block)
+        _execute(:select, sql, opts, &block)
+      end
+
+      # Run the given SQL with the given arguments and return the number of changed rows.
+      def execute_dui(sql, opts=OPTS)
+        _execute(:update, sql, opts)
+      end
+      
+      # Drop any prepared statements on the connection when executing DDL.  This is because
+      # prepared statements lock the table in such a way that you can't drop or alter the
+      # table while a prepared statement that references it still exists.
+      # def execute_ddl(sql, opts=OPTS)
+      #   synchronize(opts[:server]) do |conn|
+      #     conn.prepared_statements.values.each{|cps, s| cps.close}
+      #     conn.prepared_statements.clear
+      #     super
+      #   end
+      # end
+      
+      def execute_insert(sql, opts=OPTS)
+        _execute(:insert, sql, opts)
+      end
+      
+      def freeze
+        @conversion_procs.freeze
+        super
+      end
+
+      # Handle Integer and Float arguments, since SQLite can store timestamps as integers and floats.
+      def to_application_timestamp(s)
+        case s
+        when String
+          super
+        when Integer
+          super(Time.at(s).to_s)
+        when Float
+          super(DateTime.jd(s).to_s)
+        else
+          raise Sequel::Error, "unhandled type when converting to : #{s.inspect} (#{s.class.inspect})"
+        end
+      end
+
+      private
+      
+      def adapter_initialize
+        @conversion_procs = SQLITE_TYPES.dup
+        @conversion_procs['datetime'] = @conversion_procs['timestamp'] = method(:to_application_timestamp)
+        set_integer_booleans
+      end
+      
+      # Yield an available connection. Rescue any Extralite::Error and turn
+      # them into DatabaseErrors.
+      def _execute(type, sql, opts, &block)
+        begin
+          synchronize(opts[:server]) do |conn|
+            # return execute_prepared_statement(conn, type, sql, opts, &block) if sql.is_a?(Symbol)
+            log_args = opts[:arguments]
+            args = {}
+            opts.fetch(:arguments, OPTS).each{|k, v| args[k] = prepared_statement_argument(v) }
+            case type
+            when :select
+              log_connection_yield(sql, conn, log_args){conn.query(sql, args, &block)}
+            when :insert
+              log_connection_yield(sql, conn, log_args){conn.query(sql, args)}
+              conn.last_insert_rowid
+            when :update
+              log_connection_yield(sql, conn, log_args){conn.query(sql, args)}
+              conn.changes
+            end
+          end
+        rescue ::Extralite::Error => e
+          raise_error(e)
+        end
+      end
+      
+      # The SQLite adapter does not need the pool to convert exceptions.
+      # Also, force the max connections to 1 if a memory database is being
+      # used, as otherwise each connection gets a separate database.
+      def connection_pool_default_options
+        o = super.dup
+        # Default to only a single connection if a memory database is used,
+        # because otherwise each connection will get a separate database
+        o[:max_connections] = 1 if @opts[:database] == ':memory:' || blank_object?(@opts[:database])
+        o
+      end
+      
+      def prepared_statement_argument(arg)
+        case arg
+        when Date, DateTime, Time
+          literal(arg)[1...-1]
+        when SQL::Blob
+          arg.to_blob
+        when true, false
+          if integer_booleans
+            arg ? 1 : 0
+          else
+            literal(arg)[1...-1]
+          end
+        else
+          arg
+        end
+      end
+
+      # Execute a prepared statement on the database using the given name.
+      def execute_prepared_statement(conn, type, name, opts, &block)
+        ps = prepared_statement(name)
+        sql = ps.prepared_sql
+        args = opts[:arguments]
+        ps_args = {}
+        args.each{|k, v| ps_args[k] = prepared_statement_argument(v)}
+        if cpsa = conn.prepared_statements[name]
+          cps, cps_sql = cpsa
+          if cps_sql != sql
+            cps.close
+            cps = nil
+          end
+        end
+        unless cps
+          cps = log_connection_yield("PREPARE #{name}: #{sql}", conn){conn.prepare(sql)}
+          conn.prepared_statements[name] = [cps, sql]
+        end
+        log_sql = String.new
+        log_sql << "EXECUTE #{name}"
+        if ps.log_sql
+          log_sql << " ("
+          log_sql << sql
+          log_sql << ")"
+        end
+        if block
+          log_connection_yield(log_sql, conn, args){cps.execute(ps_args, &block)}
+        else
+          log_connection_yield(log_sql, conn, args){cps.execute!(ps_args){|r|}}
+          case type
+          when :insert
+            conn.last_insert_rowid
+          when :update
+            conn.changes
+          end
+        end
+      end
+      
+      # # SQLite3 raises ArgumentError in addition to SQLite3::Exception in
+      # # some cases, such as operations on a closed database.
+      def database_error_classes
+        #[Extralite::Error, ArgumentError]
+        [::Extralite::Error]
+      end
+
+      def dataset_class_default
+        Dataset
+      end
+
+      if USE_EXTENDED_RESULT_CODES
+        # Support SQLite exception codes if ruby-sqlite3 supports them.
+        def sqlite_error_code(exception)
+          exception.code if exception.respond_to?(:code)
+        end
+      end
+    end
+    
+    class Dataset < Sequel::Dataset
+      include ::Sequel::SQLite::DatasetMethods
+
+      module ArgumentMapper
+        include Sequel::Dataset::ArgumentMapper
+        
+        protected
+        
+        # Return a hash with the same values as the given hash,
+        # but with the keys converted to strings.
+        def map_to_prepared_args(hash)
+          args = {}
+          hash.each{|k,v| args[k.to_s.gsub('.', '__')] = v}
+          args
+        end
+        
+        private
+        
+        # SQLite uses a : before the name of the argument for named
+        # arguments.
+        def prepared_arg(k)
+          LiteralString.new("#{prepared_arg_placeholder}#{k.to_s.gsub('.', '__')}")
+        end
+      end
+      
+      BindArgumentMethods = prepared_statements_module(:bind, ArgumentMapper)
+      PreparedStatementMethods = prepared_statements_module(:prepare, BindArgumentMethods)
+
+      def fetch_rows(sql, &block)
+        execute(sql, &block)
+        # execute(sql) do |result|
+        #   cps = db.conversion_procs
+        #   type_procs = result.types.map{|t| cps[base_type_name(t)]}
+        #   j = -1
+        #   cols = result.columns.map{|c| [output_identifier(c), type_procs[(j+=1)]]}
+        #   self.columns = cols.map(&:first)
+        #   max = cols.length
+        #   result.each do |values|
+        #     row = {}
+        #     i = -1
+        #     while (i += 1) < max
+        #       name, type_proc = cols[i]
+        #       v = values[i]
+        #       if type_proc && v
+        #         v = type_proc.call(v)
+        #       end
+        #       row[name] = v
+        #     end
+        #     yield row
+        #   end
+        # end
+      end
+      
+      private
+      
+      # The base type name for a given type, without any parenthetical part.
+      def base_type_name(t)
+        (t =~ /^(.*?)\(/ ? $1 : t).downcase if t
+      end
+
+      # Quote the string using the adapter class method.
+      def literal_string_append(sql, v)
+        sql << "'" << v.gsub(/'/, "''") << "'"
+      end
+
+      def bound_variable_modules
+        [BindArgumentMethods]
+      end
+
+      def prepared_statement_modules
+        [PreparedStatementMethods]
+      end
+
+      # SQLite uses a : before the name of the argument as a placeholder.
+      def prepared_arg_placeholder
+        ':'
+      end
+    end
+  end
+end

data/test/perf.rb

@@ -13,36 +13,39 @@ require 'benchmark/ips'
 require 'fileutils'
 
 DB_PATH = '/tmp/extralite_sqlite3_perf.db'
-COUNT = 10000
 
-def prepare_database
+def prepare_database(count)
   FileUtils.rm(DB_PATH) rescue nil
   db = Extralite::Database.new(DB_PATH)
   db.query('create table foo ( a integer primary key, b text )')
   db.query('begin')
-  COUNT.times { db.query('insert into foo (b) values (?)', "hello#{rand(1000)}" )}
+  count.times { db.query('insert into foo (b) values (?)', "hello#{rand(1000)}" )}
   db.query('commit')
 end
 
-def sqlite3_run
+def sqlite3_run(count)
   db = SQLite3::Database.new(DB_PATH, :results_as_hash => true)
   results = db.execute('select * from foo')
-  raise unless results.size == COUNT
+  raise unless results.size == count
 end
 
-def extralite_run
+def extralite_run(count)
   db = Extralite::Database.new(DB_PATH)
   results = db.query('select * from foo')
-  raise unless results.size == COUNT
+  raise unless results.size == count
 end
 
-prepare_database
+[10, 1000, 100000].each do |c|
+  puts; puts; puts "Record count: #{c}"
 
-Benchmark.ips do |x|
-  x.config(:time => 3, :warmup => 1)
+  prepare_database(c)
 
-  x.report("sqlite3") { sqlite3_run }
-  x.report("extralite") { extralite_run }
+  Benchmark.ips do |x|
+    x.config(:time => 3, :warmup => 1)
 
-  x.compare!
+    x.report("sqlite3") { sqlite3_run(c) }
+    x.report("extralite") { extralite_run(c) }
+
+    x.compare!
+  end
 end

data/test/run.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Dir.glob("#{__dir__}/test_*.rb").each do |path|
+  require(path)
+end

data/test/test_database.rb

@@ -111,6 +111,33 @@ end
 
     assert_raises(Extralite::Error) { @db.query_single_value('select 42') }
   end
+
+  def test_parameter_binding_simple
+    r = @db.query('select x, y, z from t where x = ?', 1)
+    assert_equal [{ x: 1, y: 2, z: 3 }], r
+
+    r = @db.query('select x, y, z from t where z = ?', 6)
+    assert_equal [{ x: 4, y: 5, z: 6 }], r
+  end
+
+  def test_parameter_binding_with_index
+    r = @db.query('select x, y, z from t where x = ?2', 0, 1)
+    assert_equal [{ x: 1, y: 2, z: 3 }], r
+
+    r = @db.query('select x, y, z from t where z = ?3', 3, 4, 6)
+    assert_equal [{ x: 4, y: 5, z: 6 }], r
+  end
+
+  def test_parameter_binding_with_name
+    r = @db.query('select x, y, z from t where x = :x', x: 1, y: 2)
+    assert_equal [{ x: 1, y: 2, z: 3 }], r
+
+    r = @db.query('select x, y, z from t where z = :zzz', 'zzz' => 6)
+    assert_equal [{ x: 4, y: 5, z: 6 }], r
+
+    r = @db.query('select x, y, z from t where z = :bazzz', ':bazzz' => 6)
+    assert_equal [{ x: 4, y: 5, z: 6 }], r
+  end
 end
 
 class ScenarioTest < MiniTest::Test
@@ -179,4 +206,3 @@ class ScenarioTest < MiniTest::Test
     assert_equal [1, 4, 7], result
   end
 end
-

data/test/test_sequel.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'helper'
+require 'sequel'
+
+class SequelExtraliteTest < MiniTest::Test
+  def test_sequel
+    db = Sequel.connect('extralite::memory:')
+    db.create_table :items do
+      primary_key :id
+      String :name, unique: true, null: false
+      Float :price, null: false
+    end
+
+    items = db[:items]
+
+    items.insert(name: 'abc', price: 123)
+    items.insert(name: 'def', price: 456)
+    items.insert(name: 'ghi', price: 789)
+
+    assert_equal 3, items.count
+    assert_equal (123+456+789) / 3, items.avg(:price)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: extralite
 version: !ruby/object:Gem::Version
-  version: '1.5'
+  version: 1.8.2
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-13 00:00:00.000000000 Z
+date: 2021-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.1.1
+        version: 1.1.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.1.1
+        version: 1.1.6
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.14.4
+        version: 5.15.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.14.4
+        version: 5.15.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -53,33 +53,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.17.1
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.85.1
+        version: 0.9.27
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.85.1
+        version: 0.9.27
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: sequel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.13.1
+        version: 5.51.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.13.1
+        version: 5.51.0
 description: 
 email: sharon@noteflakes.com
 executables: []
@@ -103,15 +103,18 @@ files:
 - extralite.gemspec
 - lib/extralite.rb
 - lib/extralite/version.rb
+- lib/sequel/adapters/extralite.rb
 - test/helper.rb
 - test/perf.rb
+- test/run.rb
 - test/test_database.rb
+- test/test_sequel.rb
 homepage: https://github.com/digital-fabric/extralite
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/digital-fabric/extralite
-  documentation_uri: https://github.com/digital-fabric/extralite
+  documentation_uri: https://www.rubydoc.info/gems/extralite
   homepage_uri: https://github.com/digital-fabric/extralite
   changelog_uri: https://github.com/digital-fabric/extralite/blob/master/CHANGELOG.md
 post_install_message: