extralite 1.11 → 1.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d88bd81eca07e148be1f8d5b07d24c0aab49b32a9dc9aeb4a9ea5a74cf769491
-  data.tar.gz: 9f5d55a8cd4a58e2026ca3e850d48c28d86878e191e91fb92e59c76335a64484
+  metadata.gz: 887537f02a38e762c189e2c322074efc59ef28a662021f59fbfad6cc0dafc13c
+  data.tar.gz: e519f080b81120044cd25113145fb571e5655b377e992643b5fc711a7ab6abfa
 SHA512:
-  metadata.gz: cca614a4e3ffde8ff56ef3e8394f85f4a57d37f8615f2f144a9a39f84d50e51dd015348da7f93340326b40ff4b16202ec21bc03f23edacf678c03f57d0955974
-  data.tar.gz: 2e9f9c9091ac99fa96c3562fdb1e49642b2961ee682c30d98f8babd95b8366d9c96019df7185c5ef493b330f6c32066be6868398dcdb123c4607e9ab4875462b
+  metadata.gz: 50fef96363c87e0f2461165bed0c608b0bf7a24d1d3d9b90fc1b741446a2685d94bd54d392bae1714984b4c95fbf925c1a839c2b70bfb62262fc3e1112c321a8
+  data.tar.gz: ca51f38183ebc65b01b18ad4ce58885eba4481ab8804de3e70ad140e1470bfeb2c99177db6e0817fb8aa5532c532d6a848e0b20814da93f29b84f7f4fd9bdd6d

data/.github/workflows/test.yml

