extralite 2.5 → 2.7

data/gemspec.rb

@@ -8,19 +8,18 @@ def common_spec(s)
   s.files       = `git ls-files`.split
   s.homepage    = 'https://github.com/digital-fabric/extralite'
   s.metadata    = {
-    "source_code_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"
+    'homepage_uri' => 'https://github.com/digital-fabric/extralite',
+    'documentation_uri' => 'https://www.rubydoc.info/gems/extralite',
+    'changelog_uri' => 'https://github.com/digital-fabric/extralite/blob/master/CHANGELOG.md'
   }
-  s.rdoc_options = ["--title", "extralite", "--main", "README.md"]
-  s.extra_rdoc_files = ["README.md"]
-  s.require_paths = ["lib"]
+  s.rdoc_options = ['--title', 'Extralite', '--main', 'README.md']
+  s.extra_rdoc_files = ['README.md']
+  s.require_paths = ['lib']
   s.required_ruby_version = '>= 3.0'
 
-  s.add_development_dependency  'rake-compiler',        '1.1.6'
-  s.add_development_dependency  'minitest',             '5.15.0'
+  s.add_development_dependency  'rake-compiler',        '1.2.7'
+  s.add_development_dependency  'minitest',             '5.21.2'
   s.add_development_dependency  'simplecov',            '0.17.1'
-  s.add_development_dependency  'yard',                 '0.9.27'
-  s.add_development_dependency  'sequel',               '5.51.0'
+  s.add_development_dependency  'yard',                 '0.9.34'
+  s.add_development_dependency  'sequel',               '5.77.0'
 end

data/lib/extralite/version.rb

@@ -1,4 +1,4 @@
 module Extralite
   # Extralite version
-  VERSION = '2.5'
+  VERSION = '2.7'
 end

data/lib/extralite.rb

@@ -29,10 +29,10 @@ module Extralite
   class ParameterError < Error
   end
 
-  # An SQLite database
+  # This class encapsulates an SQLite database connection.
   class Database
     # @!visibility private
-    TABLES_SQL = <<~SQL
+    TABLES_SQL = (<<~SQL).freeze
       SELECT name FROM %<db>s.sqlite_master
       WHERE type ='table'
         AND name NOT LIKE 'sqlite_%%';
@@ -46,10 +46,11 @@ module Extralite
     # @param db [String] name of attached database
     # @return [Array] list of tables
     def tables(db = 'main')
-      query_single_column(format(TABLES_SQL, db: db))
+      query_argv(format(TABLES_SQL, db: db))
     end
 
-    # Gets or sets one or more pragmas:
+    # Gets or sets one or more database pragmas. For a list of available pragmas
+    # see: https://sqlite.org/pragma.html#toc
     #
     #     db.pragma(:cache_size) # get
     #     db.pragma(cache_size: -2000) # set
@@ -60,6 +61,11 @@ module Extralite
       value.is_a?(Hash) ? pragma_set(value) : pragma_get(value)
     end
 
+    # Error class used to roll back a transaction without propagating an
+    # exception.
+    class Rollback < Error
+    end
+
     # Starts a transaction and runs the given block. If an exception is raised
     # in the block, the transaction is rolled back. Otherwise, the transaction
     # is commited after running the block.
@@ -69,20 +75,73 @@ module Extralite
     #       raise if db.query_single_value('select x from bar') > 42
     #     end
     #
-    # @param mode [Symbol, String] transaction mode (deferred, immediate or exclusive). Defaults to immediate.
+    # For more information on transactions see:
+    # https://sqlite.org/lang_transaction.html
+    #
+    # @param mode [Symbol, String] transaction mode (deferred, immediate or exclusive).
     # @return [Any] the given block's return value
     def transaction(mode = :immediate)
-      execute "begin #{mode} transaction"
-    
       abort = false
+      execute "begin #{mode} transaction"    
       yield self
-    rescue
+    rescue => e
       abort = true
-      raise
+      e.is_a?(Rollback) ? nil : raise
     ensure
       execute(abort ? 'rollback' : 'commit')
     end
 
