extralite-bundle 1.14

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 707b5791f03fe03812e63a1e46ff61ab7c0113558cadcff9d23b6cc4c30489ac
+  data.tar.gz: d2d9539f7cba8b25c2aea0ed2d3263c5f77cc83f037bf3580afe6cef2d755a8b
+SHA512:
+  metadata.gz: 12b635439146811bd212ec0c1efc2e0ddd772e125799eb5f94b505357d6ad2d933bd4e4e1a8e6e21e63f938a27880673e2d66db8c71597d22df9abb22643823a
+  data.tar.gz: 986f47ea415902b9dd1c1a1728328384d50748d1fdb7cbfa290439a44aad4489bb40bd0719055115e4e0d77a0df871e75fab2f5186a1930474c69860403331ea

data/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: ciconia

data/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-10.15]
+        ruby: [2.7, 3.0, 3.1, truffleruby]
+
+    name: >-
+      ${{matrix.os}}, ${{matrix.ruby}}
+
+    runs-on: ${{matrix.os}}
+    steps:
+    - uses: actions/checkout@v1
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{matrix.ruby}}
+        bundler-cache: true # 'bundle install' and cache
+    - name: Compile C-extension
+      run: bundle exec rake compile
+    - name: Run tests
+      run:  bundle exec rake test

data/.gitignore

@@ -0,0 +1,57 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+lib/extralite_ext.*
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*

data/CHANGELOG.md

