extralite-bundle 3.1.0 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c98b87050195caee2a3ac6bbbefdd3bf77ed3fe29add59cf18d5162299856d93
-  data.tar.gz: b0796d7fba1df64d3095d29ff6d8f00bb6f66320467cf54d0ab6f31a164c7c59
+  metadata.gz: 9eac653308555c057d121db6b0e17905fff645a62d926bdd3ac07323f40f8f9e
+  data.tar.gz: 2bcfeb952ce57afa647b969016891edae0fd615fc78f97a0a6b0336cc35791d6
 SHA512:
-  metadata.gz: 34f204b0d4abf91ac7b2f114c2e6838515498a068e750c476c7c473a3823e33f871088974b204aed8e98192c1bcfbdec2f8d5f2df1bff770a523724e662a79b7
-  data.tar.gz: c6b48bf9540dd37a663ab21db610f6aeee0193a3cf539b5cff8ba600475b15cc91c9e8679f7c0a897af0b227b39f597aa8d2da4b378c6a5c2d8aaf64d6a6dc49
+  metadata.gz: aa4d929c51e1f2c05fc0e67aa37447281c50d697b9dff242ca6f96e3723027e03b3db5b4c437399f28045a12d251dfff3e0f3a47709302b132347cca9c7fa514
+  data.tar.gz: 9809ca98906d5b853e646814057b976a55171249ae85b0502eea8ab39032d725889d736d3e9eff71ee46c9ca31d64e81f42102936753e69a2714188abec3bca5

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 3.1.2 2026-10-03
+
+- Fix handling of failed BEGIN in #transaction (#89)
+- Reset of cached statements post-query (#88)
+- Add missing wal checkpoint, integrity_check docs to README
+- Implement `Database#integrity_check`, `Database#quick_check`
+
+# 3.1.1 2026-09-26
+
+- Fix clearing of stmt cache after `DB#close` or after GC (#87)
+
 # 3.1.0 2026-09-22
 
 - Update bundled SQLite to 3.53.4

data/Gemfile

@@ -1,7 +1,3 @@
 source 'https://rubygems.org'
 
 gemspec name: 'extralite'
-
-group :development do
-  gem "ruby_memcheck", "2.3.0" if Gem::Platform.local.os == "linux"
-end

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Sharon Rosner
+Copyright (c) 2026 Sharon Rosner
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -49,14 +49,14 @@ latest features and enhancements.
   allowing iterating through single records or batches of records.
 - [Prepared queries](#prepared-queries).
 - [Parameter binding](#parameter-binding).
-- [Automatic query caching] for queries with parameters.
+- [Automatic query caching](#automatic-query-caching) for parametric queries.
 - [Batch execution](#batch-execution-of-queries) of queries.
 - [transactions and savepoints](#transactions-and-savepoints).
 - Advanced features: load [SQLite extensions](#loading-extensions), create
   [backups](#creating-backups), retrieve [status
   information](#retrieving-status-information), work with
   [changesets](#working-with-changesets), interrogate [database
-  limits](#working-with-database-limits), [trace](#tracing-sql-statements)
+  limits](#working-with-database-limits), [trace](#tracing-sql-statements), [WAL checkpoints](#wal-checkpoints), and run [integrity checks](#integrity-checks).
   queries.
 - [Sequel](#usage-with-sequel) adapter.
 
@@ -363,6 +363,16 @@ To use the transform, pass it along with the SQL string to `Database#query`:
 db.qurey(transform, sql) #=> [...]
 ```
 
+Structured transforms support the following column types:
+
+- `integer`
+- `float`
+- `text`
+- `bool` - represented as an integer value of 0/1.
+- `json` - represented as a string (text).
+- A custom proc/lambda - e.g. `->(v) { v.split(',') }`.
+- `auto` - uses the native database data type.
+
 Transforms can also be used with [prepared
 queries](#transforms-in-prepared-queries).
 
@@ -1303,6 +1313,31 @@ db.query('select ?, ?', 1, 2)
 # { sql: "select ?, ?", args: [1, 2] }
 ```
 
+### WAL Checkpoints
+
+Exrtralite lets you manually perform a WAL checkpoint in order to truncate the
+WAL file at any given moment using the `Database#wal_checkpoint` method:
+
+```ruby
+db.wal_checkpoint(:full)
+```
+
+The `#wal_checkpoint` method takes a mode argument, which should be one
+`:passive`, `:full`, `:restart`, `:truncate`. For a discussion of the different
+modes, you can refer to the [SQLite
+documentation](https://sqlite.org/c3ref/wal_checkpoint_v2.html).
+
+### Integrity Checks
+
+Extralite provides two methods for performing integrity checks,
+`Database#integrity_check` and `Database#quick_check`, which map to the
+corresponding pragmas. The two methods return an array of error messages. In the
+case of a normal, uncorrupted database, the methods will return `['ok']`:
+
+```ruby
+db.integrity_check #=> ['ok'] (hopefully)
+```
+
 ## Usage with Sequel
 
 Extralite includes an adapter for

data/TODO.md

@@ -1,3 +1,9 @@
+## Remove Query objects
+
+- Remove Query
+- Cleanup code
+- Update README
+
 ## Transforms
 
 - Add ability to exclude a column:

data/ext/extralite/common.c

@@ -226,6 +226,8 @@ static inline void finalize_stmt_ctx(stmt_ctx *ctx) {
     return;
   }
 
+  sqlite3_reset(*(ctx->stmtptr));
+  sqlite3_clear_bindings(*(ctx->stmtptr));
   if (!(ctx->flags & STMT_CTX_F_CACHE_HIT))
     rb_hash_aset(ctx->stmt_cache, ctx->sql, ULONG2NUM((uint64_t)*(ctx->stmtptr)));
 }
@@ -241,11 +243,7 @@ void make_stmt_ctx(
 
   int use_cache = (argc > 0) && (db->flags & DB_F_STMT_CACHE);
   ctx->flags = use_cache ? STMT_CTX_F_USE_CACHE : 0;
-  if (use_cache) {
-    lookup_cache_entry(ctx);
-    if (ctx->flags & STMT_CTX_F_CACHE_HIT)
-      sqlite3_clear_bindings(*(ctx->stmtptr));
-  }
+  if (use_cache) lookup_cache_entry(ctx);
 
   if (!use_cache || !(*(ctx->stmtptr))) {
     ctx->str = RSTRING_PTR(sql);
@@ -318,6 +316,7 @@ void *exec_multi_stmt_impl(void *ptr) {
         int res = sqlite3_prepare_v2(ctx->db, rest, end-rest, &next_stmt, NULL);
         if (next_stmt) res = SQLITE_MISUSE;
         if (res != SQLITE_OK) {
+          ctx->flags &= ~STMT_CTX_F_USE_CACHE;
           ctx->rc = res;
           goto done;
         }
@@ -367,6 +366,7 @@ int exec_multi_stmt(stmt_ctx *ctx) {
   if (ctx->rc == SQLITE_OK) return ctx->total_changes;
 
   if (*(ctx->stmtptr)) sqlite3_finalize(*(ctx->stmtptr));
+
   return raise_error(ctx);
 }
 
@@ -403,6 +403,7 @@ void prep_single_stmt(stmt_ctx *ctx) {
   if (ctx->rc == SQLITE_OK) return;
 
   if (*(ctx->stmtptr)) sqlite3_finalize(*(ctx->stmtptr));
+
   raise_error(ctx);
 }
 
@@ -453,12 +454,14 @@ inline int stmt_iterate(query_ctx *ctx) {
 VALUE cleanup_stmt(query_ctx *ctx) {
   if (!ctx->stmt) goto done;
 
-  if (ctx->flags & STMT_CTX_F_USE_CACHE) {
+  if (!(ctx->flags & STMT_CTX_F_USE_CACHE))
+    sqlite3_finalize(ctx->stmt);
+  else {
+    sqlite3_reset(ctx->stmt);
+    sqlite3_clear_bindings(ctx->stmt);
     if (!(ctx->flags & STMT_CTX_F_CACHE_HIT))
       rb_hash_aset(ctx->db->stmt_cache, ctx->sql, ULONG2NUM((uint64_t)(ctx->stmt)));
   }
-  else
-    sqlite3_finalize(ctx->stmt);
 done:
   return Qnil;
 }
@@ -600,8 +603,6 @@ VALUE run_transform_no_identity(
 static inline VALUE run_transform(
   VALUE identity_storage, struct transform_node *node, sqlite3_stmt *stmt
 ) {
-  // fprintf(stdout, "transform_container: %p flags: %02x identity_idx: %d\n", node, node->flags, node->identity_idx);
-  // if (node->flags & TRANSFORM_F_NAME) INSPECT("  name", node->name);
   if (node->identity_node) {
     return run_transform_with_identity(identity_storage, node, stmt);
   }

data/ext/extralite/database.c

@@ -72,9 +72,26 @@ static void Database_compact(void *ptr) {
   db->progress_handler.proc = rb_gc_location(db->progress_handler.proc);
 }
 
+static int stmt_cache_iter(VALUE key, VALUE value, VALUE _param) {
+  sqlite3_stmt *stmt = (sqlite3_stmt *)NUM2ULONG(value);
+  sqlite3_finalize(stmt);
+  return ST_CONTINUE;
+}
+
+static void stmt_cache_finalize(sqlite3 *db, VALUE stmt_cache) {
+  if (stmt_cache == Qnil) return;
+  if (rb_hash_size_num(stmt_cache) == 0) return;
+
+  rb_hash_foreach(stmt_cache, stmt_cache_iter, Qnil);
+  RB_GC_GUARD(stmt_cache);
+}
+
 static void Database_free(void *ptr) {
   Database_t *db = ptr;
-  if (db->sqlite3_db) sqlite3_close_v2(db->sqlite3_db);
+  if (db->sqlite3_db) {
+    stmt_cache_finalize(db->sqlite3_db, db->stmt_cache);
+    sqlite3_close_v2(db->sqlite3_db);
+  }
   free(ptr);
 }
 
@@ -261,6 +278,8 @@ VALUE Database_close(VALUE self) {
   int rc;
   Database_t *db = self_to_database(self);
 
+  stmt_cache_finalize(db->sqlite3_db, db->stmt_cache);
+  rb_hash_clear(db->stmt_cache);
   rc = sqlite3_close_v2(db->sqlite3_db);
   if (rc) {
     rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
@@ -573,13 +592,14 @@ VALUE Database_batch_execute(VALUE self, VALUE sql, VALUE parameters) {
   if (RSTRING_LEN(sql) == 0) return Qnil;
 
   stmt_ctx stmt_ctx;
-  make_stmt_ctx(&stmt_ctx, db, &stmt, sql, RARRAY_LEN(parameters), NULL);
+  make_stmt_ctx(&stmt_ctx, db, &stmt, sql, 1, NULL);
   prep_single_stmt(&stmt_ctx);
   // prepare_xsingle_stmt(DB_GVL_MODE(db), db->stmt_cache, db->sqlite3_db, &stmt, sql, 0, NULL);
   query_ctx ctx = QUERY_CTX(
     self, sql, db, stmt, parameters,
     Qnil, QUERY_HASH, ROW_MULTI, ALL_ROWS
   );
+  ctx.flags = stmt_ctx.flags;
 
   return rb_ensure(SAFE(safe_batch_execute), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
 }
@@ -1545,11 +1565,11 @@ int checkpoint_mode_symbol_to_int(VALUE mode) {
  *
  * @overload wal_checkpoint(mode)
  *   @param mode [Symbol] checkpoint mode (`:passive`, `:full`, `:restart`, `:truncate`)
- *   @return [Array<int>] total and checkpointed frame count
+ *   @return [Array<Integer>] total and checkpointed frame count
  * @overload wal_checkpoint(mode, db_name)
  *   @param mode [Symbol] checkpoint mode (`:passive`, `:full`, `:restart`, `:truncate`)
  *   @param db_name [String] attached database name
- *   @return [Array<int>] total and checkpointed frame count
+ *   @return [Array<Integer>] total and checkpointed frame count
 */
 VALUE Database_wal_checkpoint(int argc, VALUE *argv, VALUE self) {
   Database_t *db = self_to_open_database(self);

data/gemspec.rb

@@ -19,7 +19,7 @@ def common_spec(s)
 
   s.add_development_dependency  'rake-compiler',        '1.3.1'
   s.add_development_dependency  'minitest'
-  s.add_development_dependency  'simplecov',            '0.22.0'
-  s.add_development_dependency  'yard',                 '0.9.38'
-  s.add_development_dependency  'sequel',               '5.105.0'
+  s.add_development_dependency  'simplecov'
+  s.add_development_dependency  'yard'
+  s.add_development_dependency  'sequel',               '5.108.0'
 end

data/lib/extralite/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Extralite
-  VERSION = '3.1.0'
+  VERSION = '3.1.2'
 end

data/lib/extralite.rb

@@ -215,6 +215,29 @@ module Extralite
       value.is_a?(Hash) ? pragma_set(value) : pragma_get(value)
     end
 
+    # Performs a low-level formatting and consistency check of the database
+    # using PRAGMA integrity_check. See:
+    # https://www.sqlite.org/pragma.html#pragma_integrity_check
+    #
+    # @param v [Integer, String, nil] max errors or table name
+    # @return [Array<String>] array of error strings or 'ok'
+    def integrity_check(v = nil)
+      query_splat(
+        v ? "pragma integrity_check(#{v})" : 'pragma integrity_check'
+      )
+    end
+
+    # Performs a quicker integrity check of the database using PRAGMA
+    # quick_check. See: https://www.sqlite.org/pragma.html#pragma_quick_check
+    #
+    # @param v [Integer, String, nil] max errors or table name
+    # @return [Array<String>] array of error strings or 'ok'
+    def quick_check(v = nil)
+      query_splat(
+        v ? "pragma quick_check(#{v})" : 'pragma quick_check'
+      )
+    end
+
     # Error class used to roll back a transaction without propagating an
     # exception.
     class Rollback < Error
@@ -237,12 +260,13 @@ module Extralite
     def transaction(mode = :immediate)
       abort = false
       execute "begin #{mode} transaction"
+      started = true
       yield self
     rescue => e
       abort = true
       e.is_a?(Rollback) ? nil : raise
     ensure
-      execute(abort ? 'rollback' : 'commit')
+      execute(abort ? 'rollback' : 'commit') if started
     end
 
     # Creates a savepoint with the given name. For more information on

data/test/helper.rb

@@ -16,3 +16,13 @@ module Minitest::Assertions
     assert exp_range.include?(act), msg
   end
 end
+
+module TestExtensions
+  def teardown
+    @db = nil
+    GC.start
+    super
+  end
+end
+
+Minitest::Test.prepend(TestExtensions)

data/test/test_database.rb

@@ -372,6 +372,86 @@ class DatabaseTest < Minitest::Test
     # assert_equal 1, @db.pragma('foreign_keys')
   end
 
+  def test_integrity_check_ok
+    r = @db.integrity_check
+    assert_equal ['ok'], r
+  end
+
+  def test_integrity_check_bad_var
+    assert_raises(Extralite::Error) { @db.integrity_check('foobar') }
+  end
+
+  def test_integrity_check_damaged
+    fn = Tempfile.new('extralite_test_integrity_check_damaged').path
+    db = Extralite::Database.new(fn)
+
+    db.execute <<~SQL
+      create table foo (x);
+    SQL
+
+    db.batch_execute("insert into foo values (?)", 1..100)
+
+    assert_equal (1..100).to_a, db.query_splat('select * from foo')
+    db.close
+
+    File.open(fn, 'r+b') do |f|
+      1.times do
+        f.seek(8015)
+        f.write('\x00' * 16)
+      end
+    end
+
+    db = Extralite::Database.new(fn, legacy: true)
+    assert_raises(Extralite::Error) { db.query_splat('select * from foo') }
+    r = db.integrity_check
+    assert_equal 2, r.size
+    assert_equal 'database disk image is malformed', r[1]
+
+    r = db.integrity_check(1)
+    assert_equal 1, r.size
+    assert_match /^\*\*\* in database main \*\*\*/, r[0]
+  end
+
+  def test_quick_check_ok
+    r = @db.quick_check
+    assert_equal ['ok'], r
+  end
+
+  def test_quick_check_bad_var
+    assert_raises(Extralite::Error) { @db.quick_check('foobar') }
+  end
+
+  def test_quick_check_damaged
+    fn = Tempfile.new('extralite_test_quick_check_damaged').path
+    db = Extralite::Database.new(fn)
+
+    db.execute <<~SQL
+      create table foo (x);
+    SQL
+
+    db.batch_execute("insert into foo values (?)", 1..100)
+
+    assert_equal (1..100).to_a, db.query_splat('select * from foo')
+    db.close
+
+    File.open(fn, 'r+b') do |f|
+      1.times do
+        f.seek(8015)
+        f.write('\x00' * 16)
+      end
+    end
+
+    db = Extralite::Database.new(fn, legacy: true)
+    assert_raises(Extralite::Error) { db.query_splat('select * from foo') }
+    r = db.quick_check
+    assert_equal 2, r.size
+    assert_equal 'database disk image is malformed', r[1]
+
+    r = db.integrity_check(1)
+    assert_equal 1, r.size
+    assert_match /^\*\*\* in database main \*\*\*/, r[0]
+  end
+
   def test_execute
     changes = @db.execute('update t set x = 42')
     assert_equal 2, changes
@@ -2225,4 +2305,70 @@ class StmtCacheText < Minitest::Test
     assert_equal [{ x: 42 }], rows
     assert_equal({}, @db.stmt_cache)
   end
+
+  def test_stmt_cache_close
+    fn = Tempfile.new('extralite_test_stmt_cache_close').path
+
+    db = Extralite::Database.new(fn)
+    db.query('create table t (x)')
+
+    db.execute <<~SQL
+      insert into t values (42)
+    SQL
+    assert File.file?("#{fn}-wal"), "WAL file should exist"
+
+    assert_equal [{x: 42}], db.query('select * from t where x = ?', 42)
+
+    db.close
+    refute File.file?("#{fn}-wal"), "WAL file should not exist after close"
+  end
+
+  def test_stmt_cache_gc
+    fn = Tempfile.new('extralite_test_stmt_cache_gc').path
+
+    db = Extralite::Database.new(fn)
+    db.query('create table t (x)')
+
+    db.execute <<~SQL
+      insert into t values (42)
+    SQL
+    assert File.file?("#{fn}-wal"), "WAL file should exist"
+
+    assert_equal [{x: 42}], db.query('select * from t where x = ?', 42)
+
+    db = nil
+    GC.start
+    refute File.file?("#{fn}-wal"), "WAL file should not exist after GC"
+  end
+
+  def test_stmt_cache_concurrent_access
+    # https://github.com/digital-fabric/extralite/issues/88
+    fn = Tempfile.new('extralite_test_stmt_cache_concurrent_access').path
+
+    a = Extralite::Database.new(fn)
+    a.execute("pragma journal_mode=wal")
+    a.execute("create table t (id integer primary key, x)")
+    a.execute("insert into t (x) values (1)")
+    a.query_single("select * from t where id = ?", 1)
+    
+    b = Extralite::Database.new(fn)
+    b.execute("insert into t (x) values (2)")
+    
+    assert_equal 2, b.query_single_splat("select count(*) from t")
+    assert_equal 2, a.query_single_splat("select count(*) from t")
+  end
+
+  def test_stmt_cache_concurrent_transactions
+    # https://github.com/digital-fabric/extralite/issues/89
+    fn = Tempfile.new('extralite_test_stmt_cache_concurrent_access').path
+
+    a = Extralite::Database.new(fn)
+    a.execute('create table t (x)')
+    b = Extralite::Database.new(fn)
+    b.execute('begin immediate transaction')
+    
+    assert_raises(Extralite::BusyError) {
+      a.transaction { a.execute("insert into t values (1)") }
+    }
+  end
 end

data/test/test_sequel.rb

@@ -20,6 +20,7 @@ class SequelExtraliteTest < Minitest::Test
 
   def teardown
     @db.disconnect
+    super
   end
 
   def test_sequel

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: extralite-bundle
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.1.2
 platform: ruby
 authors:
 - Sharon Rosner
@@ -41,44 +41,44 @@ dependencies:
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.22.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.22.0
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.38
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.38
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: sequel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.105.0
+        version: 5.108.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.105.0
+        version: 5.108.0
 email: sharon@noteflakes.com
 executables: []
 extensions: