extralite 2.7.1 → 2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cbb8c1507e23141a2b069306e31939b7cd5fea83e6941426972d7eeadc86ac0
-  data.tar.gz: e283cd0d2b18ed840020d73fb71d47696b64b8ff99c42a2a431928b6a25db189
+  metadata.gz: 4412f69118d15351524bd0065bc9c4624db0461bdc16b883ff4508e803b74ad4
+  data.tar.gz: de354d27438bf9e93118fbe551c05c0bb11dd6713d70e58714209fa8f64b36d8
 SHA512:
-  metadata.gz: cbe1b66c813d0e35bd667a06e14bc68673655807d256771dac231ecb2f559660a05773267ef804e40f9d747482974d897b78c0df370340c55e7cfd290bdc4a41
-  data.tar.gz: 385b3ec651b1c2365392c7a1dddb0b7b63adddc6ade662f8ba7d72d6d49f025dff0b55490df6296181d361ac5792e888ed7db90c8b11b2129b5d6474fae2c8de
+  metadata.gz: 2bf2897e5545c4f701cc2efa49c00c68ee976c44d955261014f31a5c949408298a3848b5ba6b9ca35aaea144183f8746d7cee032ef259a0cf1bf2b75ca32fbd4
+  data.tar.gz: de802356ba9f65089e1f9ff89b0af5d4032a8c5687ed33290b1ca0e4ff0bd8dbe8c674fe85a02eb1e94c2c5070b30db115aaef95d913a8d5bd4c51dbc68d62c6

