extralite 1.4 → 1.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b112a3c34429f8b44c4b4a922c4e038387f6c1db54e6f01377200d7a60324dd4
-  data.tar.gz: a664bc81719347079fdfbbffdf2e665bd2772fe8dcf9c30b3ec18c6238a8888a
+  metadata.gz: 149ddf21bc7feaf4d7c3a19011ac9a515fe83d5f57b88c507783bee8c6d5e096
+  data.tar.gz: 55507a0acbd8efeb89d5dfcf652441081285a670a5968a96f2696d3073844975
 SHA512:
-  metadata.gz: '053783bb3f186130fc92b0a57403f0f9472a98e6ce45b1fbb128c5e43914b2a6ec56d39a5e6b10e16f5e6b46f8e9d586837860f63e7538ad238fc0a7aa0995c3'
-  data.tar.gz: '058538866f9b2c6a5a0116c8ed3a801aa7bbb8ef8f911eff6d94d7a9cfa98861ad98f4d27e06a736b18c4b62e3c2369a4a306492cc562693da0282363e00f208'
+  metadata.gz: c7cdc5d0179c26c3deddc8439e4aaa5f91429ed3839cffc2224fefd8e90c78f0db9c4768f9534b693638572ec5e99ab0317a948f037c654262eca6d801a438f9
+  data.tar.gz: 4ae156e6850e5485b31b1f701597c0692608b59facd1473ca064d0b23ca8b5d2d84995f4fe4c99800b3e01815fb32e21481290e369506e5d2c4e9794af8fe853

data/.github/workflows/test.yml

@@ -8,7 +8,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        ruby: [2.6, 2.7, 3.0]
+        ruby: [2.6, 2.7, '3.0']
 
     name: >-
       ${{matrix.os}}, ${{matrix.ruby}}
@@ -16,15 +16,10 @@ jobs:
     runs-on: ${{matrix.os}}
     steps:
     - uses: actions/checkout@v1
-    - uses: actions/setup-ruby@v1
+    - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{matrix.ruby}}
-    - name: Install dependencies
-      run: |
-        gem install bundler
-        bundle install
-    - name: Show Linux kernel version
-      run: uname -r
+        bundler-cache: true # 'bundle install' and cache
     - name: Compile C-extension
       run: bundle exec rake compile
     - name: Run tests

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 1.8 2021-12-15
+
+- Add documentation
+
+## 1.7 2021-12-13
+
+- Add extralite Sequel adapter
+- Add support for binding hash parameters
+
+## 1.6 2021-12-13
+
+- Release GVL while fetching rows
+
+## 1.5 2021-12-13
+
+- Release GVL while preparing statements
+- Use `sqlite3_prepare_v2` instead of deprecated `sqlite_prepare`
+
 ## 1.4 2021-08-25
 
 - Fix possible segfault in cleanup_stmt

data/Gemfile.lock

@@ -1,58 +1,37 @@
 PATH
   remote: .
   specs:
-    extralite (1.4)
+    extralite (1.8)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
-    coderay (1.1.3)
     docile (1.4.0)
     json (2.5.1)
-    method_source (1.0.0)
-    minitest (5.14.4)
-    parallel (1.20.1)
-    parser (3.0.1.1)
-      ast (~> 2.4.1)
-    pry (0.13.1)
-      coderay (~> 1.1)
-      method_source (~> 1.0)
-    rainbow (3.0.0)
-    rake (13.0.3)
-    rake-compiler (1.1.1)
+    minitest (5.15.0)
+    rake (13.0.6)
+    rake-compiler (1.1.6)
       rake
-    regexp_parser (2.1.1)
-    rexml (3.2.5)
-    rubocop (0.85.1)
-      parallel (~> 1.10)
-      parser (>= 2.7.0.1)
-      rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.7)
-      rexml
-      rubocop-ast (>= 0.0.3)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (1.5.0)
-      parser (>= 3.0.1.1)
-    ruby-progressbar (1.11.0)
+    sequel (5.51.0)
     simplecov (0.17.1)
       docile (~> 1.1)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
-    unicode-display_width (1.7.0)
+    webrick (1.7.0)
+    yard (0.9.27)
+      webrick (~> 1.7.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   extralite!
-  minitest (= 5.14.4)
-  pry (= 0.13.1)
-  rake-compiler (= 1.1.1)
-  rubocop (= 0.85.1)
+  minitest (= 5.15.0)
+  rake-compiler (= 1.1.6)
+  sequel (= 5.51.0)
   simplecov (= 0.17.1)
+  yard (= 0.9.27)
 
 BUNDLED WITH
    2.1.4

data/README.md

@@ -6,22 +6,29 @@
 
 ## What is Extralite?
 
-Extralite is an extra-lightweight (less than 400 lines of C-code) SQLite3 wrapper for
-Ruby. It provides a single class with a minimal set of methods to interact with
-an SQLite3 database.
+Extralite is an extra-lightweight (less than 430 lines of C-code) SQLite3
+wrapper for Ruby. It provides a single class with a minimal set of methods to
+interact with an SQLite3 database.
 
 ## Features
 
-- A variety of methods for different data access patterns: row as hash, row as
-  array, single single row, single column, single value.
+- A variety of methods for different data access patterns: rows as hashes, rows
+  as arrays, single row, single column, single value.
+- 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.
 - Iterate over records with a block, or collect records into an array.
 - Parameter binding.
-- Correctly execute strings with multiple semicolon-separated queries (handy for
-  creating/modifying schemas).
+- Automatically execute SQL strings containing multiple semicolon-separated
+  queries (handy for creating/modifying schemas).
 - Get last insert rowid.
 - 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)
 
 ## Usage
 