@@ -8,7 +8,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-10.15]
-        ruby: [2.6, 2.7, '3.0']
+        ruby: [2.7, 3.0, 3.1, truffleruby]
 
     name: >-
       ${{matrix.os}}, ${{matrix.ruby}}

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 1.13.1 2022-02-27
+
+- Fix compilation on TruffleRuby
+
+## 1.13 2022-02-27
+
+- Implement prepared statements (#7)
+- Update SQLite to 3.38.0 (#6)
+
+## 1.12 2022-02-15
+
+- Add `Extralite.sqlite3_version` method
+- Bundle sqlite3 in gem
+
 ## 1.11 2021-12-17
 
 - Fix compilation on MacOS (#3)

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    extralite (1.11)
+    extralite (1.13.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     docile (1.4.0)
-    json (2.5.1)
+    json (2.6.1)
     minitest (5.15.0)
     rake (13.0.6)
     rake-compiler (1.1.6)
@@ -34,4 +34,4 @@ DEPENDENCIES
   yard (= 0.9.27)
 
 BUNDLED WITH
-   2.1.4
+   2.3.3

data/README.md

@@ -23,20 +23,24 @@
 
 ## What is Extralite?
 
-Extralite is a fast, extra-lightweight (less than 460 lines of C-code) SQLite3
-wrapper for Ruby. It provides a single class with a minimal set of methods for
-interacting with an SQLite3 database.
+Extralite is a fast, extra-lightweight (about 600 lines of C-code) SQLite3
+wrapper for Ruby. It provides a minimal set of methods for interacting with an
+SQLite3 database, as well as prepared statements. Extralite bundles the latest
+version of SQLite, offering access to the latest features and enhancements.
 
 ## Features
 
+- Zero dependencies: Extralite bundles SQLite3 version
+  [3.38.0](https://sqlite.org/releaselog/3_38_0.html) - no need to install any
+  `libsqlite3` packages.
 - A variety of methods for different data access patterns: rows as hashes, rows
   as arrays, single row, single column, single value.
+- Prepared statements.
 - 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.
+- Improved [concurrency](#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.
 - Automatically execute SQL strings containing multiple semicolon-separated
@@ -45,13 +49,30 @@ interacting with an SQLite3 database.
 - 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)
+- Includes a [Sequel adapter](#usage-with-sequel).
+
+## Installation
+
+To use Extralite in your Ruby app, add the following to your `Gemfile`:
+
+```ruby
+gem 'extralite'
+```
+
+You can also run `gem install extralite` if you just want to check it out.
+
+> **Important note**: Extralite will take a while to install (on my modest
+> machine it takes about a minute). This is owing to the fact that Extralite
+> bundles the sqlite3 code, which is compiled upon installation.
 
 ## Usage
 
 ```ruby
 require 'extralite'
 
+# get sqlite3 version
+Extralite.sqlite3_version #=> "3.38.0"
+
 # open a database
 db = Extralite::Database.new('/tmp/my.db')
 
@@ -89,6 +110,12 @@ 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)
 
+# prepared statements
+stmt = db.prepare('select ? as foo, ? as bar') #=> Extralite::PreparedStatement
+stmt.query(1, 2) #=> [{ :foo => 1, :bar => 2 }]
+# PreparedStatement offers the same data access methods as the Database class,
+# but without the sql parameter.
+
 # get last insert rowid
 rowid = db.last_insert_rowid
 
@@ -113,7 +140,7 @@ Extralite includes an adapter for
 just use the `extralite` scheme instead of `sqlite`:
 
 ```ruby
-DB = Sequel.connect('extralite:blog.db')
+DB = Sequel.connect('extralite://blog.db')
 articles = DB[:articles]
 p articles.to_a
 ```
@@ -129,25 +156,27 @@ 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.
+[thread-friendly](#concurrency). On the other hand, Extralite does not have
+support for defining custom functions, aggregates and collations. If you're
+using any of those features, you'll have to stick to sqlite3-ruby.
 
 Here's a table summarizing the differences between the two gems:
 
 | |sqlite3-ruby|Extralite|
 |-|-|-|
+|SQLite3 dependency|depends on OS-installed libsqlite3|bundles latest version of SQLite3|
 |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|
+|Execute multiple statements|separate API (#execute_batch)|integrated|
+|Prepared statements|yes|yes|
 |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|~530LoC|
+|Multithread friendly|no|[yes](#concurrency)|
+|Code size|~2650LoC|~600LoC|
 |Performance|1x|1.5x to 12.5x (see [below](#performance))|
 
-## What about concurrency?
+## Concurrency
 
 Extralite releases the GVL while making blocking calls to the sqlite3 library,
 that is while preparing SQL statements and fetching rows. Releasing the GVL
@@ -159,29 +188,42 @@ performance:
 
 A benchmark script is included, 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 for fetching rows as hashes](https://github.com/digital-fabric/extralite/blob/main/test/perf_hash.rb):
+shows Extralite to be up to ~12 times faster than `sqlite3` when fetching a
+large number of rows.
+
+### Rows as hashes
+
+ [Benchmark source code](https://github.com/digital-fabric/extralite/blob/main/test/perf_hash.rb)
 
 |Row count|sqlite3-ruby|Extralite|Advantage|
 |-:|-:|-:|-:|
-|10|57620 rows/s|95340 rows/s|__1.65x__|
-|1K|286.8K rows/s|2106.4 rows/s|__7.35x__|
-|100K|181K rows/s|2275.3K rows/s|__12.53x__|
+|10|75.3K rows/s|134.2K rows/s|__1.78x__|
+|1K|286.8K rows/s|2106.4K rows/s|__7.35x__|
+|100K|181.0K rows/s|2275.3K rows/s|__12.53x__|
+
+### Rows as arrays
 
-When [fetching rows as arrays](https://github.com/digital-fabric/extralite/blob/main/test/perf_ary.rb) Extralite also significantly outperforms sqlite3-ruby:
+[Benchmark source code](https://github.com/digital-fabric/extralite/blob/main/test/perf_ary.rb)
 
 |Row count|sqlite3-ruby|Extralite|Advantage|
 |-:|-:|-:|-:|
-|10|64365 rows/s|94031 rows/s|__1.46x__|
+|10|64.3K rows/s|94.0K rows/s|__1.46x__|
 |1K|498.9K rows/s|2478.2K rows/s|__4.97x__|
 |100K|441.1K rows/s|3023.4K rows/s|__6.85x__|
 
-(If you're interested in checking this yourself, just run the script and let me
-know if your results are better/worse.)
+### Prepared statements
+
+[Benchmark source code](https://github.com/digital-fabric/extralite/blob/main/test/perf_prepared.rb)
+
+|Row count|sqlite3-ruby|Extralite|Advantage|
+|-:|-:|-:|-:|
+|10|241.8K rows/s|888K rows/s|__3.67x__|
+|1K|298.6K rows/s|2606K rows/s|__8.73x__|
+|100K|201.6K rows/s|1934K rows/s|__9.6x__|
 
-As those benchmarks show, Extralite is capabale of reading more than 3M
-rows/second (when fetching rows as arrays), and more than 2.2M rows/second (when
-fetching rows as hashes.)
+As those benchmarks show, Extralite is capabale of reading up to 3M rows/second
+when fetching rows as arrays, and up to 2.6M rows/second when fetching
+rows as hashes.
 
 ## Contributing
 

data/Rakefile

@@ -16,7 +16,7 @@ task :test do
   exec 'ruby test/run.rb'
 end
 
-CLEAN.include '**/*.o', '**/*.so', '**/*.so.*', '**/*.a', '**/*.bundle', '**/*.jar', 'pkg', 'tmp'
+CLEAN.include 'lib/*.o', 'lib/*.so', 'lib/*.so.*', 'lib/*.a', 'lib/*.bundle', 'lib/*.jar', 'pkg', 'tmp'
 
 require 'yard'
 YARD_FILES = FileList['ext/extralite/extralite.c', 'lib/extralite.rb', 'lib/sequel/adapters/extralite.rb']

data/bin/update_sqlite_source

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+version = ARGV[0]
+raise "Please specify version" unless version
+
+require 'fileutils'
+require 'date'
+
+FileUtils.cd '/tmp'
+
+version_id = version.gsub('.', '')
+version_id += '0' * (7 - version_id.length)
+url = "https://sqlite.org/#{Date.today.year}/sqlite-amalgamation-#{version_id}.zip"
+dest = File.expand_path('../ext/extralite', __dir__)
+
+puts "Downloading from #{url}..."
+`curl #{url} > #{version_id}.zip`
+
+puts "Unzipping zip file..."
+`unzip -o #{version_id}.zip`
+
+puts "Copying source files"
+`cp sqlite-amalgamation-#{version_id}/sqlite3.* #{dest}/`
+
+puts 'Done updating source files'

data/ext/extralite/common.c

@@ -0,0 +1,347 @@
+#include <stdio.h>
+#include "extralite.h"
+
+static inline VALUE get_column_value(sqlite3_stmt *stmt, int col, int type) {
+  switch (type) {
+    case SQLITE_NULL:
+      return Qnil;
+    case SQLITE_INTEGER:
+      return LL2NUM(sqlite3_column_int64(stmt, col));
+    case SQLITE_FLOAT:
+      return DBL2NUM(sqlite3_column_double(stmt, col));
+    case SQLITE_TEXT:
+      return rb_str_new_cstr((char *)sqlite3_column_text(stmt, col));
+    case SQLITE_BLOB:
+      return rb_str_new((const char *)sqlite3_column_blob(stmt, col), (long)sqlite3_column_bytes(stmt, col));
+    default:
+      rb_raise(cError, "Unknown column type: %d", type);
+  }
+
+  return Qnil;
+}
+
+void bind_parameter_value(sqlite3_stmt *stmt, int pos, VALUE value);
+
+void bind_hash_parameter_values(sqlite3_stmt *stmt, VALUE hash) {
+  VALUE keys = rb_funcall(hash, ID_KEYS, 0);
+  long len = RARRAY_LEN(keys);
+  for (long 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);
+        break;
+      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);
+        break;
+      default:
+        rb_raise(cError, "Cannot bind hash key value idx %ld", i);
+    }
+  }
+  RB_GC_GUARD(keys);
+}
+
+inline void bind_parameter_value(sqlite3_stmt *stmt, int pos, VALUE value) {
+  switch (TYPE(value)) {
+    case T_NIL:
+      sqlite3_bind_null(stmt, pos);
+      return;
+    case T_FIXNUM:
+      sqlite3_bind_int64(stmt, pos, NUM2LL(value));
+      return;
+    case T_FLOAT:
+      sqlite3_bind_double(stmt, pos, NUM2DBL(value));
+      return;
+    case T_TRUE:
+      sqlite3_bind_int(stmt, pos, 1);
+      return;
+    case T_FALSE:
+      sqlite3_bind_int(stmt, pos, 0);
+      return;
+    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);
+  }
+}
+
+void bind_all_parameters(sqlite3_stmt *stmt, int argc, VALUE *argv) {
+  for (int i = 0; i < argc; i++) {
+    bind_parameter_value(stmt, i + 1, argv[i]);
+  }
+}
+
+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++) {
+    VALUE name = ID2SYM(rb_intern(sqlite3_column_name(stmt, i)));
+    rb_ary_push(arr, name);
+  }
+  return arr;
+}
+
+static inline VALUE row_to_hash(sqlite3_stmt *stmt, int column_count, VALUE column_names) {
+  VALUE row = rb_hash_new();
+  for (int i = 0; i < column_count; i++) {
+    VALUE value = get_column_value(stmt, i, sqlite3_column_type(stmt, i));
+    rb_hash_aset(row, RARRAY_AREF(column_names, i), value);
+  }
+  return row;
+}
+
+static inline VALUE row_to_ary(sqlite3_stmt *stmt, int column_count) {
+  VALUE row = rb_ary_new2(column_count);
+  for (int i = 0; i < column_count; i++) {
+    VALUE value = get_column_value(stmt, i, sqlite3_column_type(stmt, i));
+    rb_ary_push(row, value);
+  }
+  return row;
+}
+
+typedef struct {
+  sqlite3 *db;
+  sqlite3_stmt **stmt;
+  const char *str;
+  long len;
+  int rc;
+} prepare_stmt_ctx;
+
+void *prepare_multi_stmt_without_gvl(void *ptr) {
+  prepare_stmt_ctx *ctx = (prepare_stmt_ctx *)ptr;
+  const char *rest = NULL;
+  const char *str = ctx->str;
+  const char *end = ctx->str + ctx->len;
+  while (1) {
+    ctx->rc = sqlite3_prepare_v2(ctx->db, str, end - str, ctx->stmt, &rest);
+    if (ctx->rc) {
+      // error
+      sqlite3_finalize(*ctx->stmt);
+      return NULL;
+    }
+
+    if (rest == end) return NULL;
+
+    // perform current query, but discard its results
+    ctx->rc = sqlite3_step(*ctx->stmt);
+    sqlite3_finalize(*ctx->stmt);
+    switch (ctx->rc) {
+    case SQLITE_BUSY:
+    case SQLITE_ERROR:
+    case SQLITE_MISUSE:
+      return NULL;
+    }
+    str = rest;
+  }
+  return NULL;
+}
+
+/*
+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.
+*/
+void prepare_multi_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
+  prepare_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);
+  }
+}
+
+#define SQLITE_MULTI_STMT -1
+
+void *prepare_single_stmt_without_gvl(void *ptr) {
+  prepare_stmt_ctx *ctx = (prepare_stmt_ctx *)ptr;
+  const char *rest = NULL;
+  const char *str = ctx->str;
+  const char *end = ctx->str + ctx->len;
+
+  ctx->rc = sqlite3_prepare_v2(ctx->db, str, end - str, ctx->stmt, &rest);
+  if (ctx->rc)
+    goto discard_stmt;
+  else if (rest != end) {
+    ctx->rc = SQLITE_MULTI_STMT;
+    goto discard_stmt;
+  }
+  goto end;
+discard_stmt:
+  if (*ctx->stmt) {
+    sqlite3_finalize(*ctx->stmt);
+    *ctx->stmt = NULL;
+  }
+end:
+  return NULL;
+}
+
+void prepare_single_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
+  prepare_stmt_ctx ctx = {db, stmt, RSTRING_PTR(sql), RSTRING_LEN(sql), 0};
+  rb_thread_call_without_gvl(prepare_single_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));
+  case SQLITE_MULTI_STMT:
+    rb_raise(cSQLError, "A prepared statement does not accept SQL strings with multiple queries");
+  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;
+};
+
+void *stmt_iterate_without_gvl(void *ptr) {
+  struct step_ctx *ctx = (struct step_ctx *)ptr;
+  ctx->rc = sqlite3_step(ctx->stmt);
+  return NULL;
+}
+
+static 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:
+      return 0;
+    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 sqlite3_step: %d (please open an issue on https://github.com/digital-fabric/extralite)", ctx.rc);
+  }
+
+  return 0;
+}
+
+VALUE cleanup_stmt(query_ctx *ctx) {
+  if (ctx->stmt) sqlite3_finalize(ctx->stmt);
+  return Qnil;
+}
+
+VALUE safe_query_hash(query_ctx *ctx) {
+  VALUE result = ctx->self;
+  int yield_to_block = rb_block_given_p();
+  VALUE row;
+  int column_count;
+  VALUE column_names;
+
+  column_count = sqlite3_column_count(ctx->stmt);
+  column_names = get_column_names(ctx->stmt, column_count);
+
+  // block not given, so prepare the array of records to be returned
+  if (!yield_to_block) result = rb_ary_new();
+
+  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);
+  }
+
+  RB_GC_GUARD(column_names);
+  RB_GC_GUARD(row);
+  RB_GC_GUARD(result);
+  return result;
+}
+
+VALUE safe_query_ary(query_ctx *ctx) {
+  int column_count;
+  VALUE result = ctx->self;
+  int yield_to_block = rb_block_given_p();
+  VALUE row;
+
+  column_count = sqlite3_column_count(ctx->stmt);
+
+  // block not given, so prepare the array of records to be returned
+  if (!yield_to_block) result = rb_ary_new();
+
+  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);
+  }
+
+  RB_GC_GUARD(row);
+  RB_GC_GUARD(result);
+  return result;
+}
+
+VALUE safe_query_single_row(query_ctx *ctx) {
+  int column_count;
+  VALUE row = Qnil;
+  VALUE column_names;
+
+  column_count = sqlite3_column_count(ctx->stmt);
+  column_names = get_column_names(ctx->stmt, column_count);
+
+  if (stmt_iterate(ctx->stmt, ctx->sqlite3_db))
+    row = row_to_hash(ctx->stmt, column_count, column_names);
+
+  RB_GC_GUARD(row);
+  RB_GC_GUARD(column_names);
+  return row;
+}
+
+VALUE safe_query_single_column(query_ctx *ctx) {
+  int column_count;
+  VALUE result = ctx->self;
+  int yield_to_block = rb_block_given_p();
+  VALUE value;
+
+  column_count = sqlite3_column_count(ctx->stmt);
+  if (column_count != 1)
+    rb_raise(cError, "Expected query result to have 1 column");
+
+  // block not given, so prepare the array of records to be returned
+  if (!yield_to_block) result = rb_ary_new();
+
+  while (stmt_iterate(ctx->stmt, ctx->sqlite3_db)) {
+    value = get_column_value(ctx->stmt, 0, sqlite3_column_type(ctx->stmt, 0));
+    if (yield_to_block) rb_yield(value); else rb_ary_push(result, value);
+  }
+
+  RB_GC_GUARD(value);
+  RB_GC_GUARD(result);
+  return result;
+}
+
+VALUE safe_query_single_value(query_ctx *ctx) {
+  int column_count;
+  VALUE value = Qnil;
+
+  column_count = sqlite3_column_count(ctx->stmt);
+  if (column_count != 1)
+    rb_raise(cError, "Expected query result to have 1 column");
+
+  if (stmt_iterate(ctx->stmt, ctx->sqlite3_db))
+    value = get_column_value(ctx->stmt, 0, sqlite3_column_type(ctx->stmt, 0));
+
+  RB_GC_GUARD(value);
+  return value;
+}