+    # Creates a savepoint with the given name. For more information on
+    # savepoints see: https://sqlite.org/lang_savepoint.html
+    #
+    #     db.savepoint(:savepoint1)
+    #     db.execute('insert into foo values (42)')
+    #     db.rollback_to(:savepoint1)
+    #     db.release(:savepoint1)
+    #
+    # @param name [String, Symbol] savepoint name
+    # @return [Extralite::Database] database
+    def savepoint(name)
+      execute "savepoint #{name}"
+      self
+    end
+
+    # Release a savepoint with the given name. For more information on
+    # savepoints see: https://sqlite.org/lang_savepoint.html
+    #
+    # @param name [String, Symbol] savepoint name
+    # @return [Extralite::Database] database
+    def release(name)
+      execute "release #{name}"
+      self
+    end
+
+    # Rolls back changes to a savepoint with the given name. For more
+    # information on savepoints see: https://sqlite.org/lang_savepoint.html
+    #
+    # @param name [String, Symbol] savepoint name
+    # @return [Extralite::Database] database
+    def rollback_to(name)
+      execute "rollback to #{name}"
+      self
+    end
+
+    # Rolls back the currently active transaction. This method should only be
+    # called from within a block passed to `Database#transaction`. This method
+    # raises a Extralite::Rollback exception, which will stop execution of the
+    # transaction block without propagating the exception.
+    #
+    #     db.transaction do
+    #       db.execute('insert into foo (42)')
+    #       db.rollback!
+    #     end
+    #
+    # @param name [String, Symbol] savepoint name
+    # @return [Extralite::Database] database
+    def rollback!
+      raise Rollback
+    end
+
     private
 
     def pragma_set(values)
@@ -91,7 +150,7 @@ module Extralite
     end
 
     def pragma_get(key)
-      query_single_value("pragma #{key}")
+      query_single_argv("pragma #{key}")
     end
   end
 

data/lib/sequel/adapters/extralite.rb

@@ -362,7 +362,7 @@ module Sequel
       def fetch_rows(sql, &block)
         execute(sql) do |result, columns|
           self.columns = columns
-          max = columns.size
+          # max = columns.size
           result.each(&block)
         end
       end

data/test/helper.rb

@@ -7,4 +7,12 @@ require 'minitest/autorun'
 puts "sqlite3 version: #{Extralite.sqlite3_version}"
 
 IS_LINUX = RUBY_PLATFORM =~ /linux/
-SKIP_RACTOR_TESTS = !IS_LINUX || (RUBY_VERSION =~ /^3\.0/)
+# Ractors are kinda flaky, there's no point in testing this
+SKIP_RACTOR_TESTS = true #!IS_LINUX || (RUBY_VERSION =~ /^3\.[01]/)
+
+module Minitest::Assertions
+  def assert_in_range exp_range, act
+    msg = message(msg) { "Expected #{mu_pp(act)} to be in range #{mu_pp(exp_range)}" }
+    assert exp_range.include?(act), msg
+  end
+end

