extralite-bundle 1.21 → 1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71d65f6263e6916f9f3c92eb10f35d677385b8e3e1bc09a53bba5d809450bd8f
-  data.tar.gz: ad2df66fb54681f8e3b0537a40973616b477b43d9a8ed992f7880daab7ea2997
+  metadata.gz: 273cbd77f6231b5de32d1829c819553bbf60068251a4c994d0c038f89b908601
+  data.tar.gz: be32cecd7e3c6915f85dccf7a5c88757e952f45424fef84127bcf602de1a7074
 SHA512:
-  metadata.gz: 4afbf7a47d788d8045f45caf80b15eccd78913cc94587e1f15b68970bfc9ac8310ea45bd60ae9e51a923c086c50044afc6aac22c84b6d18af03fee57a6b75c7f
-  data.tar.gz: 986a4b84c02f84eb7bc0ebbbff537beafba3562771dc055053e9ca9ca8af2c5f53c2b4b52a65b74a881d91ade7185c40dac35d11f6641f682d266555a689f894
+  metadata.gz: 5eccc418d3dc8038263d596275d40cef9cb5690e954b8f284b37c0809be2221087899e57dd040448d8ac6c1445aabc296f81f9aa32c0e597d691fa5557eba4fa
+  data.tar.gz: a645e5bba9b35ebbdcdf14946c7e7233a1d055cbbbf8ca9d0971d67f3588b4461fa5417ca72a62a6e4ef048638c8c456d347c10a000848ed4b535d52af52df3d

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 1.22 2023-01-23
+
+- Improve documentation (#17)
+
 # 1.21 2023-01-23
 
 - Update bundled sqlite to version 3.40.1 (#18)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    extralite (1.21)
+    extralite (1.22)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,64 +1,42 @@
-<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>
+# Extralite - A super fast Ruby gem for working with SQLite3 databases
+
+* Source code: https://github.com/digital-fabric/extralite
+* Documentation: http://www.rubydoc.info/gems/extralite
+
+[![Ruby gem](https://badge.fury.io/rb/extralite.svg)](https://rubygems.org/gems/extralite) [![Tests](https://github.com/digital-fabric/extralite/workflows/Tests/badge.svg)](https://github.com/digital-fabric/extralite/actions?query=workflow%3ATests) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/digital-fabric/extralite/blob/master/LICENSE)
 
 ## 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 is a super fast, extra-lightweight (about 1300 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
+([3.40.1](https://sqlite.org/releaselog/3_40_1.html)), offering access to the
 latest features and enhancements.
 
 ## Features
 
+- Super fast - [up to 10x faster](#performance) than the
+  [sqlite3](https://github.com/sparklemotion/sqlite3-ruby) gem (see also
+  [comparison](#why-not-just-use-the-sqlite3-gem).)
 - A variety of methods for different data access patterns: rows as hashes, rows
   as arrays, single row, single column, single value.
 - Prepared statements.
+- Parameter binding.
 - Use system-installed sqlite3, or the [bundled latest version of
   SQLite3](#installing-the-extralite-sqlite3-bundle).
-- 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.
 - Execute the same query with multiple parameter lists (useful for inserting records).
 - 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).
-- Other features:
-  - Backup databases
-  - Interrupt long-running queries (from another thread)
-  - Get runtime status, database status and prepared statement status values.
 
 ## Installation
 
@@ -77,13 +55,14 @@ 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.
+> **Important note**: The `extralite-bundle` gem 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.
+`extralite` gem, using `require 'extralite'` to load the gem.
 
-## Usage
+## Synopsis
 
 ```ruby
 require 'extralite'
@@ -144,6 +123,9 @@ rowid = db.last_insert_rowid
 # get number of rows changed in last query
 number_of_rows_affected = db.changes
 
+# get column names for the given sql
+db.columns('select a, b, c from foo') => [:a, :b, :c]
+
 # get db filename
 db.filename #=> "/tmp/my.db"
 
@@ -163,6 +145,78 @@ db.close
 db.closed? #=> true
 ```
 
+## More features
+
+### Interrupting long-running queries
+
+When running long-running queries, you can use `Database#interrupt` to interrupt
+the query:
+
+```ruby
+timeout_thread = Thread.new do
+  sleep 10
+  db.interrupt
+end
+
+result = begin
+  db.query(super_slow_sql)
+rescue Extralite::InterruptError
+  nil
+ensure
+  timeout_thread.kill
+  timeout_thread.join
+end
+```
+
+### Creating backups
+
+You can use `Database#backup` to create backup copies of a database. The
+`#backup` method takes either a filename or a database instance:
+
+```ruby
+# with a filename
+db.backup('backup.db')
+
+# with an instance
+target = Extralite::Database.new('backup.db')
+db.backup(target)
+```
+
+For big databases, you can also track the backup progress by providing a block
+that takes two arguments - the number of remaining pages, and the total number pages:
+
+```ruby
+db.backup('backup.db') do |remaining, total|
+  puts "backup progress: #{(remaining.to_f/total * 100).round}%"
+end
+```
+
+### Retrieve status information
+
+Extralite provides methods for retrieving status information about the sqlite
+runtime, database-specific status and prepared statement-specific status,
+`Extralite.runtime_status`, `Database#status` and `PreparedStatement#status`
+respectively. You can also reset the high water mark for the specific status
+code by providing true as the reset argument. The status codes mirror those
+defined by the SQLite API. Some examples:
+
+```ruby
+# The Extralite.runtime_status returns a tuple consisting of the current value
+# and the high water mark value.
+current, high_watermark = Extralite.runtime_status(Extralite::SQLITE_STATUS_MEMORY_USED)
+
+# To reset the high water mark, pass true as a second argument:
+current, high_watermark = Extralite.runtime_status(Extralite::SQLITE_STATUS_MEMORY_USED, true)
+
+# Similarly, you can interrogate a database's status (pass true as a second
+# argument in order to reset the high watermark):
+current, high_watermark = db.status(Extralite::SQLITE_DBSTATUS_CACHE_USED)
+
+# The PreparedStatement#status method returns a single value (pass true as a
+# second argument in order to reset the high watermark):
+value = stmt.status(Extralite::SQLITE_STMTSTATUS_RUN)
+```
+
 ## Usage with Sequel
 
 Extralite includes an adapter for
@@ -179,20 +233,20 @@ p articles.to_a
 
 ## Why not just use the sqlite3 gem?
 
-The [sqlite3-ruby](https://github.com/sparklemotion/sqlite3-ruby) gem is a
+The [sqlite3](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
+Extralite is significantly [faster](#performance) than the `sqlite3` gem 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.
+using any of those features, you'll have to stick to the `sqlite3` gem.
 
 Here's a table summarizing the differences between the two gems:
 
-| |sqlite3-ruby|Extralite|
+| |sqlite3 1.6.0|Extralite 1.21|
 |-|-|-|
 |SQLite3 dependency|depends on OS-installed libsqlite3|Use either system sqlite3 or [bundled latest version of SQLite3](#installing-the-extralite-sqlite3-bundle)|
 |API design|multiple classes|single class|
@@ -203,56 +257,56 @@ Here's a table summarizing the differences between the two gems:
 |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))|
+|Code size|~2650LoC|~1300LoC|
+|Performance|1x|1.5x to 10x (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:
+bytecode, or fetching the next row. This *does not* hurt Extralite's
+performance, as you can see:
 
 ## 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
+shows Extralite to be up to ~10 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|
+|Row count|sqlite3 1.6.0|Extralite 1.21|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__|
+|10|63.7K rows/s|94.0K rows/s|__1.48x__|
+|1K|299.2K rows/s|1.983M rows/s|__6.63x__|
+|100K|185.4K rows/s|2.033M rows/s|__10.97x__|
 
 ### Rows as arrays
 
 [Benchmark source code](https://github.com/digital-fabric/extralite/blob/main/test/perf_ary.rb)
 
-|Row count|sqlite3-ruby|Extralite|Advantage|
+|Row count|sqlite3 1.6.0|Extralite 1.21|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__|
+|10|71.2K rows/s|92.1K rows/s|__1.29x__|
+|1K|502.1K rows/s|2.065M rows/s|__4.11x__|
+|100K|455.7K rows/s|2.511M rows/s|__5.51x__|
 
 ### Prepared statements
 
 [Benchmark source code](https://github.com/digital-fabric/extralite/blob/main/test/perf_prepared.rb)
 
-|Row count|sqlite3-ruby|Extralite|Advantage|
+|Row count|sqlite3 1.6.0|Extralite 1.21|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__|
+|10|232.2K rows/s|741.6K rows/s|__3.19x__|
+|1K|299.8K rows/s|2386.0M rows/s|__7.96x__|
+|100K|183.1K rows/s|1.893M rows/s|__10.34x__|
 
-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
+As those benchmarks show, Extralite is capabale of reading up to 2.5M
+rows/second when fetching rows as arrays, and up to 2M rows/second when fetching
 rows as hashes.
 
 ## License

data/ext/extralite/database.c

@@ -470,6 +470,17 @@ VALUE backup_cleanup(VALUE ptr) {
   return Qnil;
 }
 
+/* call-seq:
+ *   db.backup(dest) -> db
+ *   db.backup(dest) { |remaining, total| } -> db
+ *
+ * Creates a backup of the database to the given destination, which can be
+ * either a filename or a database instance. In order to monitor the backup
+ * progress you can pass a block that will be called periodically by the backup
+ * method with two arguments: the remaining page count, and the total page
+ * count, which can be used to display the progress to the user or to collect
+ * statistics.
+ */
 VALUE Database_backup(int argc, VALUE *argv, VALUE self) {
   VALUE dst;
   VALUE src_name;
@@ -513,8 +524,8 @@ VALUE Database_backup(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
-/*
- * Extralite.runtime_status(op[, reset]) -> [value, highwatermark]
+/* call-seq:
+ *   Extralite.runtime_status(op[, reset]) -> [value, highwatermark]
  *
  * Returns runtime status values for the given op as an array containing the
  * current value and the high water mark value. To reset the high water mark,

data/lib/extralite/version.rb

@@ -1,3 +1,3 @@
 module Extralite
-  VERSION = '1.21'
+  VERSION = '1.22'
 end

data/lib/extralite.rb

@@ -70,14 +70,26 @@ module Extralite
         AND name NOT LIKE 'sqlite_%';
     SQL
 
+    # Returns the list of currently defined tables.
+    #
+    # @return [Array] list of tables
     def tables
       query_single_column(TABLES_SQL)
     end
 
+    # Gets or sets one or more pragmas:
+    #
+    #     db.pragma(:cache_size) # get
+    #     db.pragma(cache_size: -2000) # set
+    #
+    # @param value [Symbol, String, Hash] pragma name or hash mapping names to values
+    # @return [Hash] query result
     def pragma(value)
       value.is_a?(Hash) ? pragma_set(value) : pragma_get(value)
     end
 
+    private
+
     def pragma_set(values)
       sql = values.inject(+'') { |s, (k, v)| s += "pragma #{k}=#{v}; " }
       query(sql)
@@ -87,18 +99,4 @@ module Extralite
       query("pragma #{key}")
     end
   end
-
-  # An SQLite backup
-  class Backup
-    # def initialize(dst, dst_name, src, src_name); end
-
-    # def dst; end
-    # def src; end
-
-    # def step(pages); end
-    # def finish; end
-
-    # def pagecount; end
-    # def remaining; end
-  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: extralite-bundle
 version: !ruby/object:Gem::Version
-  version: '1.21'
+  version: '1.22'
 platform: ruby
 authors:
 - Sharon Rosner