data/.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby: ['3.0', '3.1', '3.2', '3.3']
+        ruby: ['3.0', '3.1', '3.2', '3.3', 'head']
 
     name: >-
       ${{matrix.os}}, ${{matrix.ruby}}

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 2.8 2024-03-10
+
+- Improve documentation.
+- Implement `Database#wal_checkpoint`.
+- Rename query modes: `hash` (the default mode), `array`, `splat`, simplify querying APIs.
+  [#69](https://github.com/digital-fabric/extralite/pull/69)
+
 # 2.7.1 2024-02-11
 
 - Fix API docs.
@@ -6,11 +13,11 @@
 
 - Improve progress handler API, add mode, period, tick options, global progress
   handler. [#68](https://github.com/digital-fabric/extralite/pull/68)
-- Rework `Database#initialize` options
-- Add argv row mode (for passing column values as argv)
-- Streamline and improve query methods
+- Rework `Database#initialize` options.
+- Add argv row mode (for passing column values as argv).
+- Streamline and improve query methods.
   [#67](https://github.com/digital-fabric/extralite/pull/67)
-- Implement row transforms
+- Implement row transforms.
 
 # 2.6 2024-01-23
 

data/README.md

@@ -141,10 +141,10 @@ single values, if you're just reading one column.
 For that purpose, Extralite offers three different ways, or modes, of retrieving
 records:
 
-- `:hash`: read rows as hashes (this is the default mode).
-- `:ary`: read rows as arrays.
-- `:argv`: similar to the `:ary`, except that for queries with a single column,
-  the single column value is returned.
+- `:hash`: retrieve each row as a hash (this is the default mode).
+- `:array`: retrieve each row as an array.
+- `:splat`: retrieve each row as one or more splatted values, without wrapping
+  them in a container (see [below](#the-splat-query-mode)).
 
 Extralite provides separate methods for the different modes:
 
@@ -152,9 +152,9 @@ Extralite provides separate methods for the different modes:
 # alias #query_hash
 db.query('select 1') #=> [{ "1" => 1 }]
 
-db.query_ary('select 1') #=> [[1]]
+db.query_array('select 1') #=> [[1]]
 
-db.query_argv('select 1') #=> [1]
+db.query_splat('select 1') #=> [1]
 ```
 
 Notice how all the return values above are arrays. This is because the different
@@ -163,19 +163,56 @@ get back a single row, use one of the `query_single_xxx` methods:
 
 ```ruby
 # alias #query_single_hash
-db.query('select 1') #=> { "1" => 1 }
+db.query_single('select 1') #=> { "1" => 1 }
 
-db.query_single_ary('select 1') #=> [1]
+db.query_single_array('select 1') #=> [1]
 
-db.query_single_argv('select 1') #=> 1
+db.query_single_splat('select 1') #=> 1
 ```
 
-## Parameter binding
+### Iterating Over Query Results with a Block
 
-As shown in the above example, the `#execute` and `#query_xxx` methods accept
-parameters that can be bound to the query, which means that their values will be
-used for each corresponding place-holder (expressed using `?`) in the SQL
-statement:
+In addition to getting query results as an array of rows, you can also directly
+iterate over the query results by providing a block to the different
+`#query_xxx` methods:
+
+```ruby
+db.query('select * from foo') { |row| handle_row(row) }
+```
+
+### The Splat Query Mode
+
+The splat query mode allows you to retrieve column values for each row without
+wrapping them in a container. This is useful especially when performing queries
+that return a single column:
+
+```ruby
+# When using the array mode we need to take unwrap the values
+ids = db.query_array('select id from tasks where active = 1').map { |r| r.first }
+
+# In splat mode we don't need to do that
+ids = db.query_splat('select id from tasks where active = 1')
+```
+
+The splat mode is also useful when iterating over records with a block. The
+column values are provided as splatted arguments to the given block:
+
+```ruby
+db.query_splat('select a, b, c from foo') do |a, b, c|
+  do_this_with(a, b)
+  do_that_with(c)
+end
+```
+
+When iterating over records in this manner, the splat mode is slightly faster
+than the array mode, and also reduces pressure on the Ruby GC since you avoid
+allocating arrays or hashes to hold the column values.
+
+## Parameter Binding
+
+The `#execute` and `#query_xxx` methods accept parameters that can be bound to
+the query, which means that their values will be used for each corresponding
+place-holder (expressed using `?`) in the SQL statement:
 
 ```ruby
 db.query('select x from my_table where y = ? and z = ?', 'foo', 'bar')
@@ -224,14 +261,14 @@ values:
 - `String` (see below)
 - nil
 
-### Boolean values
+### Boolean Values
 
 SQLite does not have a boolean data type. Extralite will automatically translate
 bound parameter values of `true` or `false` to the integer values `1` and `0`,
 respectively. Note that boolean values stored in the database will be fetched as
 integers.
 
-### String values
+### String Values
 
 String parameter values are translated by Extralite to either `TEXT` or `BLOB`
 values according to the string encoding used. Strings with an `ASCII-8BIT` are
@@ -269,12 +306,12 @@ db.query(transform, 'select * from foo')
 #=> rows as instances of MyModel
 ```
 
-When using the `argv` mode, the different column values are passed as individual
+When using the `splat` mode, the different column values are passed as splatted
 values to the transform proc:
 
 ```ruby
 transform = ->(a, b, c) { { a:a, b: b, c: JSON.parse(c) } }
-db.query_argv(transform, 'select a, b, c from foo')
+db.query_splat(transform, 'select a, b, c from foo')
 #=> transformed rows
 ```
 
@@ -325,16 +362,16 @@ three different modes: as a hash, an array or as individual column values. To
 set the mode, you can use one of the `#prepare_xxx` methods:
 
 ```ruby
-# hash mode
+# hash mode (alias #prepare_hash)
 db.prepare('select * from foo').to_a
 #=> [{ x: 1, y: 2, z: 3}]
 
-# argv mode
-db.prepare_argv('select x from foo').to_a
+# splat mode
+db.prepare_splat('select x from foo').to_a
 #=> [1]
 
-# ary mode
-db.prepare_ary('select * from foo').to_a
+# array mode
+db.prepare_array('select * from foo').to_a
 #=> [[1, 2, 3]]
 ```
 
@@ -345,7 +382,7 @@ q = db.prepare('select * from foo')
 q.to_a #=> [{ x: 1, y: 2, z: 3}]
 
 q.mode #=> :hash
-q.mode = :ary
+q.mode = :array
 q.to_a "=> [[1, 2, 3]]
 ```
 
@@ -368,12 +405,12 @@ query.next(10)
 #=> [{ x: 1, y: 2, z: 3 }, { x: 4, y: 5, z: 6 }]
 
 # Fetch the next row as an array
-query = db.prepare_ary('select * from foo')
+query = db.prepare_array('select * from foo')
 query.next
 #=> [1, 2, 3]
 
 # Fetch the next row as a single column
-db.prepare_argv('select z from foo').next
+db.prepare_splat('select z from foo').next
 #=> 3
 ```
 
@@ -400,11 +437,11 @@ query = db.prepare('select * from foo')
 query.each { |r| ... }
 
 # iterate over records as arrays
-query = db.prepare_ary('select * from foo')
+query = db.prepare_array('select * from foo')
 query.each { |r| ... }
 
 # iterate over records as single values
-query = db.prepare_argv('select a, b, c from foo')
+query = db.prepare_splat('select a, b, c from foo')
 query.each { |a, b, c| ... }
 ```
 
@@ -429,7 +466,7 @@ instantiate an iterator explicitly:
 
 ```ruby
 # You need to pass the query to iterate over:
-iterator = Extralite::Iterator(query)
+iterator = Extralite::Iterator.new(query)
 iterator.each { |r| ... }
 ```
 
@@ -437,7 +474,7 @@ iterator.each { |r| ... }
 
 Prepared queries can automatically transform their result sets by setting a
 transform block. The transform block receives values according to the query mode
-(hash, array or argv). To set a transform you can pass a block to one of the
+(hash, array or splat). To set a transform you can pass a block to one of the
 `Database#prepare_xxx` methods, or use `Query#transform`:
 
 ```ruby
@@ -449,12 +486,12 @@ q = db.prepare('select * from items where id = ?')
 q.transform { |h| Item.new(h) }
 ```
 
-The same can be done for queries in `argv` or `ary` mode:
+The same can be done for queries in `splat` or `array` mode:
 
 ```ruby
-db.prepare_argv('select * from foo') { |a, b, c| a + b + c }
+db.prepare_splat('select * from foo') { |a, b, c| a + b + c }
 
-db.prepare_ary('select * from foo') { |a| a.map(&:to_s).join }
+db.prepare_array('select * from foo') { |a| a.map(&:to_s).join }
 ```
 
 ## Batch Execution of Queries
@@ -640,7 +677,7 @@ end
 
 ## Database Information
 
-### Getting the list of tables
+### Getting the List of Tables
 
 To get the list of tables in a database, use the `#tables` method:
 
@@ -657,7 +694,7 @@ db.tables('foo')
 #=> [...]
 ```
 
-### Getting the last insert row id
+### Getting the Last Insert Row Id
 
 ```ruby
 db.execute 'insert into foo values (?)', 42
@@ -665,7 +702,7 @@ db.last_insert_rowid
 #=> 1
 ```
 
-### Getting the columns names for a given query
+### Getting the Column Names for a Given Query
 
 ```ruby
 db.columns('select a, b, c from foo')
@@ -1220,13 +1257,13 @@ code](https://github.com/digital-fabric/extralite/blob/main/test/perf_hash.rb)
 ### Rows as Arrays
 
 [Benchmark source
-code](https://github.com/digital-fabric/extralite/blob/main/test/perf_ary.rb)
+code](https://github.com/digital-fabric/extralite/blob/main/test/perf_array.rb)
 
 |Row count|sqlite3 1.7.0|Extralite 2.5|Advantage|
 |-:|-:|-:|-:|
-|10|276.9K rows/s|472.3K rows/s|__1.71x__|
-|1K|615.6K rows/s|2324.3K rows/s|__3.78x__|
-|100K|477.4K rows/s|1982.7K rows/s|__4.15x__|
+|10|278.0K rows/s|493.6K rows/s|__1.78x__|
+|1K|608.6K rows/s|2692.2K rows/s|__4.42x__|
+|100K|502.9K rows/s|2564.0K rows/s|__5.10x__|
 
 ### Prepared Queries (Prepared Statements)
 
@@ -1239,7 +1276,7 @@ code](https://github.com/digital-fabric/extralite/blob/main/test/perf_hash_prepa
 |1K|296.5K rows/s|2396.2K rows/s|__8.08x__|
 |100K|145.9K rows/s|2107.3K rows/s|__14.45x__|
 
-As those benchmarks show, Extralite is capabale of reading up to 2.4M rows per
+As those benchmarks show, Extralite is capabale of reading up to 2.7M rows per
 second, and can be more than 14 times faster than the `sqlite3` gem.
 
 Note that the benchmarks above were performed on synthetic data, in a

data/examples/kv_store.rb

@@ -24,7 +24,7 @@ class KVStore
   end
 
   def setup_queries
-    @q_get = @db.prepare_argv('select value from kv where key = ?')
+    @q_get = @db.prepare_splat('select value from kv where key = ?')
     @q_set = @db.prepare('insert into kv (key, value) values($1, $2) on conflict (key) do update set value = $2')
   end
 

data/examples/pubsub_store_polyphony.rb

@@ -42,7 +42,7 @@ class PubSub
 
   def get_messages(&block)
     #   @db.execute('update subscribers set stamp = ? where id = ?', Time.now.to_i, @id)
-      @db.query_argv('delete from messages where subscriber_id = ? returning topic, message', @id, &block)
+      @db.query_splat('delete from messages where subscriber_id = ? returning topic, message', @id, &block)
   end
 
   SCHEMA = <<~SQL
@@ -174,7 +174,7 @@ while true
   elapsed = now - last_t
   d_publish = publish_count - last_publish_count
   d_receive = receive_count - last_receive_count
-  pending = db4.query_single_argv('select count(*) from messages')
+  pending = db4.query_single_splat('select count(*) from messages')
   puts "#{Time.now} publish: #{d_publish/elapsed}/s receive: #{d_receive/elapsed}/s pending: #{pending}"
   last_t = now
   last_publish_count = publish_count

data/examples/pubsub_store_threads.rb

@@ -35,14 +35,14 @@ class PubSub
 
   def get_messages(&block)
     @db.transaction(:deferred) do
-      results = @db.query_ary('select topic, message from messages where subscriber_id = ?', @id)
+      results = @db.query_array('select topic, message from messages where subscriber_id = ?', @id)
       return [] if results.empty?
 
       @db.execute('delete from messages where subscriber_id = ?', @id)
       results
     end
 
-      # messages = @db.query_ary('delete from messages where subscriber_id = ? returning topic, message', @id)
+      # messages = @db.query_array('delete from messages where subscriber_id = ? returning topic, message', @id)
       # if block
       #   messages.each(&block)
       #   nil
@@ -196,7 +196,7 @@ while true
   d_publish = publish_count - last_publish_count
   d_receive = receive_count - last_receive_count
 
-  count = db4.query_single_argv('select count(*) from messages')
+  count = db4.query_single_splat('select count(*) from messages')
   puts "#{Time.now} publish: #{d_publish/elapsed}/s receive: #{d_receive/elapsed}/s pending: #{count}"
   last_t = now
   last_publish_count = publish_count

data/ext/extralite/changeset.c

@@ -339,7 +339,7 @@ VALUE Changeset_to_a(VALUE self) {
 
 // copied from: https://sqlite.org/sessionintro.html
 static int xConflict(void *pCtx, int eConflict, sqlite3_changeset_iter *pIter){
-  int ret = (int)pCtx;
+  long ret = (long)pCtx;
   return ret;
 }
 

data/ext/extralite/common.c

@@ -153,7 +153,7 @@ static inline VALUE row_to_hash(sqlite3_stmt *stmt, int column_count, VALUE colu
   return row;
 }
 
-static inline VALUE row_to_ary(sqlite3_stmt *stmt, int column_count) {
+static inline VALUE row_to_array(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));
@@ -162,7 +162,7 @@ static inline VALUE row_to_ary(sqlite3_stmt *stmt, int column_count) {
   return row;
 }
 
-static inline void row_to_argv_values(sqlite3_stmt *stmt, int column_count, VALUE *values) {
+static inline void row_to_splat_values(sqlite3_stmt *stmt, int column_count, VALUE *values) {
   for (int i = 0; i < column_count; i++) {
     values[i] = get_column_value(stmt, i, sqlite3_column_type(stmt, i));
   }
@@ -321,7 +321,7 @@ VALUE cleanup_stmt(query_ctx *ctx) {
   return Qnil;
 }
 
-VALUE safe_query_argv(query_ctx *ctx);
+VALUE safe_query_splat(query_ctx *ctx);
 
 VALUE safe_query_hash(query_ctx *ctx) {
   VALUE array = ROW_MULTI_P(ctx->row_mode) ? rb_ary_new() : Qnil;
@@ -369,13 +369,13 @@ VALUE safe_query_hash(query_ctx *ctx) {
   RB_GC_GUARD(values[7])
 
 #define ARGV_GET_ROW(ctx, column_count, argv_values, row, do_transform, return_rows) \
-  row_to_argv_values(ctx->stmt, column_count, argv_values); \
+  row_to_splat_values(ctx->stmt, column_count, argv_values); \
   if (do_transform) \
     row = rb_funcall2(ctx->transform_proc, ID_call, column_count, argv_values); \
   else if (return_rows) \
     row = column_count == 1 ? argv_values[0] : rb_ary_new_from_values(column_count, argv_values);
 
-VALUE safe_query_argv(query_ctx *ctx) {
+VALUE safe_query_splat(query_ctx *ctx) {
   VALUE array = ROW_MULTI_P(ctx->row_mode) ? rb_ary_new() : Qnil;
   VALUE argv_values[MAX_ARGV_COLUMNS] = NIL_ARGV_VALUES;
   VALUE row = Qnil;
@@ -413,7 +413,7 @@ VALUE safe_query_argv(query_ctx *ctx) {
   return ROW_MULTI_P(ctx->row_mode) ? array : Qnil;
 }
 
-VALUE safe_query_ary(query_ctx *ctx) {
+VALUE safe_query_array(query_ctx *ctx) {
   VALUE array = ROW_MULTI_P(ctx->row_mode) ? rb_ary_new() : Qnil;
   VALUE row = Qnil;
   int column_count = sqlite3_column_count(ctx->stmt);
@@ -421,7 +421,7 @@ VALUE safe_query_ary(query_ctx *ctx) {
   int do_transform = !NIL_P(ctx->transform_proc);
 
   while (stmt_iterate(ctx)) {
-    row = row_to_ary(ctx->stmt, column_count);
+    row = row_to_array(ctx->stmt, column_count);
     if (do_transform)
       row = rb_funcall(ctx->transform_proc, ID_call, 1, row);
     row_count++;
@@ -463,7 +463,7 @@ VALUE safe_query_single_row_hash(query_ctx *ctx) {
   return row;
 }
 
-VALUE safe_query_single_row_argv(query_ctx *ctx) {
+VALUE safe_query_single_row_splat(query_ctx *ctx) {
   VALUE argv_values[MAX_ARGV_COLUMNS] = NIL_ARGV_VALUES;
   VALUE row = Qnil;
   int column_count = sqlite3_column_count(ctx->stmt);
@@ -480,13 +480,13 @@ VALUE safe_query_single_row_argv(query_ctx *ctx) {
   return row;
 }
 
-VALUE safe_query_single_row_ary(query_ctx *ctx) {
+VALUE safe_query_single_row_array(query_ctx *ctx) {
   int column_count = sqlite3_column_count(ctx->stmt);
   VALUE row = Qnil;
   int do_transform = !NIL_P(ctx->transform_proc);
 
   if (stmt_iterate(ctx)) {
-    row = row_to_ary(ctx->stmt, column_count);
+    row = row_to_array(ctx->stmt, column_count);
     if (do_transform)
       row = rb_funcall(ctx->transform_proc, ID_call, 1, row);
   }
@@ -498,8 +498,8 @@ VALUE safe_query_single_row_ary(query_ctx *ctx) {
 enum batch_mode {
   BATCH_EXECUTE,
   BATCH_QUERY_HASH,
-  BATCH_QUERY_ARGV,
-  BATCH_QUERY_ARY,
+  BATCH_QUERY_SPLAT,
+  BATCH_QUERY_ARRAY,
 };
 
 static inline VALUE batch_iterate_hash(query_ctx *ctx) {
@@ -522,14 +522,14 @@ static inline VALUE batch_iterate_hash(query_ctx *ctx) {
   return rows;
 }
 
-static inline VALUE batch_iterate_ary(query_ctx *ctx) {
+static inline VALUE batch_iterate_array(query_ctx *ctx) {
   VALUE rows = rb_ary_new();
   VALUE row = Qnil;
   int column_count = sqlite3_column_count(ctx->stmt);
   int do_transform = !NIL_P(ctx->transform_proc);
 
   while (stmt_iterate(ctx)) {
-    row = row_to_ary(ctx->stmt, column_count);
+    row = row_to_array(ctx->stmt, column_count);
     if (do_transform)
       row = rb_funcall(ctx->transform_proc, ID_call, 1, row);
     rb_ary_push(rows, row);
@@ -540,7 +540,7 @@ static inline VALUE batch_iterate_ary(query_ctx *ctx) {
   return rows;
 }
 
-static inline VALUE batch_iterate_argv(query_ctx *ctx) {
+static inline VALUE batch_iterate_splat(query_ctx *ctx) {
   VALUE rows = rb_ary_new();
   VALUE argv_values[MAX_ARGV_COLUMNS] = NIL_ARGV_VALUES;
   VALUE row = Qnil;
@@ -568,11 +568,11 @@ static inline void batch_iterate(query_ctx *ctx, enum batch_mode mode, VALUE *ro
     case BATCH_QUERY_HASH:
       *rows = batch_iterate_hash(ctx);
       break;
-    case BATCH_QUERY_ARGV:
-      *rows = batch_iterate_argv(ctx);
+    case BATCH_QUERY_SPLAT:
+      *rows = batch_iterate_splat(ctx);
       break;
-    case BATCH_QUERY_ARY:
-      *rows = batch_iterate_ary(ctx);
+    case BATCH_QUERY_ARRAY:
+      *rows = batch_iterate_array(ctx);
       break;
   }
 }
@@ -715,21 +715,21 @@ VALUE safe_batch_query(query_ctx *ctx) {
   switch (ctx->query_mode) {
     case QUERY_HASH:
       return batch_run(ctx, BATCH_QUERY_HASH);
-    case QUERY_ARGV:
-      return batch_run(ctx, BATCH_QUERY_ARGV);
-    case QUERY_ARY:
-      return batch_run(ctx, BATCH_QUERY_ARY);
+    case QUERY_SPLAT:
+      return batch_run(ctx, BATCH_QUERY_SPLAT);
+    case QUERY_ARRAY:
+      return batch_run(ctx, BATCH_QUERY_ARRAY);
     default:
       rb_raise(cError, "Invalid query mode (safe_batch_query)");
   }  
 }
 
-VALUE safe_batch_query_ary(query_ctx *ctx) {
-  return batch_run(ctx, BATCH_QUERY_ARY);
+VALUE safe_batch_query_array(query_ctx *ctx) {
+  return batch_run(ctx, BATCH_QUERY_ARRAY);
 }
 
-VALUE safe_batch_query_argv(query_ctx *ctx) {
-  return batch_run(ctx, BATCH_QUERY_ARGV);
+VALUE safe_batch_query_splat(query_ctx *ctx) {
+  return batch_run(ctx, BATCH_QUERY_SPLAT);
 }
 
 VALUE safe_query_columns(query_ctx *ctx) {