data/test/perf_argv_transform.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Run on Ruby 3.3 with YJIT enabled
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'extralite', path: '..'
+  gem 'benchmark-ips'
+end
+
+require 'benchmark/ips'
+require 'fileutils'
+
+DB_PATH = "/tmp/extralite_sqlite3_perf-#{Time.now.to_i}-#{rand(10000)}.db"
+puts "DB_PATH = #{DB_PATH.inspect}"
+
+$extralite_db = Extralite::Database.new(DB_PATH, gvl_release_threshold: -1)
+
+def prepare_database(count)
+  $extralite_db.query('create table if not exists foo (b text)')
+  $extralite_db.query('delete from foo')
+  $extralite_db.query('begin')
+  count.times { $extralite_db.query('insert into foo (b) values (?)', "hello#{rand(1000)}" )}
+  $extralite_db.query('commit')
+end
+
+class Model
+  def initialize(h)
+    @h = h
+  end
+
+  def values
+    @h
+  end
+end
+
+TRANSFORM = ->(b) { { b: b } }
+
+def extralite_run_ary_map(count)
+  results = []
+  $extralite_db.query_ary('select * from foo') { |(b)| results << { b: b } }
+  raise unless results.size == count
+end
+
+def extralite_run_argv_map(count)
+  results = []
+  $extralite_db.query_argv('select * from foo') { |b| results << { b: b } }
+  raise unless results.size == count
+end
+
+def extralite_run_transform(count)
+  results = $extralite_db.query_argv(TRANSFORM, 'select * from foo')
+  raise unless results.size == count
+end
+
+[10, 1000, 100000].each do |c|
+  puts "Record count: #{c}"
+  prepare_database(c)
+
+  bm = Benchmark.ips do |x|
+    x.config(:time => 5, :warmup => 2)
+
+    x.report("ary_map")   { extralite_run_ary_map(c) }
+    x.report("argv_map")  { extralite_run_argv_map(c) }
+    x.report("transform") { extralite_run_transform(c) }
+
+    x.compare!
+  end
+  puts;
+  bm.entries.each { |e| puts "#{e.label}: #{(e.ips * c).round.to_i} rows/s" }
+  puts;
+end

data/test/perf_ary.rb

@@ -15,26 +15,25 @@ require 'fileutils'
 DB_PATH = "/tmp/extralite_sqlite3_perf-#{Time.now.to_i}-#{rand(10000)}.db"
 puts "DB_PATH = #{DB_PATH.inspect}"
 
+$sqlite3_db = SQLite3::Database.new(DB_PATH)
+$extralite_db = Extralite::Database.new(DB_PATH, gvl_release_threshold: -1)
 
 def prepare_database(count)
   db = Extralite::Database.new(DB_PATH)
-  db.query('create table if not exists foo ( a integer primary key, b text )')
-  db.query('delete from foo')
-  db.query('begin')
-  count.times { db.query('insert into foo (b) values (?)', "hello#{rand(1000)}" )}
-  db.query('commit')
-  db.close
+  $extralite_db.query('create table if not exists foo ( a integer primary key, b text )')
+  $extralite_db.query('delete from foo')
+  $extralite_db.query('begin')
+  count.times { $extralite_db.query('insert into foo (b) values (?)', "hello#{rand(1000)}" )}
+  $extralite_db.query('commit')
 end
 
 def sqlite3_run(count)
-  db = SQLite3::Database.new(DB_PATH)
-  results = db.execute('select * from foo')
+  results = $sqlite3_db.execute('select * from foo')
   raise unless results.size == count
 end
 
 def extralite_run(count)
-  db = Extralite::Database.new(DB_PATH)
-  results = db.query_ary('select * from foo')
+  results = $extralite_db.query('select * from foo')
   raise unless results.size == count
 end
 
@@ -43,12 +42,15 @@ end
 
   prepare_database(c)
 
-  Benchmark.ips do |x|
-    x.config(:time => 3, :warmup => 1)
+  bm = Benchmark.ips do |x|
+    x.config(:time => 5, :warmup => 2)
 
     x.report("sqlite3") { sqlite3_run(c) }
     x.report("extralite") { extralite_run(c) }
 
     x.compare!
   end
+  puts;
+  bm.entries.each { |e| puts "#{e.label}: #{(e.ips * c).round.to_i} rows/s" }
+  puts;
 end

data/test/perf_hash.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Run on Ruby 3.3 with YJIT enabled
+
 require 'bundler/inline'
 
 gemfile do
@@ -15,40 +17,40 @@ require 'fileutils'
 DB_PATH = "/tmp/extralite_sqlite3_perf-#{Time.now.to_i}-#{rand(10000)}.db"
 puts "DB_PATH = #{DB_PATH.inspect}"
 
+$sqlite3_db = SQLite3::Database.new(DB_PATH, results_as_hash: true)
+$extralite_db = Extralite::Database.new(DB_PATH, gvl_release_threshold: -1)
+
 def prepare_database(count)