@@ -0,0 +1,96 @@
+## 1.14 2022-02-28
+
+- Introduce `extralite-bundle` gem for bundling SQLite, use system lib by
+  default.
+
+## 1.13.1 2022-02-27
+
+- Fix compilation on TruffleRuby
+
+## 1.13 2022-02-27
+
+- Implement prepared statements (#7)
+- Update SQLite to 3.38.0 (#6)
+
+## 1.12 2022-02-15
+
+- Add `Extralite.sqlite3_version` method
+- Bundle sqlite3 in gem
+
+## 1.11 2021-12-17
+
+- Fix compilation on MacOS (#3)
+
+## 1.10 2021-12-15
+
+- Fix mutliple parameter binding with hash
+
+## 1.9 2021-12-15
+
+- Add support for reading BLOBs
+
+## 1.8.2 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
+
+## 1.3 2021-08-17
+
+- Pin error classes (for better compatibility with `GC.compact`)
+
+## 1.2 2021-06-06
+
+- Add support for big integers
+
+## 1.1 2021-06-02
+
+- Add `#close`, `#closed?` methods
+
+## 1.0 2021-05-27
+
+- Refactor C code
+- Use `rb_ensure` to finalize stmt
+- Remove bundled `sqlite3.h`, use system-wide header file instead
+
+## 0.6 2021-05-25
+
+- Add more specific errors: `SQLError`, `BusyError`
+
+## 0.5 2021-05-25
+
+- Implement `Database#query_single_row`
+
+## 0.4 2021-05-24
+
+- Add support for loading extensions
+
+## 0.3 2021-05-24
+
+- Add support for running multiple statements
+
+## 0.2 2021-05-23
+
+- Implement `Database#transaction_active?`
+- Add tests
+
+## 0.1 2021-05-21
+
+- First release
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec name: 'extralite'

data/Gemfile.lock

@@ -0,0 +1,37 @@
+PATH
+  remote: .
+  specs:
+    extralite (1.14)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    docile (1.4.0)
+    json (2.6.1)
+    minitest (5.15.0)
+    rake (13.0.6)
+    rake-compiler (1.1.6)
+      rake
+    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)
+    webrick (1.7.0)
+    yard (0.9.27)
+      webrick (~> 1.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  extralite!
+  minitest (= 5.15.0)
+  rake-compiler (= 1.1.6)
+  sequel (= 5.51.0)
+  simplecov (= 0.17.1)
+  yard (= 0.9.27)
+
+BUNDLED WITH
+   2.3.3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,248 @@
+<h1 align="center">
+  Extralite
+</h1>
+
+<h4 align="center">A fast Ruby gem for working with SQLite3 databases</h4>
+
+<p align="center">
+  <a href="http://rubygems.org/gems/extralite">
+    <img src="https://badge.fury.io/rb/extralite.svg" alt="Ruby gem">
+  </a>
+  <a href="https://github.com/digital-fabric/extralite/actions?query=workflow%3ATests">
+    <img src="https://github.com/digital-fabric/extralite/workflows/Tests/badge.svg" alt="Tests">
+  </a>
+  <a href="https://github.com/digital-fabric/extralite/blob/master/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.rubydoc.info/gems/extralite">DOCS</a> |
+  <a href="https://noteflakes.com/articles/2021-12-15-extralite">BLOG POST</a>
+</p>
+
+## What is Extralite?
+
+Extralite is a fast, extra-lightweight (about 600 lines of C-code) SQLite3
+wrapper for Ruby. It provides a minimal set of methods for interacting with an
+SQLite3 database, as well as prepared statements.
+
+Extralite comes in two flavors: the `extralite` gem which uses the
+system-installed sqlite3 library, and the `extralite-bundle` gem which bundles
+the latest version of SQLite
+([3.38.0](https://sqlite.org/releaselog/3_38_0.html)), offering access to the
+latest features and enhancements.
+
+## Features
+
+- A variety of methods for different data access patterns: rows as hashes, rows
+  as arrays, single row, single column, single value.
+- Prepared statements.
+- 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](#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.
+- 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).
+
+## Installation
+
+To use Extralite in your Ruby app, add the following to your `Gemfile`:
+
+```ruby
+gem 'extralite'
+```
+
+You can also run `gem install extralite` if you just want to check it out.
+
+## Installing the Extralite-SQLite3 bundle
+
+If you don't have sqlite3 installed on your system, do not want to use the
+system-installed version of SQLite3, or would like to use the latest version of
+SQLite3, you can install the `extralite-bundle` gem, which integrates the
+SQLite3 source code.
+
+> **Important note**: The `extralite-bundle` will take a while to install (on my
+> modest machine it takes about a minute), due to the size of the sqlite3 code.
+
+Usage of the `extralite-bundle` gem is identical to the usage of the normal
+`extralite` gem.
+
+## Usage
+
+```ruby
+require 'extralite'
+
+# get sqlite3 version
+Extralite.sqlite3_version #=> "3.35.2"
+
+# open a database
+db = Extralite::Database.new('/tmp/my.db')
+
+# get query results as array of hashes
+db.query('select 1 as foo') #=> [{ :foo => 1 }]
+# or:
+db.query_hash('select 1 as foo') #=> [{ :foo => 1 }]
+# or iterate over results
+db.query('select 1 as foo') { |r| p r }
+# { :foo => 1 }
+
+# get query results as array of arrays
+db.query_ary('select 1, 2, 3') #=> [[1, 2, 3]]
+# or iterate over results
+db.query_ary('select 1, 2, 3') { |r| p r }
+# [1, 2, 3]
+
+# get a single row as a hash
+db.query_single_row("select 1 as foo") #=> { :foo => 1 }
+
+# get single column query results as array of values
+db.query_single_column('select 42') #=> [42]
+# or iterate over results
+db.query_single_column('select 42') { |v| p v }
+# 42
+
+# get single value from first row of results
+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)
+
+# prepared statements
+stmt = db.prepare('select ? as foo, ? as bar') #=> Extralite::PreparedStatement
+stmt.query(1, 2) #=> [{ :foo => 1, :bar => 2 }]
+# PreparedStatement offers the same data access methods as the Database class,
+# but without the sql parameter.
+
+# get last insert rowid
+rowid = db.last_insert_rowid
+
+# get number of rows changed in last query
+number_of_rows_affected = db.changes
+
+# get db filename
+db.filename #=> "/tmp/my.db"
+
+# load an extension
+db.load_extension('/path/to/extension.so')
+
+# close database
+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](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](#concurrency). On the other hand, Extralite does not have
+support for defining custom functions, aggregates and collations. If you're
+using any of those features, you'll have to stick to sqlite3-ruby.
+
+Here's a table summarizing the differences between the two gems:
+
+| |sqlite3-ruby|Extralite|
+|-|-|-|
+|SQLite3 dependency|depends on OS-installed libsqlite3|bundles latest version of SQLite3|
+|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|
+|Prepared statements|yes|yes|
+|custom functions in Ruby|yes|no|
+|custom collations|yes|no|
+|custom aggregate functions|yes|no|
+|Multithread friendly|no|[yes](#concurrency)|
+|Code size|~2650LoC|~600LoC|
+|Performance|1x|1.5x to 12.5x (see [below](#performance))|
+
+## Concurrency
+
+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, 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 times faster than `sqlite3` when fetching a
+large number of rows.
+
+### Rows as hashes
+
+ [Benchmark source code](https://github.com/digital-fabric/extralite/blob/main/test/perf_hash.rb)
+
+|Row count|sqlite3-ruby|Extralite|Advantage|
+|-:|-:|-:|-:|
+|10|75.3K rows/s|134.2K rows/s|__1.78x__|
+|1K|286.8K rows/s|2106.4K rows/s|__7.35x__|
+|100K|181.0K rows/s|2275.3K rows/s|__12.53x__|
+
+### Rows as arrays
+
+[Benchmark source code](https://github.com/digital-fabric/extralite/blob/main/test/perf_ary.rb)
+
+|Row count|sqlite3-ruby|Extralite|Advantage|
+|-:|-:|-:|-:|
+|10|64.3K rows/s|94.0K rows/s|__1.46x__|
+|1K|498.9K rows/s|2478.2K rows/s|__4.97x__|
+|100K|441.1K rows/s|3023.4K rows/s|__6.85x__|
+
+### Prepared statements
+
+[Benchmark source code](https://github.com/digital-fabric/extralite/blob/main/test/perf_prepared.rb)
+
+|Row count|sqlite3-ruby|Extralite|Advantage|
+|-:|-:|-:|-:|
+|10|241.8K rows/s|888K rows/s|__3.67x__|
+|1K|298.6K rows/s|2606K rows/s|__8.73x__|
+|100K|201.6K rows/s|1934K rows/s|__9.6x__|
+
+As those benchmarks show, Extralite is capabale of reading up to 3M rows/second
+when fetching rows as arrays, and up to 2.6M rows/second when fetching
+rows as hashes.
+
+## License
+
+The source code for Extralite is published under the [MIT license](LICENSE). The
+source code for SQLite is in the [public
+domain](https://sqlite.org/copyright.html).
+
+## Contributing
+
+Contributions in the form of issues, PRs or comments will be greatly
+appreciated!

data/Rakefile

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'rake/clean'
+
+require 'rake/extensiontask'
+Rake::ExtensionTask.new('extralite_ext') do |ext|
+  ext.ext_dir = 'ext/extralite'
+end
+
+task :recompile => [:clean, :compile]
+
+task :default => [:compile, :doc, :test]
+task :doc => :yard
+task :test do
+  exec 'ruby test/run.rb'
+end
+
+CLEAN.include 'lib/*.o', 'lib/*.so', 'lib/*.so.*', 'lib/*.a', 'lib/*.bundle', 'lib/*.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
+
+task :release do
+  require_relative './lib/extralite/version'
+  version = Extralite::VERSION
+  
+  puts 'Building extralite...'
+  `gem build extralite.gemspec`
+
+  puts 'Building extralite-bundle...'
+  `gem build extralite-bundle.gemspec`
+
+  puts "Pushing extralite #{version}..."
+  # `gem push extralite-#{version}.gem`
+
+  puts "Pushing extralite-bundle #{version}..."
+  `gem push extralite-bundle-#{version}.gem`
+
+  puts "Cleaning up..."
+  `rm *.gem`
+end

data/bin/update_sqlite_source

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+version = ARGV[0]
+raise "Please specify version" unless version
+
+require 'fileutils'
+require 'date'
+
+FileUtils.cd '/tmp'
+
+version_id = version.gsub('.', '')
+version_id += '0' * (7 - version_id.length)
+url = "https://sqlite.org/#{Date.today.year}/sqlite-amalgamation-#{version_id}.zip"
+dest = File.expand_path('../ext/extralite', __dir__)
+
+puts "Downloading from #{url}..."
+`curl #{url} > #{version_id}.zip`
+
+puts "Unzipping zip file..."
+`unzip -o #{version_id}.zip`
+
+puts "Copying source files"
+`cp sqlite-amalgamation-#{version_id}/sqlite3.* #{dest}/`
+
+puts 'Done updating source files'