extralite-bundle 3.1.1 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fffde36ad772833bc816f85c26c6472d1c9e6c8e4ba91092734efeb24e2541a
-  data.tar.gz: c4200d06ffece67d1241297567b37b3ddb6bc882d72dd6b4ba402a2611f4a1a1
+  metadata.gz: 9eac653308555c057d121db6b0e17905fff645a62d926bdd3ac07323f40f8f9e
+  data.tar.gz: 2bcfeb952ce57afa647b969016891edae0fd615fc78f97a0a6b0336cc35791d6
 SHA512:
-  metadata.gz: 97fa8bbe57df8c8f679703764a7b6a185c235cf53c40738bf46f06bea82385fe1a7deed5d2990cb9837a1e1aaf858a5a4a88e5baccbb6117526dce8c3591fd32
-  data.tar.gz: 07716c4ba47c25b2ee796ce287e7a87e051176cdbd79badb906ea86fe45fd7526b3cd0180f077cfae3ff6311a7e182b351c36d8696c10feb8ac50714f8dd1dd0
+  metadata.gz: aa4d929c51e1f2c05fc0e67aa37447281c50d697b9dff242ca6f96e3723027e03b3db5b4c437399f28045a12d251dfff3e0f3a47709302b132347cca9c7fa514
+  data.tar.gz: 9809ca98906d5b853e646814057b976a55171249ae85b0502eea8ab39032d725889d736d3e9eff71ee46c9ca31d64e81f42102936753e69a2714188abec3bca5

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 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)

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

@@ -56,7 +56,7 @@ latest features and enhancements.
   [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.
 
@@ -1313,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);
@@ -458,8 +456,12 @@ VALUE cleanup_stmt(query_ctx *ctx) {
 
   if (!(ctx->flags & STMT_CTX_F_USE_CACHE))
     sqlite3_finalize(ctx->stmt);
-  else if (!(ctx->flags & STMT_CTX_F_CACHE_HIT))
-    rb_hash_aset(ctx->db->stmt_cache, ctx->sql, ULONG2NUM((uint64_t)(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)));
+  }
 done:
   return Qnil;
 }

data/ext/extralite/database.c

@@ -78,19 +78,18 @@ static int stmt_cache_iter(VALUE key, VALUE value, VALUE _param) {
   return ST_CONTINUE;
 }
 
-static void stmt_cache_clear(sqlite3 *db, VALUE stmt_cache) {
+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_hash_clear(stmt_cache);
   RB_GC_GUARD(stmt_cache);
 }
 
 static void Database_free(void *ptr) {
   Database_t *db = ptr;
   if (db->sqlite3_db) {
-    stmt_cache_clear(db->sqlite3_db, db->stmt_cache);
+    stmt_cache_finalize(db->sqlite3_db, db->stmt_cache);
     sqlite3_close_v2(db->sqlite3_db);
   }
   free(ptr);
@@ -279,7 +278,8 @@ VALUE Database_close(VALUE self) {
   int rc;
   Database_t *db = self_to_database(self);
 
-  stmt_cache_clear(db->sqlite3_db, db->stmt_cache);
+  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));
@@ -1565,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.1'
+  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/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
@@ -2244,7 +2324,7 @@ class StmtCacheText < Minitest::Test
   end
 
   def test_stmt_cache_gc
-    fn = Tempfile.new('extralite_test_stmt_cache_close').path
+    fn = Tempfile.new('extralite_test_stmt_cache_gc').path
 
     db = Extralite::Database.new(fn)
     db.query('create table t (x)')
@@ -2260,4 +2340,35 @@ class StmtCacheText < Minitest::Test
     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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: extralite-bundle
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  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: