extralite 1.21 → 1.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b705a2d1c970cb3e73c784a6322ea92e8f7618531b4d8b9c2d4e036bf135b0f
-  data.tar.gz: fceaaf8976cac3d5e5328d64e8e76d07fe5979e4897ad7f20bb6295f697659b7
+  metadata.gz: 7466fb655d5f2cc65862d604190d52208773a9cc8fb611b184bc46a20ccb8d1f
+  data.tar.gz: bbc9b59c5c2297df34d716a19b53ccc95008bea3be4d38d3cdd91340089962b5
 SHA512:
-  metadata.gz: c1b1bc996aa69b8f4abd4888a23a3aeae0aa15069b5d7c13027389e6165529186949ed8679571b55c00f3b76bd5360f396e874dd4c73f3d88cd8443c8931fca9
-  data.tar.gz: aca5d4470770f5c635d2d3b42a1897c45535efd29a38137c3164c07629f3f68a3cc1f74f95cef180efe06b9cb5423bb8fe95e183c7001c98a05baa0f3532718e
+  metadata.gz: 227a7fb703cca6eed8b25f0adb32cf8421f3c503149a715006c381d5cca475e692048650acc561ccfcb5ff1203c489fa6fe429922aecb2c0486cd0ec83c85360
+  data.tar.gz: 131aa35e939c4623a306be6e7a756d40cfe77a5b199ffc90cb1937194e7066ba6fa4de3d4cc8618b8123b68dcfe9e92a60b3e821c49b51145497deb005467f24

data/.github/workflows/test.yml

@@ -8,7 +8,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby: ['2.7', '3.0', '3.1', truffleruby]
+        ruby: ['3.0', '3.1', '3.2', truffleruby]
 
     name: >-
       ${{matrix.os}}, ${{matrix.ruby}}

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# 1.23 2023-01-26
+
+- Add `Database#trace` (#21)
+- Add `Database#total_changes` (#20)
+- Add `Database#busy_timeout=` (#19)
+- Add `Database#limit` (#16)
+- Improve error handling
+
+# 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.23)
 
 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 11x 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
 
@@ -70,20 +48,21 @@ gem 'extralite'
 
 You can also run `gem install extralite` if you just want to check it out.
 
-### Installing the Extralite-SQLite3 bundle
+### 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.
+> **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,114 @@ 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
+```
+
+### Retrieving 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)
+```
+
+### Working with Database Limits
+
+The `Database#limit` can be used to get and set various database limits, as
+[discussed in the SQLite docs](https://www.sqlite.org/limits.html):
+
+```ruby
+# get limit
+value = db.limit(Extralite::SQLITE_LIMIT_ATTACHED)
+
+# set limit
+db.limit(Extralite::SQLITE_LIMIT_ATTACHED, new_value)
+```
+
+### Setting the Busy Timeout
+
+When accessing a database concurrently it can be handy to set a busy timeout, in
+order to not have to deal with rescuing `Extralite::BusyError` exceptions. The
+timeout is given in seconds:
+
+```ruby
+db.busy_timeout = 5
+```
+
+### Tracing SQL Statements
+
+To trace all SQL statements executed on the database, pass a block to
+`Database#trace`. To disable tracing, call `Database#trace` without a block:
+
+```ruby
+# enable tracing
+db.trace { |sql| puts sql: sql }
+
+# disable tracing
+db.trace
+```
+
 ## Usage with Sequel
 
 Extralite includes an adapter for
@@ -177,82 +267,53 @@ 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|Use either system sqlite3 or [bundled latest version of SQLite3](#installing-the-extralite-sqlite3-bundle)|
-|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:
+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 ~11 times faster than `sqlite3` when fetching a
 large number of rows.
 
-### Rows as hashes
+### 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
+### 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
+### 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/common.c

@@ -174,7 +174,7 @@ void prepare_multi_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
   case SQLITE_ERROR:
     rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
   default:
-    rb_raise(cError, "Invalid return code for prepare_multi_stmt_without_gvl: %d (please open an issue on https://github.com/digital-fabric/extralite)", ctx.rc);
+    rb_raise(cError, "%s", sqlite3_errmsg(db));
   }
 }
 
@@ -216,9 +216,9 @@ void prepare_single_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
   case SQLITE_ERROR:
     rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
   case SQLITE_MULTI_STMT:
-    rb_raise(cSQLError, "A prepared statement does not accept SQL strings with multiple queries");
+    rb_raise(cError, "A prepared statement does not accept SQL strings with multiple queries");
   default:
-    rb_raise(cError, "Invalid return code for prepare_multi_stmt_without_gvl: %d (please open an issue on https://github.com/digital-fabric/extralite)", ctx.rc);
+    rb_raise(cError, "%s", sqlite3_errmsg(db));
   }
 }
 
@@ -248,7 +248,7 @@ int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db) {
     case SQLITE_ERROR:
       rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
     default:
-      rb_raise(cError, "Invalid return code for sqlite3_step: %d (please open an issue on https://github.com/digital-fabric/extralite)", ctx.rc);
+      rb_raise(cError, "%s", sqlite3_errmsg(db));
   }
 
   return 0;

data/ext/extralite/database.c

@@ -7,6 +7,7 @@ VALUE cSQLError;
 VALUE cBusyError;
 VALUE cInterruptError;
 
+ID ID_CALL;
 ID ID_KEYS;
 ID ID_NEW;
 ID ID_STRIP;
@@ -45,6 +46,12 @@ static VALUE Database_allocate(VALUE klass) {
   } \
 }
 