-  db = Extralite::Database.new(DB_PATH)
-  db.query('create table if not exists foo ( a integer primary key, b text )')
-  db.query('delete from foo')
-  db.query('begin')
-  count.times { db.query('insert into foo (b) values (?)', "hello#{rand(1000)}" )}
-  db.query('commit')
-  db.close
+  $extralite_db.query('create table if not exists foo ( a integer primary key, b text )')
+  $extralite_db.query('delete from foo')
+  $extralite_db.query('begin')
+  count.times { $extralite_db.query('insert into foo (b) values (?)', "hello#{rand(1000)}" )}
+  $extralite_db.query('commit')
 end
 
 def sqlite3_run(count)
-  db = SQLite3::Database.new(DB_PATH, :results_as_hash => true)
-  results = db.execute('select * from foo')
+  results = $sqlite3_db.execute('select * from foo')
   raise unless results.size == count
 end
 
 def extralite_run(count)
-  db = Extralite::Database.new(DB_PATH)
-  results = db.query('select * from foo')
+  results = $extralite_db.query('select * from foo')
   raise unless results.size == count
 end
 
 [10, 1000, 100000].each do |c|
   puts "Record count: #{c}"
-
   prepare_database(c)
 
-  Benchmark.ips do |x|
-    x.config(:time => 3, :warmup => 1)
+  bm = Benchmark.ips do |x|
+    x.config(:time => 5, :warmup => 2)
 
     x.report("sqlite3") { sqlite3_run(c) }
     x.report("extralite") { extralite_run(c) }
 
     x.compare!
   end
-  puts; puts; 
+  puts;
+  bm.entries.each { |e| puts "#{e.label}: #{(e.ips * c).round.to_i} rows/s" }
+  puts;
 end

data/test/perf_hash_prepared.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'extralite', path: '..'
+  gem 'sqlite3'
+  gem 'benchmark-ips'
+end
+
+require 'benchmark/ips'
+require 'fileutils'
+
+DB_PATH = "/tmp/extralite_sqlite3_perf-#{Time.now.to_i}-#{rand(10000)}.db"
+puts "DB_PATH = #{DB_PATH.inspect}"
+
+def prepare_database(count)
+  $sqlite3_db = SQLite3::Database.new(DB_PATH, results_as_hash: true)
+  $extralite_db = Extralite::Database.new(DB_PATH, gvl_release_threshold: -1)
+    
+  $extralite_db.query('create table if not exists foo ( a integer primary key, b text )')
+  $extralite_db.query('delete from foo')
+  $extralite_db.query('begin')
+  count.times { $extralite_db.query('insert into foo (b) values (?)', "hello#{rand(1000)}" )}
+  $extralite_db.query('commit')
+
+  $sqlite3_stmt = $sqlite3_db.prepare('select * from foo')
+  $extralite_q = $extralite_db.prepare('select * from foo')
+end
+
+def sqlite3_run(count)
+  results = $sqlite3_stmt.execute
+  raise unless results.to_a.size == count
+end
+
+def extralite_run(count)
+  results = $extralite_q.to_a
+  raise unless results.size == count
+end
+
+[10, 1000, 100000].each do |c|
+  puts "Record count: #{c}"
+
+  prepare_database(c)
+
+  bm = Benchmark.ips do |x|
+    x.config(:time => 5, :warmup => 2)
+
+    x.report("sqlite3") { sqlite3_run(c) }
+    x.report("extralite") { extralite_run(c) }
+
+    x.compare!
+  end
+  puts;
+  bm.entries.each { |e| puts "#{e.label}: #{(e.ips * c).round.to_i} rows/s" }
+  puts;
+end

