sqlite3 1.7.3 → 2.5.0

data/README.md

@@ -9,21 +9,20 @@ Note that this module is only compatible with SQLite 3.6.16 or newer.
 * Source code: https://github.com/sparklemotion/sqlite3-ruby
 * Mailing list: http://groups.google.com/group/sqlite3-ruby
 * Download: http://rubygems.org/gems/sqlite3
-* Documentation: http://www.rubydoc.info/gems/sqlite3
+* Documentation: https://sparklemotion.github.io/sqlite3-ruby/
 
-[![Unit tests](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/sqlite3-ruby.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/sqlite3-ruby.yml)
-[![Native packages](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml)
+[![Test suite](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/ci.yml)
 
 
 ## Quick start
 
-For help understanding the SQLite3 Ruby API, please read the [FAQ](./FAQ.md) and the [full API documentation](https://rubydoc.info/gems/sqlite3).
+For help understanding the SQLite3 Ruby API, please read the [FAQ](./FAQ.md) and the [full API documentation](https://sparklemotion.github.io/sqlite3-ruby/).
 
 A few key classes whose APIs are often-used are:
 
-- SQLite3::Database ([rdoc](https://rubydoc.info/gems/sqlite3/SQLite3/Database))
-- SQLite3::Statement ([rdoc](https://rubydoc.info/gems/sqlite3/SQLite3/Statement))
-- SQLite3::ResultSet ([rdoc](https://rubydoc.info/gems/sqlite3/SQLite3/ResultSet))
+- SQLite3::Database ([rdoc](https://sparklemotion.github.io/sqlite3-ruby/SQLite3/Database.html))
+- SQLite3::Statement ([rdoc](https://sparklemotion.github.io/sqlite3-ruby/SQLite3/Statement.html))
+- SQLite3::ResultSet ([rdoc](https://sparklemotion.github.io/sqlite3-ruby/SQLite3/ResultSet.html))
 
 If you have any questions that you feel should be addressed in the FAQ, please send them to [the mailing list](http://groups.google.com/group/sqlite3-ruby) or open a [discussion thread](https://github.com/sparklemotion/sqlite3-ruby/discussions/categories/q-a).
 
@@ -77,6 +76,95 @@ end
 # => ["Jane", "me@janedoe.com", "A", "http://blog.janedoe.com"]
 ```
 
+## Thread Safety
+
+When `SQLite3.threadsafe?` returns `true`, then SQLite3 has been compiled to
+support running in a multithreaded environment.  However, this doesn't mean
+that all classes in the SQLite3 gem can be considered "thread safe".
+
+When `SQLite3.threadsafe?` returns `true`, it is safe to share only
+`SQLite3::Database` instances among threads without providing your own locking
+mechanism.  For example, the following code is fine because only the database
+instance is shared among threads:
+
+```ruby
+require 'sqlite3'
+
+db = SQLite3::Database.new ":memory:"
+
+latch = Queue.new
+
+ts = 10.times.map {
+  Thread.new {
+    latch.pop
+    db.execute "SELECT '#{Thread.current.inspect}'"
+  }
+}
+10.times { latch << nil }
+
+p ts.map(&:value)
+```
+
+Other instances can be shared among threads, but they require that you provide
+your own locking for thread safety.  For example, `SQLite3::Statement` objects
+(prepared statements) are mutable, so applications must take care to add
+appropriate locks to avoid data race conditions when sharing these objects
+among threads.
+
+Lets rewrite the above example but use a prepared statement and safely share
+the prepared statement among threads:
+
+```ruby
+db = SQLite3::Database.new ":memory:"
+
+# Prepare a statement
+stmt = db.prepare "SELECT :inspect"
+stmt_lock = Mutex.new
+
+latch = Queue.new
+
+ts = 10.times.map {
+  Thread.new {
+    latch.pop
+
+    # Add a lock when using the prepared statement.
+    # Binding values, and walking over results will mutate the statement, so
+    # in order to prevent other threads from "seeing" this thread's data, we
+    # must lock when using the statement object
+    stmt_lock.synchronize do
+      stmt.execute(Thread.current.inspect).to_a
+    end
+  }
+}
+
+10.times { latch << nil }
+
+p ts.map(&:value)
+
+stmt.close
+```
+
+It is generally recommended that if applications want to share a database among
+threads, they _only_ share the database instance object.  Other objects are
+fine to share, but may require manual locking for thread safety.
+
+
+## Fork Safety
+
+[Sqlite is not fork
+safe](https://www.sqlite.org/howtocorrupt.html#_carrying_an_open_database_connection_across_a_fork_)
+and instructs users to not carry an open writable database connection across a `fork()`. Using an inherited
+connection in the child may corrupt your database, leak memory, or cause other undefined behavior.
+
+To help protect users of this gem from accidental corruption due to this lack of fork safety, the gem will immediately close any open writable databases in the child after a fork. Discarding writable
+connections in the child will incur a small one-time memory leak per connection, but that's
+preferable to potentially corrupting your database.
+
+Whenever possible, close writable connections in the parent before forking. If absolutely necessary (and you know what you're doing), you may suppress the fork safety warnings by calling `SQLite3::ForkSafety.suppress_warnings!`.
+
+See [./adr/2024-09-fork-safety.md](./adr/2024-09-fork-safety.md) for more information and context.
+
+
 ## Support
 
 ### Installation or database extensions
@@ -104,7 +192,7 @@ See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 
 This library is licensed under `BSD-3-Clause`, see [`LICENSE`](./LICENSE).
 
-
 ### Dependencies
 
-The source code of `sqlite` is distributed in the "ruby platform" gem. This code is public domain, see [`LICENSE-DEPENDENCIES`](./LICENSE-DEPENDENCIES) for details.
+The source code of `sqlite` is distributed in the "ruby platform" gem. This code is public domain,
+see https://www.sqlite.org/copyright.html for details.

data/dependencies.yml

@@ -1,14 +1,13 @@
-# TODO: stop using symbols here once we no longer support Ruby 2.7 and can rely on symbolize_names
-:sqlite3:
+sqlite3:
   # checksum verified by first checking the published sha3(256) checksum against https://sqlite.org/download.html:
-  # 1b02c58a711d15b50da8a1089e0f8807ebbdf3e674c714100eda9a03a69ac758
+  # 52cd4a2304b627abbabe1a438ba853d0f6edb8e2774fcb5773c7af11077afe94
   #
-  # $ sha3sum -a 256 ports/archives/sqlite-autoconf-3450200.tar.gz
-  # 1b02c58a711d15b50da8a1089e0f8807ebbdf3e674c714100eda9a03a69ac758  ports/archives/sqlite-autoconf-3450200.tar.gz
+  # $ sha3sum -a 256 ports/archives/sqlite-autoconf-3470200.tar.gz
+  # 52cd4a2304b627abbabe1a438ba853d0f6edb8e2774fcb5773c7af11077afe94  ports/archives/sqlite-autoconf-3470200.tar.gz
   #
-  # $ sha256sum ports/archives/sqlite-autoconf-3450200.tar.gz
-  # bc9067442eedf3dd39989b5c5cfbfff37ae66cc9c99274e0c3052dc4d4a8f6ae  ports/archives/sqlite-autoconf-3450200.tar.gz
-  :version: "3.45.2"
-  :files:
-    - :url: "https://sqlite.org/2024/sqlite-autoconf-3450200.tar.gz"
-      :sha256: "bc9067442eedf3dd39989b5c5cfbfff37ae66cc9c99274e0c3052dc4d4a8f6ae"
+  # $ sha256sum ports/archives/sqlite-autoconf-3470200.tar.gz
+  # f1b2ee412c28d7472bc95ba996368d6f0cdcf00362affdadb27ed286c179540b  ports/archives/sqlite-autoconf-3470200.tar.gz
+  version: "3.47.2"
+  files:
+    - url: "https://sqlite.org/2024/sqlite-autoconf-3470200.tar.gz"
+      sha256: "f1b2ee412c28d7472bc95ba996368d6f0cdcf00362affdadb27ed286c179540b"

data/ext/sqlite3/aggregator.c

@@ -31,20 +31,20 @@ typedef struct rb_sqlite3_protected_funcall_args {
 static VALUE
 rb_sqlite3_protected_funcall_body(VALUE protected_funcall_args_ptr)
 {
-  protected_funcall_args_t *args =
-    (protected_funcall_args_t*)protected_funcall_args_ptr;
+    protected_funcall_args_t *args =
+        (protected_funcall_args_t *)protected_funcall_args_ptr;
 
-  return rb_funcall2(args->self, args->method, args->argc, args->params);
+    return rb_funcall2(args->self, args->method, args->argc, args->params);
 }
 
 static VALUE
 rb_sqlite3_protected_funcall(VALUE self, ID method, int argc, VALUE *params,
-                             int* exc_status)
+                             int *exc_status)
 {
-  protected_funcall_args_t args = {
-    .self = self, .method = method, .argc = argc, .params = params
-  };
-  return rb_protect(rb_sqlite3_protected_funcall_body, (VALUE)(&args), exc_status);
+    protected_funcall_args_t args = {
+        .self = self, .method = method, .argc = argc, .params = params
+    };
+    return rb_protect(rb_sqlite3_protected_funcall_body, (VALUE)(&args), exc_status);
 }
 
 /* called in rb_sqlite3_aggregator_step and rb_sqlite3_aggregator_final. It
@@ -54,36 +54,36 @@ rb_sqlite3_protected_funcall(VALUE self, ID method, int argc, VALUE *params,
 static VALUE
 rb_sqlite3_aggregate_instance(sqlite3_context *ctx)
 {
-  VALUE aw = (VALUE) sqlite3_user_data(ctx);
-  VALUE handler_klass = rb_iv_get(aw, "-handler_klass");
-  VALUE inst;
-  VALUE *inst_ptr = sqlite3_aggregate_context(ctx, (int)sizeof(VALUE));
+    VALUE aw = (VALUE) sqlite3_user_data(ctx);
+    VALUE handler_klass = rb_iv_get(aw, "-handler_klass");
+    VALUE inst;
+    VALUE *inst_ptr = sqlite3_aggregate_context(ctx, (int)sizeof(VALUE));
 
-  if (!inst_ptr) {
-    rb_fatal("SQLite is out-of-merory");
-  }
+    if (!inst_ptr) {
+        rb_fatal("SQLite is out-of-merory");
+    }
 
-  inst = *inst_ptr;
+    inst = *inst_ptr;
 
-  if (inst == Qfalse) { /* Qfalse == 0 */
-    VALUE instances = rb_iv_get(aw, "-instances");
-    int exc_status;
+    if (inst == Qfalse) { /* Qfalse == 0 */
+        VALUE instances = rb_iv_get(aw, "-instances");
+        int exc_status;
 
-    inst = rb_class_new_instance(0, NULL, cAggregatorInstance);
-    rb_iv_set(inst, "-handler_instance", rb_sqlite3_protected_funcall(
-      handler_klass, rb_intern("new"), 0, NULL, &exc_status));
-    rb_iv_set(inst, "-exc_status", INT2NUM(exc_status));
+        inst = rb_class_new_instance(0, NULL, cAggregatorInstance);
+        rb_iv_set(inst, "-handler_instance", rb_sqlite3_protected_funcall(
+                      handler_klass, rb_intern("new"), 0, NULL, &exc_status));
+        rb_iv_set(inst, "-exc_status", INT2NUM(exc_status));
 
-    rb_ary_push(instances, inst);
+        rb_ary_push(instances, inst);
 
-    *inst_ptr = inst;
-  }
+        *inst_ptr = inst;
+    }
 
-  if (inst == Qnil) {
-    rb_fatal("SQLite called us back on an already destroyed aggregate instance");
-  }
+    if (inst == Qnil) {
+        rb_fatal("SQLite called us back on an already destroyed aggregate instance");
+    }
 
-  return inst;
+    return inst;
 }
 
 /* called by rb_sqlite3_aggregator_final. Unlinks and frees the
@@ -92,84 +92,84 @@ rb_sqlite3_aggregate_instance(sqlite3_context *ctx)
 static void
 rb_sqlite3_aggregate_instance_destroy(sqlite3_context *ctx)
 {
-  VALUE aw = (VALUE) sqlite3_user_data(ctx);
-  VALUE instances = rb_iv_get(aw, "-instances");
-  VALUE *inst_ptr = sqlite3_aggregate_context(ctx, 0);
-  VALUE inst;
+    VALUE aw = (VALUE) sqlite3_user_data(ctx);
+    VALUE instances = rb_iv_get(aw, "-instances");
+    VALUE *inst_ptr = sqlite3_aggregate_context(ctx, 0);
+    VALUE inst;
 
-  if (!inst_ptr || (inst = *inst_ptr)) {
-    return;
-  }
+    if (!inst_ptr || (inst = *inst_ptr)) {
+        return;
+    }
 
-  if (inst == Qnil) {
-    rb_fatal("attempt to destroy aggregate instance twice");
-  }
+    if (inst == Qnil) {
+        rb_fatal("attempt to destroy aggregate instance twice");
+    }
 
-  rb_iv_set(inst, "-handler_instance", Qnil); // may catch use-after-free
-  if (rb_ary_delete(instances, inst) == Qnil) {
-    rb_fatal("must be in instances at that point");
-  }
+    rb_iv_set(inst, "-handler_instance", Qnil); // may catch use-after-free
+    if (rb_ary_delete(instances, inst) == Qnil) {
+        rb_fatal("must be in instances at that point");
+    }
 
-  *inst_ptr = Qnil;
+    *inst_ptr = Qnil;
 }
 
 static void
-rb_sqlite3_aggregator_step(sqlite3_context * ctx, int argc, sqlite3_value **argv)
+rb_sqlite3_aggregator_step(sqlite3_context *ctx, int argc, sqlite3_value **argv)
 {
-  VALUE inst = rb_sqlite3_aggregate_instance(ctx);
-  VALUE handler_instance = rb_iv_get(inst, "-handler_instance");
-  VALUE * params = NULL;
-  VALUE one_param;
-  int exc_status = NUM2INT(rb_iv_get(inst, "-exc_status"));
-  int i;
-
-  if (exc_status) {
-    return;
-  }
-
-  if (argc == 1) {
-    one_param = sqlite3val2rb(argv[0]);
-    params = &one_param;
-  }
-  if (argc > 1) {
-    params = xcalloc((size_t)argc, sizeof(VALUE));
-    for(i = 0; i < argc; i++) {
-      params[i] = sqlite3val2rb(argv[i]);
+    VALUE inst = rb_sqlite3_aggregate_instance(ctx);
+    VALUE handler_instance = rb_iv_get(inst, "-handler_instance");
+    VALUE *params = NULL;
+    VALUE one_param;
+    int exc_status = NUM2INT(rb_iv_get(inst, "-exc_status"));
+    int i;
+
+    if (exc_status) {
+        return;
+    }
+
+    if (argc == 1) {
+        one_param = sqlite3val2rb(argv[0]);
+        params = &one_param;
     }
-  }
-  rb_sqlite3_protected_funcall(
-    handler_instance, rb_intern("step"), argc, params, &exc_status);
-  if (argc > 1) {
-    xfree(params);
-  }
-
-  rb_iv_set(inst, "-exc_status", INT2NUM(exc_status));
+    if (argc > 1) {
+        params = xcalloc((size_t)argc, sizeof(VALUE));
+        for (i = 0; i < argc; i++) {
+            params[i] = sqlite3val2rb(argv[i]);
+        }
+    }
+    rb_sqlite3_protected_funcall(
+        handler_instance, rb_intern("step"), argc, params, &exc_status);
+    if (argc > 1) {
+        xfree(params);
+    }
+
+    rb_iv_set(inst, "-exc_status", INT2NUM(exc_status));
 }
 
 /* we assume that this function is only called once per execution context */
 static void
-rb_sqlite3_aggregator_final(sqlite3_context * ctx)
+rb_sqlite3_aggregator_final(sqlite3_context *ctx)
 {
-  VALUE inst = rb_sqlite3_aggregate_instance(ctx);
-  VALUE handler_instance = rb_iv_get(inst, "-handler_instance");
-  int exc_status = NUM2INT(rb_iv_get(inst, "-exc_status"));
+    VALUE inst = rb_sqlite3_aggregate_instance(ctx);
+    VALUE handler_instance = rb_iv_get(inst, "-handler_instance");
+    int exc_status = NUM2INT(rb_iv_get(inst, "-exc_status"));
 
-  if (!exc_status) {
-    VALUE result = rb_sqlite3_protected_funcall(
-      handler_instance, rb_intern("finalize"), 0, NULL, &exc_status);
     if (!exc_status) {
-      set_sqlite3_func_result(ctx, result);
+        VALUE result = rb_sqlite3_protected_funcall(
+                           handler_instance, rb_intern("finalize"), 0, NULL, &exc_status);
+        if (!exc_status) {
+            set_sqlite3_func_result(ctx, result);
+        }
     }
-  }
 
-  if (exc_status) {
-    /* the user should never see this, as Statement.step() will pick up the
-     * outstanding exception and raise it instead of generating a new one
-     * for SQLITE_ERROR with message "Ruby Exception occurred" */
-    sqlite3_result_error(ctx, "Ruby Exception occurred", -1);
-  }
+    if (exc_status) {
+        /* the user should never see this, as Statement.step() will pick up the
+         * outstanding exception and raise it instead of generating a new one
+         * for SQLITE_ERROR with message "Ruby Exception occurred" */
+        sqlite3_result_error(ctx, "Ruby Exception occurred", -1);
+    }
 
-  rb_sqlite3_aggregate_instance_destroy(ctx);
+    rb_sqlite3_aggregate_instance_destroy(ctx);
 }
 
 /* call-seq: define_aggregator2(aggregator)
@@ -205,69 +205,66 @@ rb_sqlite3_aggregator_final(sqlite3_context * ctx)
 VALUE
 rb_sqlite3_define_aggregator2(VALUE self, VALUE aggregator, VALUE ruby_name)
 {
-  /* define_aggregator is added as a method to SQLite3::Database in database.c */
-  sqlite3RubyPtr ctx = sqlite3_database_unwrap(self);
-  int arity, status;
-  VALUE aw;
-  VALUE aggregators;
-
-  if (!ctx->db) {
-    rb_raise(rb_path2class("SQLite3::Exception"), "cannot use a closed database");
-  }
-
-  if (rb_respond_to(aggregator, rb_intern("arity"))) {
-    VALUE ruby_arity = rb_funcall(aggregator, rb_intern("arity"), 0);
-    arity = NUM2INT(ruby_arity);
-  } else {
-    arity = -1;
-  }
-
-  if (arity < -1 || arity > 127) {
+    /* define_aggregator is added as a method to SQLite3::Database in database.c */
+    sqlite3RubyPtr ctx = sqlite3_database_unwrap(self);
+    int arity, status;
+    VALUE aw;
+    VALUE aggregators;
+
+    if (!ctx->db) {
+        rb_raise(rb_path2class("SQLite3::Exception"), "cannot use a closed database");
+    }
+
+    if (rb_respond_to(aggregator, rb_intern("arity"))) {
+        VALUE ruby_arity = rb_funcall(aggregator, rb_intern("arity"), 0);
+        arity = NUM2INT(ruby_arity);
+    } else {
+        arity = -1;
+    }
+
+    if (arity < -1 || arity > 127) {
 #ifdef PRIsVALUE
-    rb_raise(rb_eArgError, "%"PRIsVALUE" arity=%d out of range -1..127",
-            self, arity);
+        rb_raise(rb_eArgError, "%"PRIsVALUE" arity=%d out of range -1..127",
+                 self, arity);
 #else
-    rb_raise(rb_eArgError, "Aggregator arity=%d out of range -1..127", arity);
+        rb_raise(rb_eArgError, "Aggregator arity=%d out of range -1..127", arity);
 #endif
-  }
-
-  if (!rb_ivar_defined(self, rb_intern("-aggregators"))) {
-    rb_iv_set(self, "-aggregators", rb_ary_new());
-  }
-  aggregators = rb_iv_get(self, "-aggregators");
-
-  aw = rb_class_new_instance(0, NULL, cAggregatorWrapper);
-  rb_iv_set(aw, "-handler_klass", aggregator);
-  rb_iv_set(aw, "-instances", rb_ary_new());
-
-  status = sqlite3_create_function(
-    ctx->db,
-    StringValueCStr(ruby_name),
-    arity,
-    SQLITE_UTF8,
-    (void*)aw,
-    NULL,
-    rb_sqlite3_aggregator_step,
-    rb_sqlite3_aggregator_final
-  );
-
-  if (status != SQLITE_OK) {
-    rb_sqlite3_raise(ctx->db, status);
-    return self; // just in case rb_sqlite3_raise returns.
-  }
-
-  rb_ary_push(aggregators, aw);
-
-  return self;
+    }
+
+    if (!rb_ivar_defined(self, rb_intern("-aggregators"))) {
+        rb_iv_set(self, "-aggregators", rb_ary_new());
+    }
+    aggregators = rb_iv_get(self, "-aggregators");
+
+    aw = rb_class_new_instance(0, NULL, cAggregatorWrapper);
+    rb_iv_set(aw, "-handler_klass", aggregator);
+    rb_iv_set(aw, "-instances", rb_ary_new());
+
+    status = sqlite3_create_function(
+                 ctx->db,
+                 StringValueCStr(ruby_name),
+                 arity,
+                 SQLITE_UTF8,
+                 (void *)aw,
+                 NULL,
+                 rb_sqlite3_aggregator_step,
+                 rb_sqlite3_aggregator_final
+             );
+
+    CHECK(ctx->db, status);
+
+    rb_ary_push(aggregators, aw);
+
+    return self;
 }
 
 void
 rb_sqlite3_aggregator_init(void)
 {
-  /* rb_class_new generatos class with undefined allocator in ruby 1.9 */
-  cAggregatorWrapper = rb_funcall(rb_cClass, rb_intern("new"), 0);
-  rb_gc_register_mark_object(cAggregatorWrapper);
+    /* rb_class_new generatos class with undefined allocator in ruby 1.9 */
+    cAggregatorWrapper = rb_funcall(rb_cClass, rb_intern("new"), 0);
+    rb_gc_register_mark_object(cAggregatorWrapper);
 
-  cAggregatorInstance = rb_funcall(rb_cClass, rb_intern("new"), 0);
-  rb_gc_register_mark_object(cAggregatorInstance);
+    cAggregatorInstance = rb_funcall(rb_cClass, rb_intern("new"), 0);
+    rb_gc_register_mark_object(cAggregatorInstance);
 }

data/ext/sqlite3/aggregator.h

@@ -3,10 +3,8 @@
 
 #include <sqlite3_ruby.h>
 
-VALUE
-rb_sqlite3_define_aggregator2(VALUE self, VALUE aggregator, VALUE ruby_name);
+VALUE rb_sqlite3_define_aggregator2(VALUE self, VALUE aggregator, VALUE ruby_name);
 
-void
-rb_sqlite3_aggregator_init(void);
+void rb_sqlite3_aggregator_init(void);
 
 #endif