+Database_t *Database_struct(VALUE self) {
+  Database_t *db;
+  GetDatabase(self, db);
+  return db;
+}
+
 sqlite3 *Database_sqlite3_db(VALUE self) {
   Database_t *db;
   GetDatabase(self, db);
@@ -86,6 +93,8 @@ VALUE Database_initialize(VALUE self, VALUE path) {
   }
 #endif
 
+  db->trace_block = Qnil;
+
   return Qnil;
 }
 
@@ -134,6 +143,7 @@ static inline VALUE Database_perform_query(int argc, VALUE *argv, VALUE self, VA
 
   // prepare query ctx
   GetOpenDatabase(self, db);
+  if (db->trace_block != Qnil) rb_funcall(db->trace_block, ID_CALL, 1, sql);
   prepare_multi_stmt(db->sqlite3_db, &stmt, sql);
   bind_all_parameters(stmt, argc - 1, argv + 1);
   query_ctx ctx = { self, db->sqlite3_db, stmt };
@@ -470,6 +480,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 +534,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,
@@ -539,7 +560,7 @@ VALUE Extralite_runtime_status(int argc, VALUE* argv, VALUE self) {
  * current value and the high water mark value. To reset the high water mark,
  * pass true as reset.
  */
-VALUE Database_status(int argc, VALUE* argv, VALUE self) {
+VALUE Database_status(int argc, VALUE *argv, VALUE self) {
   VALUE op, reset;
   int cur, hwm;
 
@@ -554,6 +575,75 @@ VALUE Database_status(int argc, VALUE* argv, VALUE self) {
   return rb_ary_new3(2, INT2NUM(cur), INT2NUM(hwm));
 }
 
+/* call-seq:
+ *   db.limit(category) -> value
+ *   db.limit(category, new_value) -> prev_value
+ *
+ * Returns the current limit for the given category. If a new value is given,
+ * sets the limit to the new value and returns the previous value.
+ */
+VALUE Database_limit(int argc, VALUE *argv, VALUE self) {
+  VALUE category, new_value;
+
+  rb_scan_args(argc, argv, "11", &category, &new_value);
+
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  int value = sqlite3_limit(db->sqlite3_db, NUM2INT(category), RTEST(new_value) ? NUM2INT(new_value) : -1);
+
+  if (value == -1) rb_raise(cError, "Invalid limit category");
+
+  return INT2NUM(value);
+}
+
+/* call-seq:
+ *   db.busy_timeout=(sec) -> db
+ *   db.busy_timeout=nil -> db
+ *
+ * Sets the busy timeout for the database, in seconds or fractions thereof. To
+ * disable the busy timeout, set it to 0 or nil.
+ */
+VALUE Database_busy_timeout_set(VALUE self, VALUE sec) {
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  int ms = (sec == Qnil) ? 0 : (int)(NUM2DBL(sec) * 1000);
+
+  int rc = sqlite3_busy_timeout(db->sqlite3_db, ms);
+  if (rc != SQLITE_OK) rb_raise(cError, "Failed to set busy timeout");
+
+  return self;
+}
+
+/* call-seq:
+ *   db.total_changes -> value
+ *
+ * Returns the total number of changes made to the database since opening it.
+ */
+VALUE Database_total_changes(VALUE self) {
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  int value = sqlite3_total_changes(db->sqlite3_db);
+  return INT2NUM(value);
+}
+
+/* call-seq:
+ *   db.trace { |sql| } -> db
+ *   db.trace -> db
+ *
+ * Installs or removes a block that will be invoked for every SQL statement
+ * executed.
+ */
+VALUE Database_trace(VALUE self) {
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  db->trace_block = rb_block_given_p() ? rb_block_proc() : Qnil;
+  return self;
+}
+
 void Init_ExtraliteDatabase(void) {
   VALUE mExtralite = rb_define_module("Extralite");
   rb_define_singleton_method(mExtralite, "runtime_status", Extralite_runtime_status, -1);
@@ -563,6 +653,7 @@ void Init_ExtraliteDatabase(void) {
   rb_define_alloc_func(cDatabase, Database_allocate);
 
   rb_define_method(cDatabase, "backup", Database_backup, -1);
+  rb_define_method(cDatabase, "busy_timeout=", Database_busy_timeout_set, 1);
   rb_define_method(cDatabase, "changes", Database_changes, 0);
   rb_define_method(cDatabase, "close", Database_close, 0);
   rb_define_method(cDatabase, "closed?", Database_closed_p, 0);
@@ -572,6 +663,7 @@ void Init_ExtraliteDatabase(void) {
   rb_define_method(cDatabase, "initialize", Database_initialize, 1);
   rb_define_method(cDatabase, "interrupt", Database_interrupt, 0);
   rb_define_method(cDatabase, "last_insert_rowid", Database_last_insert_rowid, 0);
+  rb_define_method(cDatabase, "limit", Database_limit, -1);
   rb_define_method(cDatabase, "prepare", Database_prepare, 1);
   rb_define_method(cDatabase, "query", Database_query_hash, -1);
   rb_define_method(cDatabase, "query_ary", Database_query_ary, -1);
@@ -580,6 +672,8 @@ void Init_ExtraliteDatabase(void) {
   rb_define_method(cDatabase, "query_single_row", Database_query_single_row, -1);
   rb_define_method(cDatabase, "query_single_value", Database_query_single_value, -1);
   rb_define_method(cDatabase, "status", Database_status, -1);
+  rb_define_method(cDatabase, "total_changes", Database_total_changes, 0);
+  rb_define_method(cDatabase, "trace", Database_trace, 0);
   rb_define_method(cDatabase, "transaction_active?", Database_transaction_active_p, 0);
 
 #ifdef HAVE_SQLITE3_LOAD_EXTENSION
@@ -595,6 +689,7 @@ void Init_ExtraliteDatabase(void) {
   rb_gc_register_mark_object(cBusyError);
   rb_gc_register_mark_object(cInterruptError);
 
+  ID_CALL   = rb_intern("call");
   ID_KEYS   = rb_intern("keys");
   ID_NEW    = rb_intern("new");
   ID_STRIP  = rb_intern("strip");

data/ext/extralite/extralite.h

@@ -27,6 +27,7 @@ extern VALUE cSQLError;
 extern VALUE cBusyError;
 extern VALUE cInterruptError;
 
+extern ID ID_CALL;
 extern ID ID_KEYS;
 extern ID ID_NEW;
 extern ID ID_STRIP;
@@ -34,11 +35,13 @@ extern ID ID_TO_S;
 
 typedef struct {
   sqlite3 *sqlite3_db;
+  VALUE trace_block;
 } Database_t;
 
 typedef struct {
   VALUE db;
   VALUE sql;
+  Database_t *db_struct;
   sqlite3 *sqlite3_db;
   sqlite3_stmt *stmt;
 } PreparedStatement_t;
@@ -72,5 +75,6 @@ int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db);
 VALUE cleanup_stmt(query_ctx *ctx);
 
 sqlite3 *Database_sqlite3_db(VALUE self);
+Database_t *Database_struct(VALUE self);
 
 #endif /* EXTRALITE_H */

data/ext/extralite/prepared_statement.c

@@ -50,6 +50,7 @@ VALUE PreparedStatement_initialize(VALUE self, VALUE db, VALUE sql) {
     rb_raise(cError, "Cannot prepare an empty SQL query");
 
   stmt->db = db;
+  stmt->db_struct = Database_struct(db);
   stmt->sqlite3_db = Database_sqlite3_db(db);
   stmt->sql = sql;
 
@@ -65,6 +66,8 @@ static inline VALUE PreparedStatement_perform_query(int argc, VALUE *argv, VALUE
   if (!stmt->stmt)
     rb_raise(cError, "Prepared statement is closed");
 
+  if (stmt->db_struct->trace_block != Qnil) rb_funcall(stmt->db_struct->trace_block, ID_CALL, 1, stmt->sql);
+
   sqlite3_reset(stmt->stmt);
   sqlite3_clear_bindings(stmt->stmt);
   bind_all_parameters(stmt->stmt, argc, argv);

data/lib/extralite/sqlite3_constants.rb

@@ -0,0 +1,50 @@
+module Extralite
+
+  SQLITE_STATUS_MEMORY_USED           =  0
+  SQLITE_STATUS_PAGECACHE_USED        =  1
+  SQLITE_STATUS_PAGECACHE_OVERFLOW    =  2
+  SQLITE_STATUS_SCRATCH_USED          =  3 # NOT USED
+  SQLITE_STATUS_SCRATCH_OVERFLOW      =  4 # NOT USED
+  SQLITE_STATUS_MALLOC_SIZE           =  5
+  SQLITE_STATUS_PARSER_STACK          =  6
+  SQLITE_STATUS_PAGECACHE_SIZE        =  7
+  SQLITE_STATUS_SCRATCH_SIZE          =  8 # NOT USED
+  SQLITE_STATUS_MALLOC_COUNT          =  9
+
+  SQLITE_DBSTATUS_LOOKASIDE_USED      =  0
+  SQLITE_DBSTATUS_CACHE_USED          =  1
+  SQLITE_DBSTATUS_SCHEMA_USED         =  2
+  SQLITE_DBSTATUS_STMT_USED           =  3
+  SQLITE_DBSTATUS_LOOKASIDE_HIT       =  4
+  SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE =  5
+  SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL =  6
+  SQLITE_DBSTATUS_CACHE_HIT           =  7
+  SQLITE_DBSTATUS_CACHE_MISS          =  8
+  SQLITE_DBSTATUS_CACHE_WRITE         =  9
+  SQLITE_DBSTATUS_DEFERRED_FKS        = 10
+  SQLITE_DBSTATUS_CACHE_USED_SHARED   = 11
+  SQLITE_DBSTATUS_CACHE_SPILL         = 12
+
+  SQLITE_STMTSTATUS_FULLSCAN_STEP     =  1
+  SQLITE_STMTSTATUS_SORT              =  2
+  SQLITE_STMTSTATUS_AUTOINDEX         =  3
+  SQLITE_STMTSTATUS_VM_STEP           =  4
+  SQLITE_STMTSTATUS_REPREPARE         =  5
+  SQLITE_STMTSTATUS_RUN               =  6
+  SQLITE_STMTSTATUS_FILTER_MISS       =  7
+  SQLITE_STMTSTATUS_FILTER_HIT        =  8
+  SQLITE_STMTSTATUS_MEMUSED           = 99
+
+  SQLITE_LIMIT_LENGTH                 =  0
+  SQLITE_LIMIT_SQL_LENGTH             =  1
+  SQLITE_LIMIT_COLUMN                 =  2
+  SQLITE_LIMIT_EXPR_DEPTH             =  3
+  SQLITE_LIMIT_COMPOUND_SELECT        =  4
+  SQLITE_LIMIT_VDBE_OP                =  5
+  SQLITE_LIMIT_FUNCTION_ARG           =  6
+  SQLITE_LIMIT_ATTACHED               =  7
+  SQLITE_LIMIT_LIKE_PATTERN_LENGTH    =  8
+  SQLITE_LIMIT_VARIABLE_NUMBER        =  9
+  SQLITE_LIMIT_TRIGGER_DEPTH          = 10
+  SQLITE_LIMIT_WORKER_THREADS         = 11  
+end

data/lib/extralite/version.rb

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

data/lib/extralite.rb

@@ -1,46 +1,11 @@
 require_relative './extralite_ext'
+require_relative './extralite/sqlite3_constants'
 
 # Extralite is a Ruby gem for working with SQLite databases
 module Extralite
-  
-  SQLITE_STATUS_MEMORY_USED           =  0
-  SQLITE_STATUS_PAGECACHE_USED        =  1
-  SQLITE_STATUS_PAGECACHE_OVERFLOW    =  2
-  SQLITE_STATUS_SCRATCH_USED          =  3 # NOT USED
-  SQLITE_STATUS_SCRATCH_OVERFLOW      =  4 # NOT USED
-  SQLITE_STATUS_MALLOC_SIZE           =  5
-  SQLITE_STATUS_PARSER_STACK          =  6
-  SQLITE_STATUS_PAGECACHE_SIZE        =  7
-  SQLITE_STATUS_SCRATCH_SIZE          =  8 # NOT USED
-  SQLITE_STATUS_MALLOC_COUNT          =  9
 
-  SQLITE_DBSTATUS_LOOKASIDE_USED      =  0
-  SQLITE_DBSTATUS_CACHE_USED          =  1
-  SQLITE_DBSTATUS_SCHEMA_USED         =  2
-  SQLITE_DBSTATUS_STMT_USED           =  3
-  SQLITE_DBSTATUS_LOOKASIDE_HIT       =  4
-  SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE =  5
-  SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL =  6
-  SQLITE_DBSTATUS_CACHE_HIT           =  7
-  SQLITE_DBSTATUS_CACHE_MISS          =  8
-  SQLITE_DBSTATUS_CACHE_WRITE         =  9
-  SQLITE_DBSTATUS_DEFERRED_FKS        = 10
-  SQLITE_DBSTATUS_CACHE_USED_SHARED   = 11
-  SQLITE_DBSTATUS_CACHE_SPILL         = 12
-
-  SQLITE_STMTSTATUS_FULLSCAN_STEP     =  1
-  SQLITE_STMTSTATUS_SORT              =  2
-  SQLITE_STMTSTATUS_AUTOINDEX         =  3
-  SQLITE_STMTSTATUS_VM_STEP           =  4
-  SQLITE_STMTSTATUS_REPREPARE         =  5
-  SQLITE_STMTSTATUS_RUN               =  6
-  SQLITE_STMTSTATUS_FILTER_MISS       =  7
-  SQLITE_STMTSTATUS_FILTER_HIT        =  8
-  SQLITE_STMTSTATUS_MEMUSED           = 99
-
-  # The following class definitions are not really needed, as they're already
-  # defined in the C extension. We put them here for the sake of generating
-  # docs.
+  # The following error classes are already defined in the C extension. We put
+  # them here for the sake of generating docs.
 
   # A base class for Extralite exceptions
   class Error < ::StandardError
@@ -70,14 +35,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 +64,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

data/test/test_database.rb

@@ -269,6 +269,68 @@ end
   def test_database_status
     assert_operator 0, :<, @db.status(Extralite::SQLITE_DBSTATUS_SCHEMA_USED).first
   end
+
+  def test_database_limit
+    result = @db.limit(Extralite::SQLITE_LIMIT_ATTACHED)
+    assert_equal 10, result
+
+    result = @db.limit(Extralite::SQLITE_LIMIT_ATTACHED, 5)
+    assert_equal 10, result
+
+    result = @db.limit(Extralite::SQLITE_LIMIT_ATTACHED)
+    assert_equal 5, result
+
+    assert_raises(Extralite::Error) { @db.limit(-999) }
+  end
+
+  def test_database_busy_timeout
+    fn = "/tmp/extralite-#{rand(10000)}.db"
+    db1 = Extralite::Database.new(fn)
+    db2 = Extralite::Database.new(fn)
+    
+    db1.query('begin exclusive')
+    assert_raises(Extralite::BusyError) { db2.query('begin exclusive') }
+
+    db2.busy_timeout = 0.3
+    t0 = Time.now
+    t = Thread.new { sleep 0.1; db1.query('rollback') }
+    result = db2.query('begin exclusive')
+    t1 = Time.now
+
+    assert_equal [], result
+    assert t1 - t0 >= 0.1
+    db2.query('rollback')
+
+    # try to provoke a timeout
+    db1.query('begin exclusive')
+    db2.busy_timeout = 0.1
+    t0 = Time.now
+    t = Thread.new do
+      sleep 0.5
+    ensure
+      db1.query('rollback')
+    end
+    assert_raises(Extralite::BusyError) { db2.query('begin exclusive') }
+    t1 = Time.now
+    assert t1 - t0 >= 0.1
+    t.kill
+    t.join
+
+    db1.query('begin exclusive')
+    db2.busy_timeout = 0
+    assert_raises(Extralite::BusyError) { db2.query('begin exclusive') }
+
+    db2.busy_timeout = nil
+    assert_raises(Extralite::BusyError) { db2.query('begin exclusive') }
+  end
+
+  def test_database_total_changes
+    assert_equal 2, @db.total_changes
+
+    @db.query('insert into t values (7, 8, 9)')
+
+    assert_equal 3, @db.total_changes
+  end
 end
 
 class ScenarioTest < MiniTest::Test
@@ -336,6 +398,30 @@ class ScenarioTest < MiniTest::Test
     result = @db.query_single_column('select x from t')
     assert_equal [1, 4, 7], result
   end
+
+  def test_database_trace
+    sqls = []
+    @db.trace { |sql| sqls << sql }
+
+    @db.query('select 1')
+    assert_equal ['select 1'], sqls
+
+    @db.query('select 2')
+    assert_equal ['select 1', 'select 2'], sqls
+
+    stmt = @db.prepare('select 3')
+    
+    stmt.query
+    assert_equal ['select 1', 'select 2', 'select 3'], sqls
+
+    # turn off
+    @db.trace
+
+    stmt.query
+
+    @db.query('select 4')
+    assert_equal ['select 1', 'select 2', 'select 3'], sqls
+  end
 end
 
 class BackupTest < MiniTest::Test

data/test/test_prepared_statement.rb

@@ -37,6 +37,11 @@ class PreparedStatementTest < MiniTest::Test
     assert_raises(Extralite::SQLError) { @db.prepare('blah') }
   end
 
+  def test_prepared_statement_with_multiple_queries
+    error = begin; @db.prepare('select 1; select 2'); rescue => e; error = e; end
+    assert_equal Extralite::Error, error.class
+  end
+
   def test_prepared_statement_query_hash
     r = @stmt.query_hash(4)
     assert_equal [{x: 4, y: 5, z: 6}], r

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: extralite
 version: !ruby/object:Gem::Version
-  version: '1.21'
+  version: '1.23'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-23 00:00:00.000000000 Z
+date: 2023-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -113,6 +113,7 @@ files:
 - extralite.gemspec
 - gemspec.rb
 - lib/extralite.rb
+- lib/extralite/sqlite3_constants.rb
 - lib/extralite/version.rb
 - lib/sequel/adapters/extralite.rb
 - test/extensions/text.dylib