data/test/perf_hash_transform.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Run on Ruby 3.3 with YJIT enabled
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'extralite', path: '..'
+  gem 'benchmark-ips'
+end
+
+require 'benchmark/ips'
+require 'fileutils'
+
+DB_PATH = "/tmp/extralite_sqlite3_perf-#{Time.now.to_i}-#{rand(10000)}.db"
+puts "DB_PATH = #{DB_PATH.inspect}"
+
+$extralite_db = Extralite::Database.new(DB_PATH, gvl_release_threshold: -1)
+
+def prepare_database(count)
+  $extralite_db.query('create table if not exists foo ( a integer primary key, b text )')
+  $extralite_db.query('delete from foo')
+  $extralite_db.query('begin')
+  count.times { $extralite_db.query('insert into foo (b) values (?)', "hello#{rand(1000)}" )}
+  $extralite_db.query('commit')
+end
+
+class Model
+  def initialize(h)
+    @h = h
+  end
+
+  def values
+    @h
+  end
+end
+
+TRANSFORM = ->(h) { Model.new(h) }
+
+def extralite_run_map(count)
+  results = $extralite_db.query('select * from foo').map(&TRANSFORM)
+  raise unless results.size == count
+end
+
+def extralite_run_transform(count)
+  results = $extralite_db.query(TRANSFORM, 'select * from foo')
+  raise unless results.size == count
+end
+
+[10, 1000, 100000].each do |c|
+  puts "Record count: #{c}"
+  prepare_database(c)
+
+  bm = Benchmark.ips do |x|
+    x.config(:time => 5, :warmup => 2)
+
+    x.report("map")       { extralite_run_map(c) }
+    x.report("transform") { extralite_run_transform(c) }
+
+    x.compare!
+  end
+  puts;
+  bm.entries.each { |e| puts "#{e.label}: #{(e.ips * c).round.to_i} rows/s" }
+  puts;
+end

data/test/perf_polyphony.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Run on Ruby 3.3 with YJIT enabled
+
+require 'bundler/inline'
+gemfile do
+  gem 'polyphony'
+  gem 'extralite', path: '.'
+  gem 'benchmark-ips'
+end
+
+require 'benchmark/ips'
+require 'polyphony'
+
+DB_PATH = "/tmp/extralite_sqlite3_perf-#{Time.now.to_i}-#{rand(10000)}.db"
+puts "DB_PATH = #{DB_PATH.inspect}"
+
+$db1 = Extralite::Database.new(DB_PATH, gvl_release_threshold: -1)
+$db2 = Extralite::Database.new(DB_PATH, gvl_release_threshold: 0)
+$db3 = Extralite::Database.new(DB_PATH)
+
+$snooze_count = 0
+$db3.on_progress(25) { $snooze_count += 1; snooze }
+
+def prepare_database(count)
+  $db1.execute('create table if not exists foo ( a integer primary key, b text )')
+  $db1.transaction do
+    $db1.execute('delete from foo')
+    rows = count.times.map { "hello#{rand(1000)}" }
+    $db1.batch_execute('insert into foo (b) values (?)', rows)
+  end
+end
+
+def extralite_run1(count)
+  results = $db1.query('select * from foo')
+  raise unless results.size == count
+end
+
+def extralite_run2(count)
+  results = $db2.query('select * from foo')
+  raise unless results.size == count
+end
+
+def extralite_run3(count)
+  results = $db3.query('select * from foo')
+  raise unless results.size == count
+end
+
+[10, 1000, 100000].each do |c|
+  puts "Record count: #{c}"
+  prepare_database(c)
+
+  bm = Benchmark.ips do |x|
+    x.config(:time => 3, :warmup => 1)
+
+    x.report('GVL threshold -1') { extralite_run1(c) }
+    x.report('GVL threshold  0') { extralite_run2(c) }
+    $snooze_count  = 0
+    x.report('on_progress 1000') { extralite_run3(c) }
+
+    x.compare!
+  end
+  puts;
+  bm.entries.each do |e|
+    score = (e.ips * c).round.to_i
+    if e.label == 'on_progress 1000'
+      snooze_rate = ($snooze_count / e.seconds).to_i
+      puts "#{e.label}: #{score} rows/s  snoozes: #{snooze_rate} i/s"
+    else
+      puts "#{e.label}: #{score} rows/s"
+    end
+  end
+  puts;
+end