@@ -60,8 +67,13 @@ db.query_single_value("select 'foo'") #=> "foo"
 # parameter binding (works for all query_xxx methods)
 db.query_hash('select ? as foo, ? as bar', 1, 2) #=> [{ :foo => 1, :bar => 2 }]
 
+# parameter binding of named parameters
+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)
+
 # get last insert rowid
-rowid = db.last_insert_id
+rowid = db.last_insert_rowid
 
 # get number of rows changed in last query
 number_of_rows_affected = db.changes
@@ -77,23 +89,74 @@ db.close
 db.closed? #=> true
 ```
 
+## Usage with Sequel
+
+Extralite includes an adapter for
+[Sequel](https://github.com/jeremyevans/sequel). To use the Extralite adapter,
+just use the `extralite` scheme instead of `sqlite`:
+
+```ruby
+DB = Sequel.connect('extralite:blog.db')
+articles = DB[:articles]
+p articles.to_a
+```
+
+(Make sure you include `extralite` as a dependency in your `Gemfile`.)
+
 ## Why not just use the sqlite3 gem?
 
-The sqlite3-ruby gem is a popular, solid, well-maintained project, used by
-thousands of developers. I've been doing a lot of work with SQLite3 lately, and
-wanted to have a simpler API that gives me query results in a variety of ways.
-Thus extralite was born.
+The [sqlite3-ruby](https://github.com/sparklemotion/sqlite3-ruby) gem is a
+popular, solid, well-maintained project, used by thousands of developers. I've
+been doing a lot of work with SQLite3 databases lately, and wanted to have a
+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.
+
+Here's a table summarizing the differences between the two gems:
+
+| |sqlite3-ruby|Extralite|
+|-|-|-|
+|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|
+|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|~500LoC|
+|Performance|1x|1.5x to 12.5x (see [below](#performance))|
 
 ## What about concurrency?
 
-Extralite currently does not release the GVL. This means that even if queries
-are executed on a separate thread, no other Ruby threads will be scheduled while
-SQLite3 is busy fetching the next record.
+Extralite releases the GVL while making blocking calls to the sqlite3 library,
+that is while preparing SQL statements and fetching rows. Releasing the GVL
+allows other threads to run while the sqlite3 library is busy compiling SQL into
+bytecode, or fetching the next row. This does not seem to hurt Extralite's
+performance:
+
+## Performance
+
+A benchmark script is
+[included](https://github.com/digital-fabric/extralite/blob/main/test/perf.rb),
+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 (using the `sqlite3` gem performance as baseline):
+
+|Row count|sqlite3-ruby (baseline)|Extralite (relative - rounded)|
+|-:|-:|-:|
+|10|1x|1.5x|
+|1K|1x|7x|
+|100K|1x|12.5x|
 
-In the future Extralite might be changed to release the GVL each time
-`sqlite3_step` is called.
+(If you're interested in checking this yourself, just run the script and let me
+know if your results are different.)
 
-## Can I use it with an ORM like ActiveRecord or Sequel?
+## Contributing
 
-Not yet, but you are welcome to contribute adapters for those projects. I will
-be releasing my own not-an-ORM tool in the near future.
+Contributions in the form of issues, PRs or comments will be greatly
+appreciated!

data/Rakefile

@@ -1,18 +1,27 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rake/clean"
+require 'bundler/gem_tasks'
+require 'rake/clean'
 
-require "rake/extensiontask"
-Rake::ExtensionTask.new("extralite_ext") do |ext|
-  ext.ext_dir = "ext/extralite"
+require 'rake/extensiontask'
+Rake::ExtensionTask.new('extralite_ext') do |ext|
+  ext.ext_dir = 'ext/extralite'
 end
 
 task :recompile => [:clean, :compile]
 
-task :default => [:compile, :test]
+task :default => [:compile, :doc, :test]
+task :doc => :yard
 task :test do
-  exec 'ruby test/test_database.rb'
+  exec 'ruby test/run.rb'
 end
 
-CLEAN.include "**/*.o", "**/*.so", "**/*.so.*", "**/*.a", "**/*.bundle", "**/*.jar", "pkg", "tmp"
+CLEAN.include '**/*.o', '**/*.so', '**/*.so.*', '**/*.a', '**/*.bundle', '**/*.jar', 'pkg', 'tmp'
+
+require 'yard'
+YARD_FILES = FileList['ext/extralite/extralite.c', 'lib/extralite.rb', 'lib/sequel/adapters/extralite.rb']
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = YARD_FILES
+  t.options = %w(-o doc --readme README.md)
+end