sqlite3 2.10.1-aarch64-linux-gnu → 2.10.2-aarch64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 012660cbfb4c148a0a1ae84db94abffcacaafaf1e866c9599d90b62020843090
-  data.tar.gz: e64a827ff503d1fd7d817af683f53d9d953f43fe88be3dbed15e6bf2edbf0f3d
+  metadata.gz: f9127458a40883ef9822507597470fd696e1d9a8bd00b14d43a9b9544d92d558
+  data.tar.gz: d827e966f0ab36f8ec315dab41b1f2e2a8fbc292b451b7a77d6974e81c33eca4
 SHA512:
-  metadata.gz: a1ffb80013b3494a09092ecb6e8b6e914b927e966aaa70aaaddc10e22f71dddbd71eca19187d50d4a4bfbeb604b718b538d8aead84fa8a9cbba5495b20bc02cf
-  data.tar.gz: 2f30fc1f82cc7d9fbd2e6767269958a0608a3ce05507ffd4a4c51669f8516c08e78a548f0d051ed0d1ab13b17b459498516736a75b613ae581b2112c14171fb2
+  metadata.gz: e263760d40f9a5002da1ddccb43a84a2bb484226c14b4a68f67db801d61a22f6df42ae26d27259c4157107c2d0e872fdae17942e066a4e8e293237e5fc0ef267
+  data.tar.gz: 8665adb90d725c905d79bf1dc81b64d92a7e972037b2e849c3b64b8695f260f735079f6fd52ba991f4ee131f17d255af41b60d40b9d05e4184444371a2245aa8

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # sqlite3-ruby Changelog
 
+## 2.10.2 / 2026-10-26
+
+### Security / Stability
+
+- Raise `RangeError` when a SQL string, a bound String or Blob value, or a String or Blob returned from a custom function or aggregate is longer than `INT_MAX` bytes. Previously the length was truncated to 32 bits, so SQLite could read only part of the string and drop trailing clauses from a query. See [GHSA-4fqr-96q8-xrfx](https://github.com/sparklemotion/sqlite3-ruby/security/advisories/GHSA-4fqr-96q8-xrfx) for more information. #762 @flavorjones
+- Fix a crash when a custom aggregate's `finalize` returns a value that can't be converted to a SQLite result. The exception is now raised from the query and the connection remains usable. #762 @flavorjones
+- Fix a use-after-free when the hash returned by `Database#collations` is cleared, modified or frozen. GC could free a comparator that SQLite still called. When that hash is frozen, `Database#collation` still raises `FrozenError`, but the new comparator stays registered and in use. #764 @flavorjones
+- Fix a deadlock when a collation comparator, `trace` block, `busy_handler` block or authorizer raises, or when an interrupt such as `Thread#raise` arrives while an aggregate's handler is being created. Another thread that used the connection blocked forever. The exception is now raised from the query and the connection remains usable. See "Changed" below for what SQLite does before the exception is raised. #764 @flavorjones
+- Fix a crash when a custom function or aggregate uses `throw`. The throw now unwinds to its `catch`. #764 @flavorjones
+
+### Changed
+
+- When a callback raises or throws, SQLite now finishes its current call before the exception is raised, instead of being unwound in the middle of it. #764 @flavorjones
+  - When a `trace` block raises, SQLite runs the statement up to its first row, or to completion, before the exception is raised. Previously the statement stopped where the block raised. For example, an `INSERT` whose `trace` block raises now inserts its row.
+  - The other callbacks in that SQLite call skip their Ruby code: collation comparators return 0, functions and aggregates report an error to SQLite, the busy handler stops retrying and the authorizer denies.
+  - `Database#execute_batch2` now raises the exception from a custom function, instead of `SQLite3::SQLException` "Ruby Exception occurred".
+  - An exception from a callback that SQLite runs during `Statement#reset!` or `Database#close` is discarded.
+- The extension keeps per-fiber state in `Thread.current[:__sqlite3_callback_frames__]`. A query raises `FrozenError` on a `Thread` that was frozen before its first query. #764 @flavorjones
+- When SQLite can't allocate an aggregate's context, the query raises `SQLite3::MemoryException` instead of aborting the process. #764 @flavorjones
+
+### Improved
+
+- `Statement#step` no longer allocates and discards an array when the statement has no more rows. This saves one object per statement execution. #758 @thomasklemm
+- `ObjectSpace.dump` and heap profilers now report `SQLite3::Database` and `SQLite3::Statement` objects under their own type names, instead of `SQLite3::Backup`. #764 @flavorjones
+
+### Documentation
+
+- Document that parameters bound by `Statement#execute`, `#execute!`, `#bind_param` and `#bind_params` stay bound across executions, and that `Statement#clear_bindings!` clears them. #751 @flavorjones
+
+
 ## 2.10.1 / 2026-10-19
 
 ### Dependencies

data/FAQ.md

@@ -209,6 +209,25 @@ Or do a `Database#prepare` to get the `Statement`, and then use either
   stmt.bind_params( "value", "name" => "bob" )
 ```
 
+Bound values stay bound across executions of the statement, including values
+passed to `Statement#execute`. A later `#execute` that omits a parameter uses
+the value bound earlier. Call `Statement#clear_bindings!` to set every
+parameter back to NULL:
+
+
+```ruby
+  stmt = db.prepare( "select :a, :b" )
+
+  stmt.execute( a: 1, b: 2 ).to_a  # => [[1, 2]]
+  stmt.execute( a: 3 ).to_a        # => [[3, 2]]
+
+  stmt.clear_bindings!
+  stmt.execute( a: 3 ).to_a        # => [[3, nil]]
+```
+
+`Database#execute` and the related `Database` methods prepare a new statement
+for each call, so values bound in one call never carry over to the next.
+
 ## How do I discover metadata about a query result?
   
 IMPORTANT: `Database#execute` returns an Array of Array of Strings

data/ext/sqlite3/aggregator.c

@@ -14,165 +14,149 @@ static VALUE cAggregatorWrapper;
  * the xFinal callback.
  *
  * An AggregatorInstance holds the following instance variables:
- * -handler_instance: the instance to call `step` and `finalize` on.
- * -exc_status:       status returned by rb_protect.
- *                    != 0 if an exception occurred. If an exception occurred
- *                    `step` and `finalize` won't be called any more. */
+ * -handler_instance: the instance to call `step` and `finalize` on. */
 static VALUE cAggregatorInstance;
 
-typedef struct rb_sqlite3_protected_funcall_args {
-    VALUE self;
-    ID method;
-    int argc;
-    VALUE *params;
-} protected_funcall_args_t;
-
-/* why isn't there something like this in the ruby API? */
-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;
-
-    return rb_funcall2(args->self, args->method, args->argc, args->params);
-}
+/* interned at init, because interning can allocate and rb_sqlite3_aggregator_pin
+ * runs during GC */
+static ID id_instances;
+static ID id_handler_instance;
 
-static VALUE
-rb_sqlite3_protected_funcall(VALUE self, ID method, int argc, VALUE *params,
-                             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);
-}
+/* sqlite's aggregate context for one invocation of an aggregate function. */
+typedef struct {
+    /* the AggregatorInstance: Qfalse until the first callback creates it, Qnil
+     * once xFinal destroys it */
+    VALUE inst;
+    /* != 0 once a callback for this invocation raised, threw or was skipped.
+     * After that, `step` and `finalize` won't be called any more. */
+    int exc_status;
+} aggregate_context_t;
+
+typedef struct {
+    sqlite3_context *ctx;
+    aggregate_context_t *agg;
+    int argc;
+    sqlite3_value **argv;
+} aggregator_call_t;
 
-/* called in rb_sqlite3_aggregator_step and rb_sqlite3_aggregator_final. It
- * checks if the execution context already has an associated instance. If it
- * has one, it returns it. If there is no instance yet, it creates one and
- * associates it with the context. */
+/* called in the step and final callbacks. Returns the invocation's handler
+ * instance, creating it on the first call. */
 static VALUE
-rb_sqlite3_aggregate_instance(sqlite3_context *ctx)
+rb_sqlite3_aggregate_handler_instance(aggregator_call_t *call)
 {
-    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, handler_instance, inst;
 
-    if (!inst_ptr) {
-        rb_fatal("SQLite is out-of-memory");
+    if (call->agg->inst == Qnil) {
+        rb_fatal("SQLite called us back on an already destroyed aggregate instance");
     }
 
-    inst = *inst_ptr;
-
-    if (inst == Qfalse) { /* Qfalse == 0 */
-        VALUE instances = rb_iv_get(aw, "-instances");
-        int exc_status;
+    if (call->agg->inst == Qfalse) { /* Qfalse == 0 */
+        aw = (VALUE) sqlite3_user_data(call->ctx);
+        handler_instance = rb_funcall(rb_ivar_get(aw, rb_intern("-handler_klass")), rb_intern("new"), 0);
 
         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);
-
-        *inst_ptr = inst;
-    }
+        rb_ivar_set(inst, id_handler_instance, handler_instance);
+        rb_ary_push(rb_ivar_get(aw, id_instances), inst);
 
-    if (inst == Qnil) {
-        rb_fatal("SQLite called us back on an already destroyed aggregate instance");
+        call->agg->inst = inst;
     }
 
-    return inst;
+    return rb_ivar_get(call->agg->inst, id_handler_instance);
 }
 
-/* called by rb_sqlite3_aggregator_final. Unlinks and frees the
- * aggregator_instance_t, so the handler_instance won't be marked any more
- * and Ruby's GC may free it. */
+/* called by rb_sqlite3_aggregator_final, after any skipped or failed callback
+ * too, so it runs no Ruby code. Unlinks the instance, so the handler_instance
+ * won't be marked any more and Ruby's GC may free it. */
 static void
-rb_sqlite3_aggregate_instance_destroy(sqlite3_context *ctx)
+rb_sqlite3_aggregate_instance_destroy(sqlite3_context *ctx, aggregate_context_t *agg)
 {
-    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 instances = rb_ivar_get((VALUE) sqlite3_user_data(ctx), id_instances);
+    long i;
 
-    if (!inst_ptr || !(inst = *inst_ptr)) {
+    if (!agg->inst) {
         return;
     }
 
-    if (inst == Qnil) {
+    if (agg->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_ivar_set(agg->inst, id_handler_instance, Qnil); // may catch use-after-free
+    for (i = 0; i < RARRAY_LEN(instances) && RARRAY_AREF(instances, i) != agg->inst; i++);
+    if (i == RARRAY_LEN(instances)) {
         rb_fatal("must be in instances at that point");
     }
+    rb_ary_delete_at(instances, i);
 
-    *inst_ptr = Qnil;
+    agg->inst = Qnil;
+}
+
+static VALUE
+rb_sqlite3_aggregator_step_protected(VALUE call_value)
+{
+    aggregator_call_t *call = (aggregator_call_t *)call_value;
+    VALUE handler_instance = rb_sqlite3_aggregate_handler_instance(call);
+    VALUE params = rb_ary_new2(call->argc);
+    int i;
+
+    for (i = 0; i < call->argc; i++) {
+        rb_ary_push(params, sqlite3val2rb(call->argv[i]));
+    }
+
+    return rb_apply(handler_instance, rb_intern("step"), params);
+}
+
+static VALUE
+rb_sqlite3_aggregator_final_protected(VALUE call_value)
+{
+    aggregator_call_t *call = (aggregator_call_t *)call_value;
+    VALUE handler_instance = rb_sqlite3_aggregate_handler_instance(call);
+
+    set_sqlite3_func_result(call->ctx, rb_funcall(handler_instance, rb_intern("finalize"), 0));
+
+    return Qnil;
 }
 
 static void
 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 params_handle = 0;
-    VALUE one_param;
-    int exc_status = NUM2INT(rb_iv_get(inst, "-exc_status"));
-    int i;
+    aggregator_call_t call = {
+        .ctx = ctx, .agg = sqlite3_aggregate_context(ctx, (int)sizeof(aggregate_context_t)), .argc = argc, .argv = argv
+    };
 
-    if (exc_status) {
+    if (!call.agg) {
+        sqlite3_result_error_nomem(ctx);
         return;
     }
 
-    if (argc == 1) {
-        one_param = sqlite3val2rb(argv[0]);
-        params = &one_param;
+    if (!call.agg->exc_status) {
+        rb_sqlite3_protect_callback(rb_sqlite3_aggregator_step_protected, (VALUE)&call, &call.agg->exc_status);
     }
-    if (argc > 1) {
-        /* ALLOCV memory is conservatively marked, so stored VALUEs survive a
-         * GC raised by a later sqlite3val2rb call. */
-        params = ALLOCV_N(VALUE, params_handle, argc);
-        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) {
-        ALLOCV_END(params_handle);
-    }
-
-    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)
 {
-    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);
-        }
+    aggregator_call_t call = { .ctx = ctx, .agg = sqlite3_aggregate_context(ctx, (int)sizeof(aggregate_context_t)) };
+
+    if (!call.agg) {
+        sqlite3_result_error_nomem(ctx);
+        return;
     }
 
-    if (exc_status) {
+    if (!call.agg->exc_status) {
+        rb_sqlite3_protect_callback(rb_sqlite3_aggregator_final_protected, (VALUE)&call, &call.agg->exc_status);
+    }
+
+    if (call.agg->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.agg);
 }
 
 /* call-seq: define_aggregator2(aggregator)
@@ -263,9 +247,16 @@ rb_sqlite3_define_aggregator2(VALUE self, VALUE aggregator, VALUE ruby_name)
 }
 
 void
-rb_sqlite3_aggregator_pin_instances(VALUE aw)
+rb_sqlite3_aggregator_pin(VALUE aggregators)
 {
-    rb_sqlite3_pin_array_and_contents(rb_iv_get(aw, "-instances"));
+    long i;
+
+    if (NIL_P(aggregators) || !aggregators) { return; }
+
+    rb_sqlite3_pin_array_and_contents(aggregators);
+    for (i = 0; i < RARRAY_LEN(aggregators); i++) {
+        rb_sqlite3_pin_array_and_contents(rb_ivar_get(RARRAY_AREF(aggregators, i), id_instances));
+    }
 }
 
 void
@@ -277,4 +268,7 @@ rb_sqlite3_aggregator_init(void)
 
     cAggregatorInstance = rb_funcall(rb_cClass, rb_intern("new"), 0);
     rb_gc_register_mark_object(cAggregatorInstance);
+
+    id_instances = rb_intern("-instances");
+    id_handler_instance = rb_intern("-handler_instance");
 }

data/ext/sqlite3/aggregator.h

@@ -7,8 +7,9 @@ VALUE rb_sqlite3_define_aggregator2(VALUE self, VALUE aggregator, VALUE ruby_nam
 
 void rb_sqlite3_aggregator_init(void);
 
-/* sqlite stores each live instance's VALUE in its aggregate context, so those
- * must not move either. */
-void rb_sqlite3_aggregator_pin_instances(VALUE aw);
+/* Pins every aggregator wrapper and its live instances. sqlite holds raw
+ * pointers to the wrappers, and stores each instance's VALUE in its aggregate
+ * context. */
+void rb_sqlite3_aggregator_pin(VALUE aggregators);
 
 #endif

data/ext/sqlite3/backup.c

@@ -113,11 +113,16 @@ static VALUE
 step(VALUE self, VALUE nPage)
 {
     sqlite3BackupRubyPtr ctx;
-    int status;
+    rb_sqlite3_callback_frame_t frame;
+    int pages, status, callback_state;
 
     TypedData_Get_Struct(self, sqlite3BackupRuby, &backup_type, ctx);
     REQUIRE_OPEN_BACKUP(ctx);
-    status = sqlite3_backup_step(ctx->p, NUM2INT(nPage));
+    pages = NUM2INT(nPage);
+
+    rb_sqlite3_push_callback_frame(&frame);
+    status = sqlite3_backup_step(ctx->p, pages);
+    if ((callback_state = rb_sqlite3_pop_callback_frame(&frame))) { rb_jump_tag(callback_state); }
     return INT2NUM(status);
 }
 

data/ext/sqlite3/database.c

@@ -74,51 +74,6 @@ close_or_discard_db(sqlite3RubyPtr ctx)
 }
 
 
-void
-rb_sqlite3_pin_array_and_contents(VALUE ary)
-{
-    long i;
-
-    if (NIL_P(ary) || !ary) { return; }
-
-    rb_gc_mark(ary);
-    for (i = 0; i < RARRAY_LEN(ary); i++) {
-        rb_gc_mark(RARRAY_AREF(ary, i));
-    }
-}
-
-static int
-pin_hash_value(VALUE UNUSED(key), VALUE value, VALUE UNUSED(arg))
-{
-    rb_gc_mark(value);
-    return ST_CONTINUE;
-}
-
-static void
-pin_hash_and_contents(VALUE hash)
-{
-    if (NIL_P(hash) || !hash) { return; }
-
-    rb_gc_mark(hash);
-    rb_hash_foreach(hash, pin_hash_value, 0);
-}
-
-/* Each wrapper also owns live aggregate instances, whose VALUEs sqlite keeps in
- * its own aggregate contexts. */
-static void
-pin_aggregators(VALUE aggregators)
-{
-    long i;
-
-    rb_sqlite3_pin_array_and_contents(aggregators);
-
-    if (NIL_P(aggregators) || !aggregators) { return; }
-
-    for (i = 0; i < RARRAY_LEN(aggregators); i++) {
-        rb_sqlite3_aggregator_pin_instances(RARRAY_AREF(aggregators, i));
-    }
-}
-
 static void
 database_mark(void *ctx)
 {
@@ -130,8 +85,8 @@ database_mark(void *ctx)
     rb_gc_mark(c->authorizer);
 
     rb_sqlite3_pin_array_and_contents(c->functions);
-    pin_hash_and_contents(c->collations);
-    pin_aggregators(c->aggregators);
+    rb_sqlite3_pin_array_and_contents(c->collations);
+    rb_sqlite3_aggregator_pin(c->aggregators);
 }
 
 static void
@@ -150,7 +105,7 @@ database_memsize(const void *ctx)
 }
 
 static const rb_data_type_t database_type = {
-    .wrap_struct_name = "SQLite3::Backup",
+    .wrap_struct_name = "SQLite3::Database",
     .function = {
         .dmark = database_mark,
         .dfree = deallocate,
@@ -321,11 +276,21 @@ total_changes(VALUE self)
     return INT2NUM(sqlite3_total_changes(ctx->db));
 }
 
+static VALUE
+tracefunc_protected(VALUE args_value)
+{
+    VALUE *args = (VALUE *)args_value;
+    return rb_funcall(args[0], rb_intern("call"), 1, rb_str_new2((const char *)args[1]));
+}
+
 static void
 tracefunc(void *data, const char *sql)
 {
     sqlite3RubyPtr ctx = (sqlite3RubyPtr)data;
-    rb_funcall(ctx->trace_handler, rb_intern("call"), 1, rb_str_new2(sql));
+    VALUE args[] = { ctx->trace_handler, (VALUE)sql };
+    int failed;
+
+    rb_sqlite3_protect_callback(tracefunc_protected, (VALUE)args, &failed);
 }
 
 /* call-seq:
@@ -356,15 +321,24 @@ trace(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+static VALUE
+rb_sqlite3_busy_handler_protected(VALUE args_value)
+{
+    VALUE *args = (VALUE *)args_value;
+    return rb_funcall(args[0], rb_intern("call"), 1, INT2NUM((int)args[1]));
+}
+
 static int
 rb_sqlite3_busy_handler(void *context, int count)
 {
     sqlite3RubyPtr ctx = (sqlite3RubyPtr)context;
+    VALUE args[] = { ctx->busy_handler, (VALUE)count };
+    VALUE result;
+    int failed;
 
-    VALUE handle = ctx->busy_handler;
-    VALUE result = rb_funcall(handle, rb_intern("call"), 1, INT2NUM(count));
+    result = rb_sqlite3_protect_callback(rb_sqlite3_busy_handler_protected, (VALUE)args, &failed);
 
-    if (Qfalse == result) { return 0; }
+    if (failed || Qfalse == result) { return 0; }
 
     return 1;
 }
@@ -529,14 +503,14 @@ set_sqlite3_func_result(sqlite3_context *ctx, VALUE result)
                 sqlite3_result_blob(
                     ctx,
                     (const void *)StringValuePtr(result),
-                    (int)RSTRING_LEN(result),
+                    RSTRING_LENINT(result),
                     SQLITE_TRANSIENT
                 );
             } else {
                 sqlite3_result_text(
                     ctx,
                     (const char *)StringValuePtr(result),
-                    (int)RSTRING_LEN(result),
+                    RSTRING_LENINT(result),
                     SQLITE_TRANSIENT
                 );
             }
@@ -578,13 +552,13 @@ static void
 rb_sqlite3_func(sqlite3_context *ctx, int argc, sqlite3_value **argv)
 {
     rb_sqlite3_func_args_t args = { .ctx = ctx, .argc = argc, .argv = argv };
-    int exc_status;
+    int failed;
 
-    rb_protect(rb_sqlite3_func_protected, (VALUE)&args, &exc_status);
+    rb_sqlite3_protect_callback(rb_sqlite3_func_protected, (VALUE)&args, &failed);
 
-    if (exc_status) {
+    if (failed) {
         /* the user should never see this message, because Statement#step will
-         * re-raise the exception still in rb_errinfo */
+         * resume the Ruby exception instead */
         sqlite3_result_error(ctx, "Ruby Exception occurred", -1);
     }
 }
@@ -722,6 +696,33 @@ changes(VALUE self)
     return INT2NUM(sqlite3_changes(ctx->db));
 }
 
+typedef struct {
+    VALUE authorizer;
+    int action;
+    const char *a;
+    const char *b;
+    const char *c;
+    const char *d;
+} rb_sqlite3_auth_args_t;
+
+static VALUE
+rb_sqlite3_auth_protected(VALUE auth_args_value)
+{
+    rb_sqlite3_auth_args_t *args = (rb_sqlite3_auth_args_t *)auth_args_value;
+    VALUE action = INT2NUM(args->action);
+    VALUE a      = args->a ? rb_str_new2(args->a) : Qnil;
+    VALUE b      = args->b ? rb_str_new2(args->b) : Qnil;
+    VALUE c      = args->c ? rb_str_new2(args->c) : Qnil;
+    VALUE d      = args->d ? rb_str_new2(args->d) : Qnil;
+    VALUE result = rb_funcall(args->authorizer, rb_intern("call"), 5, action, a, b, c, d);
+
+    if (T_FIXNUM == TYPE(result)) { return INT2FIX(NUM2INT(result)); }
+    if (Qtrue == result) { return INT2FIX(SQLITE_OK); }
+    if (Qfalse == result) { return INT2FIX(SQLITE_DENY); }
+
+    return INT2FIX(SQLITE_IGNORE);
+}
+
 static int
 rb_sqlite3_auth(
     void *ctx,
@@ -732,18 +733,17 @@ rb_sqlite3_auth(
     const char *_d)
 {
     sqlite3RubyPtr db_ctx = (sqlite3RubyPtr)ctx;
-    VALUE action = INT2NUM(_action);
-    VALUE a      = _a ? rb_str_new2(_a) : Qnil;
-    VALUE b      = _b ? rb_str_new2(_b) : Qnil;
-    VALUE c      = _c ? rb_str_new2(_c) : Qnil;
-    VALUE d      = _d ? rb_str_new2(_d) : Qnil;
-    VALUE result = rb_funcall(db_ctx->authorizer, rb_intern("call"), 5, action, a, b, c, d);
-
-    if (T_FIXNUM == TYPE(result)) { return (int)NUM2INT(result); }
-    if (Qtrue == result) { return SQLITE_OK; }
-    if (Qfalse == result) { return SQLITE_DENY; }
-
-    return SQLITE_IGNORE;
+    rb_sqlite3_auth_args_t args = {
+        .authorizer = db_ctx->authorizer, .action = _action, .a = _a, .b = _b, .c = _c, .d = _d
+    };
+    VALUE result;
+    int failed;
+
+    result = rb_sqlite3_protect_callback(rb_sqlite3_auth_protected, (VALUE)&args, &failed);
+
+    if (failed) { return SQLITE_DENY; }
+
+    return FIX2INT(result);
 }
 
 /* call-seq: set_authorizer = auth
@@ -815,10 +815,19 @@ set_extended_result_codes(VALUE self, VALUE enable)
     return self;
 }
 
-int
-rb_comparator_func(void *ctx, int a_len, const void *a, int b_len, const void *b)
-{
+typedef struct {
     VALUE comparator;
+    int a_len;
+    const void *a;
+    int b_len;
+    const void *b;
+    int comparison;
+} rb_comparator_args_t;
+
+static VALUE
+rb_comparator_protected(VALUE comparator_args_value)
+{
+    rb_comparator_args_t *args = (rb_comparator_args_t *)comparator_args_value;
     VALUE a_str;
     VALUE b_str;
     VALUE comparison;
@@ -826,9 +835,8 @@ rb_comparator_func(void *ctx, int a_len, const void *a, int b_len, const void *b
 
     internal_encoding = rb_default_internal_encoding();
 
-    comparator = (VALUE)ctx;
-    a_str = rb_str_new((const char *)a, a_len);
-    b_str = rb_str_new((const char *)b, b_len);
+    a_str = rb_str_new((const char *)args->a, args->a_len);
+    b_str = rb_str_new((const char *)args->b, args->b_len);
 
     rb_enc_associate_index(a_str, rb_utf8_encindex());
     rb_enc_associate_index(b_str, rb_utf8_encindex());
@@ -838,9 +846,30 @@ rb_comparator_func(void *ctx, int a_len, const void *a, int b_len, const void *b
         b_str = rb_str_export_to_enc(b_str, internal_encoding);
     }
 
-    comparison = rb_funcall(comparator, rb_intern("compare"), 2, a_str, b_str);
+    comparison = rb_funcall(args->comparator, rb_intern("compare"), 2, a_str, b_str);
+
+    args->comparison = NUM2INT(comparison);
 
-    return NUM2INT(comparison);
+    return Qnil;
+}
+
+int
+rb_comparator_func(void *ctx, int a_len, const void *a, int b_len, const void *b)
+{
+    rb_comparator_args_t args = { .comparator = (VALUE)ctx, .a_len = a_len, .a = a, .b_len = b_len, .b = b };
+    int failed;
+
+    rb_sqlite3_protect_callback(rb_comparator_protected, (VALUE)&args, &failed);
+
+    /* sqlite has no way to report a comparator error */
+    return failed ? 0 : args.comparison;
+}
+
+static int
+push_hash_value(VALUE UNUSED(key), VALUE value, VALUE ary)
+{
+    rb_ary_push(ary, value);
+    return ST_CONTINUE;
 }
 
 /* call-seq: db.collation(name, comparator)
@@ -854,21 +883,42 @@ static VALUE
 collation(VALUE self, VALUE name, VALUE comparator)
 {
     sqlite3RubyPtr ctx;
-    VALUE collations;
+    VALUE registry, key, comparators;
+    char *key_ptr;
+    long i;
     TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
     REQUIRE_OPEN_DB(ctx);
 
+    /* sqlite holds a raw pointer to the comparator, so keep it alive and
+     * unmoved. The registry is private because callers can mutate the public
+     * @collations hash, and the snapshot is an array so database_mark can pin
+     * it without iterating a hash. sqlite matches collation names without
+     * regard to ASCII case, so the registry does too. The key and registry
+     * are prepared before sqlite takes the pointer, and the snapshot is
+     * published before the public hash, whose write can raise. */
+    key = rb_str_new_cstr(StringValuePtr(name));
+    key_ptr = RSTRING_PTR(key);
+    for (i = 0; i < RSTRING_LEN(key); i++) {
+        if (key_ptr[i] >= 'A' && key_ptr[i] <= 'Z') { key_ptr[i] += 'a' - 'A'; }
+    }
+    if (!rb_ivar_defined(self, rb_intern("-collations"))) {
+        rb_iv_set(self, "-collations", rb_hash_new());
+    }
+    registry = rb_iv_get(self, "-collations");
+
     CHECK(ctx->db, sqlite3_create_collation(
               ctx->db,
-              StringValuePtr(name),
+              RSTRING_PTR(name),
               SQLITE_UTF8,
               (void *)comparator,
               NIL_P(comparator) ? NULL : rb_comparator_func));
 
-    /* sqlite holds a raw pointer to the comparator, so keep it alive and unmoved. */
-    collations = rb_iv_get(self, "@collations");
-    rb_hash_aset(collations, name, comparator);
-    RB_OBJ_WRITE(self, &ctx->collations, collations);
+    rb_hash_aset(registry, key, comparator);
+    comparators = rb_ary_new();
+    rb_hash_foreach(registry, push_hash_value, comparators);
+    RB_OBJ_WRITE(self, &ctx->collations, comparators);
+
+    rb_hash_aset(rb_iv_get(self, "@collations"), name, comparator);
 
     return self;
 }
@@ -934,42 +984,68 @@ transaction_active_p(VALUE self)
     return sqlite3_get_autocommit(ctx->db) ? Qfalse : Qtrue;
 }
 
-static int
-hash_callback_function(VALUE callback_ary, int count, char **data, char **columns)
+typedef struct {
+    VALUE callback_ary;
+    VALUE (*build_row)(VALUE);
+} rb_sqlite3_exec_batch_t;
+
+typedef struct {
+    VALUE callback_ary;
+    int count;
+    char **data;
+    char **columns;
+} rb_sqlite3_exec_row_t;
+
+static VALUE
+hash_callback_protected(VALUE row_value)
 {
+    rb_sqlite3_exec_row_t *row = (rb_sqlite3_exec_row_t *)row_value;
     VALUE new_hash = rb_hash_new();
     int i;
 
-    for (i = 0; i < count; i++) {
-        if (data[i] == NULL) {
-            rb_hash_aset(new_hash, rb_str_new_cstr(columns[i]), Qnil);
+    for (i = 0; i < row->count; i++) {
+        if (row->data[i] == NULL) {
+            rb_hash_aset(new_hash, rb_str_new_cstr(row->columns[i]), Qnil);
         } else {
-            rb_hash_aset(new_hash, rb_str_new_cstr(columns[i]), rb_str_new_cstr(data[i]));
+            rb_hash_aset(new_hash, rb_str_new_cstr(row->columns[i]), rb_str_new_cstr(row->data[i]));
         }
     }
 
-    rb_ary_push(callback_ary, new_hash);
+    rb_ary_push(row->callback_ary, new_hash);
 
-    return 0;
+    return Qnil;
 }
 
-static int
-regular_callback_function(VALUE callback_ary, int count, char **data, char **columns)
+static VALUE
+regular_callback_protected(VALUE row_value)
 {
+    rb_sqlite3_exec_row_t *row = (rb_sqlite3_exec_row_t *)row_value;
     VALUE new_ary = rb_ary_new();
     int i;
 
-    for (i = 0; i < count; i++) {
-        if (data[i] == NULL) {
+    for (i = 0; i < row->count; i++) {
+        if (row->data[i] == NULL) {
             rb_ary_push(new_ary, Qnil);
         } else {
-            rb_ary_push(new_ary, rb_str_new_cstr(data[i]));
+            rb_ary_push(new_ary, rb_str_new_cstr(row->data[i]));
         }
     }
 
-    rb_ary_push(callback_ary, new_ary);
+    rb_ary_push(row->callback_ary, new_ary);
 
-    return 0;
+    return Qnil;
+}
+
+static int
+exec_batch_callback_function(void *batch_ptr, int count, char **data, char **columns)
+{
+    rb_sqlite3_exec_batch_t *batch = (rb_sqlite3_exec_batch_t *)batch_ptr;
+    rb_sqlite3_exec_row_t row = { .callback_ary = batch->callback_ary, .count = count, .data = data, .columns = columns };
+    int failed;
+
+    rb_sqlite3_protect_callback(batch->build_row, (VALUE)&row, &failed);
+
+    return failed;
 }
 
 
@@ -987,21 +1063,27 @@ exec_batch(VALUE self, VALUE sql, VALUE results_as_hash)
     sqlite3RubyPtr ctx;
     int status;
     VALUE callback_ary = rb_ary_new();
+    rb_sqlite3_exec_batch_t batch = {
+        .callback_ary = callback_ary,
+        .build_row = results_as_hash == Qtrue ? hash_callback_protected : regular_callback_protected
+    };
+    rb_sqlite3_callback_frame_t frame;
+    int callback_state;
+    const char *sql_cstr;
     char *errMsg;
 
     TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
     REQUIRE_OPEN_DB(ctx);
 
+    sql_cstr = StringValuePtr(sql);
     timespecclear(&ctx->stmt_deadline);
 
-    if (results_as_hash == Qtrue) {
-        status = sqlite3_exec(ctx->db, StringValuePtr(sql), (sqlite3_callback)hash_callback_function,
-                              (void *)callback_ary,
-                              &errMsg);
-    } else {
-        status = sqlite3_exec(ctx->db, StringValuePtr(sql), (sqlite3_callback)regular_callback_function,
-                              (void *)callback_ary,
-                              &errMsg);
+    rb_sqlite3_push_callback_frame(&frame);
+    status = sqlite3_exec(ctx->db, sql_cstr, exec_batch_callback_function, (void *)&batch, &errMsg);
+
+    if ((callback_state = rb_sqlite3_pop_callback_frame(&frame))) {
+        sqlite3_free(errMsg);
+        rb_jump_tag(callback_state);
     }
 
     CHECK_MSG(ctx->db, status, errMsg);

data/ext/sqlite3/database.h

@@ -10,6 +10,12 @@
 struct _sqlite3Ruby {
     sqlite3 *db;
     VALUE busy_handler;
+    /* sqlite holds raw pointers to everything in these arrays. functions and
+     * aggregators are append-only, so redefining a name keeps the old object
+     * for the life of the connection: sqlite keys them by name and arity, and
+     * releasing on name alone was GHSA-28hh-pr2h-2w89. collations is rebuilt
+     * from a private hash keyed by name without regard to ASCII case, as
+     * sqlite keys them, so it releases a replaced comparator. */
     VALUE functions;
     VALUE collations;
     VALUE aggregators;
@@ -24,9 +30,6 @@ struct _sqlite3Ruby {
 typedef struct _sqlite3Ruby sqlite3Ruby;
 typedef sqlite3Ruby *sqlite3RubyPtr;
 
-/* Pinning a collection doesn't pin what's in it, hence both. */
-void rb_sqlite3_pin_array_and_contents(VALUE ary);
-
 void init_sqlite3_database();
 void set_sqlite3_func_result(sqlite3_context *ctx, VALUE result);
 

data/ext/sqlite3/exception.c

@@ -120,3 +120,98 @@ rb_sqlite3_raise_with_sql(sqlite3 *db, int status, const char *sql)
 
     rb_exc_raise(exception);
 }
+
+/* Each call into sqlite that can run callbacks pushes a frame on the current
+ * fiber's chain. A callback that fails records its rb_protect state in the top
+ * frame, and the call resumes Ruby's pending jump once sqlite returns. Ruby
+ * code that runs in between, such as a finalizer during an allocation, pushes
+ * its own frame for any nested call, so it never takes the outer call's jump.
+ * The chain is fiber-local because Ruby code inside a callback can switch
+ * threads or fibers, and a Ruby thread can move between native threads inside
+ * rb_protect. */
+typedef struct {
+    rb_sqlite3_callback_frame_t *top;
+} callback_frames_t;
+
+static const rb_data_type_t callback_frames_type = {
+    .wrap_struct_name = "SQLite3::CallbackFrames",
+    .function = {
+        .dfree = RUBY_TYPED_DEFAULT_FREE,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED,
+};
+
+static ID id_callback_frames;
+
+/* Ruby code can overwrite or delete the fiber-local, so check its type. */
+static VALUE
+current_callback_frames_holder(void)
+{
+    VALUE holder = rb_thread_local_aref(rb_thread_current(), id_callback_frames);
+    return rb_typeddata_is_kind_of(holder, &callback_frames_type) ? holder : Qnil;
+}
+
+static callback_frames_t *
+current_callback_frames(void)
+{
+    VALUE holder = current_callback_frames_holder();
+    return NIL_P(holder) ? NULL : (callback_frames_t *)RTYPEDDATA_DATA(holder);
+}
+
+void
+rb_sqlite3_push_callback_frame(rb_sqlite3_callback_frame_t *frame)
+{
+    VALUE holder = current_callback_frames_holder();
+    callback_frames_t *frames;
+
+    if (NIL_P(holder)) {
+        holder = TypedData_Make_Struct(rb_cObject, callback_frames_t, &callback_frames_type, frames);
+        rb_thread_local_aset(rb_thread_current(), id_callback_frames, holder);
+    }
+    frames = (callback_frames_t *)RTYPEDDATA_DATA(holder);
+
+    frame->state = 0;
+    frame->prev = frames->top;
+    frame->holder = holder;
+    frames->top = frame;
+}
+
+int
+rb_sqlite3_pop_callback_frame(rb_sqlite3_callback_frame_t *frame)
+{
+    ((callback_frames_t *)RTYPEDDATA_DATA(frame->holder))->top = frame->prev;
+    return frame->state;
+}
+
+VALUE
+rb_sqlite3_protect_callback(VALUE (*body)(VALUE), VALUE data, int *failed)
+{
+    callback_frames_t *frames = current_callback_frames();
+    rb_sqlite3_callback_frame_t *frame = frames ? frames->top : NULL;
+    VALUE result;
+    int state;
+
+    if (frame && frame->state) {
+        *failed = 1;
+        return Qnil;
+    }
+
+    result = rb_protect(body, data, &state);
+    *failed = state != 0;
+
+    if (frame) {
+        frame->state = state;
+    } else if (state) {
+        /* sqlite ran the callback from a call that cannot resume the jump, such
+         * as Statement#reset!, so the error is dropped */
+        rb_set_errinfo(Qnil);
+    }
+
+    return result;
+}
+
+void
+init_sqlite3_exception(void)
+{
+    id_callback_frames = rb_intern("__sqlite3_callback_frames__");
+}

data/ext/sqlite3/exception.h

@@ -9,4 +9,25 @@ void rb_sqlite3_raise(sqlite3 *db, int status);
 void rb_sqlite3_raise_msg(sqlite3 *db, int status, const char *msg);
 void rb_sqlite3_raise_with_sql(sqlite3 *db, int status, const char *sql);
 
+typedef struct rb_sqlite3_callback_frame {
+    int state;
+    struct rb_sqlite3_callback_frame *prev;
+    /* the frame lives on the C stack, so GC marks and pins this */
+    VALUE holder;
+} rb_sqlite3_callback_frame_t;
+
+/* A call into sqlite that can run callbacks is wrapped in a frame. sqlite
+ * cannot carry a raise or a throw, so a failed callback records its rb_protect
+ * state in the frame, and later callbacks skip their Ruby code. Pop the frame
+ * when sqlite returns, then resume the jump with rb_jump_tag if the returned
+ * state is nonzero. Run nothing but the sqlite call in between, because a
+ * raise there would skip the pop. */
+void rb_sqlite3_push_callback_frame(rb_sqlite3_callback_frame_t *frame);
+int rb_sqlite3_pop_callback_frame(rb_sqlite3_callback_frame_t *frame);
+
+/* Runs a callback's Ruby code for sqlite. Sets *failed if it did not complete. */
+VALUE rb_sqlite3_protect_callback(VALUE (*body)(VALUE), VALUE data, int *failed);
+
+void init_sqlite3_exception(void);
+
 #endif

data/ext/sqlite3/sqlite3.c

@@ -60,6 +60,19 @@ bignum_to_int64(VALUE value, sqlite3_int64 *result)
 #endif
 }
 
+void
+rb_sqlite3_pin_array_and_contents(VALUE ary)
+{
+    long i;
+
+    if (NIL_P(ary) || !ary) { return; }
+
+    rb_gc_mark(ary);
+    for (i = 0; i < RARRAY_LEN(ary); i++) {
+        rb_gc_mark(RARRAY_AREF(ary, i));
+    }
+}
+
 static VALUE
 libversion(VALUE UNUSED(klass))
 {
@@ -191,6 +204,7 @@ Init_sqlite3_native(void)
     sqlite3_initialize();
 #endif
 
+    init_sqlite3_exception();
     init_sqlite3_constants();
     init_sqlite3_database();
     init_sqlite3_statement();

data/ext/sqlite3/sqlite3_ruby.h

@@ -45,4 +45,7 @@ extern VALUE cSqlite3Blob;
 
 int bignum_to_int64(VALUE big, sqlite3_int64 *result);
 
+/* Pinning a collection doesn't pin what's in it, hence both. */
+void rb_sqlite3_pin_array_and_contents(VALUE ary);
+
 #endif

data/ext/sqlite3/statement.c

@@ -31,7 +31,7 @@ statement_memsize(const void *data)
 }
 
 static const rb_data_type_t statement_type = {
-    "SQLite3::Backup",
+    "SQLite3::Statement",
     {
         NULL,
         statement_deallocate,
@@ -54,8 +54,9 @@ prepare(VALUE self, VALUE db, VALUE sql)
 {
     sqlite3RubyPtr db_ctx = sqlite3_database_unwrap(db);
     sqlite3StmtRubyPtr ctx;
-    const char *tail = NULL;
-    int status;
+    const char *sql_cstr, *tail = NULL;
+    rb_sqlite3_callback_frame_t frame;
+    int sql_len, status, callback_state;
 
     StringValue(sql);
 
@@ -68,17 +69,22 @@ prepare(VALUE self, VALUE db, VALUE sql)
 
     timespecclear(&db_ctx->stmt_deadline);
 
+    sql_cstr = StringValuePtr(sql);
+    sql_len = RSTRING_LENINT(sql);
+
+    rb_sqlite3_push_callback_frame(&frame);
 #ifdef HAVE_SQLITE3_PREPARE_V2
     status = sqlite3_prepare_v2(
 #else
     status = sqlite3_prepare(
 #endif
                  db_ctx->db,
-                 (const char *)StringValuePtr(sql),
-                 (int)RSTRING_LEN(sql),
+                 sql_cstr,
+                 sql_len,
                  &ctx->st,
                  &tail
              );
+    if ((callback_state = rb_sqlite3_pop_callback_frame(&frame))) { rb_jump_tag(callback_state); }
 
     CHECK_PREPARE(db_ctx->db, status, StringValuePtr(sql));
 
@@ -125,7 +131,8 @@ step(VALUE self)
 {
     sqlite3StmtRubyPtr ctx;
     sqlite3_stmt *stmt;
-    int value, length;
+    rb_sqlite3_callback_frame_t frame;
+    int value, length, callback_state;
     VALUE list;
     rb_encoding *internal_encoding;
 
@@ -144,14 +151,13 @@ step(VALUE self)
         timespecclear(&ctx->db->stmt_deadline);
     }
 
+    rb_sqlite3_push_callback_frame(&frame);
     value = sqlite3_step(stmt);
-    if (rb_errinfo() != Qnil) {
-        /* some user defined function was invoked as a callback during step and
-         * it raised an exception that has been suppressed until step returns.
-         * Now re-raise it. */
-        VALUE exception = rb_errinfo();
-        rb_set_errinfo(Qnil);
-        rb_exc_raise(exception);
+    if ((callback_state = rb_sqlite3_pop_callback_frame(&frame))) { rb_jump_tag(callback_state); }
+
+    if (value == SQLITE_DONE) {
+        ctx->done_p = 1;
+        return Qnil;
     }
 
     length = sqlite3_column_count(stmt);
@@ -200,10 +206,6 @@ step(VALUE self)
             }
         }
         break;
-        case SQLITE_DONE:
-            ctx->done_p = 1;
-            return Qnil;
-            break;
         default:
             sqlite3_reset(stmt);
             ctx->done_p = 0;
@@ -236,6 +238,10 @@ step(VALUE self)
  *
  *   stmt.bind_param(1, my_binary_str.encode(Encoding::UTF_8))
  *
+ * The value that this method binds stays bound when you execute or reset the
+ * statement. To change the value, bind a new value to the same parameter. To
+ * clear all values, call #clear_bindings!.
+ *
  * See also #bind_params.
  */
 static VALUE
@@ -274,7 +280,7 @@ bind_param(VALUE self, VALUE key, VALUE value)
                              ctx->st,
                              index,
                              (const char *)StringValuePtr(value),
-                             (int)RSTRING_LEN(value),
+                             RSTRING_LENINT(value),
                              SQLITE_TRANSIENT
                          );
             } else {
@@ -285,7 +291,7 @@ bind_param(VALUE self, VALUE key, VALUE value)
                                  ctx->st,
                                  index,
                                  (const char *)StringValuePtr(value),
-                                 (int)RSTRING_LEN(value),
+                                 RSTRING_LENINT(value),
                                  SQLITE_TRANSIENT
                              );
                 } else {
@@ -296,7 +302,7 @@ bind_param(VALUE self, VALUE key, VALUE value)
                                  ctx->st,
                                  index,
                                  (const char *)StringValuePtr(value),
-                                 (int)RSTRING_LEN(value),
+                                 RSTRING_LENINT(value),
                                  SQLITE_TRANSIENT
                              );
                 }
@@ -331,8 +337,11 @@ bind_param(VALUE self, VALUE key, VALUE value)
 
 /* call-seq: stmt.reset!
  *
- * Resets the statement. This is typically done internally, though it might
- * occasionally be necessary to manually reset the statement.
+ * Resets the statement. The library usually calls this method for you, but
+ * you can also call it yourself.
+ *
+ * This method does not clear the values that you bound to the parameters. To
+ * clear them, call #clear_bindings!.
  */
 static VALUE
 reset_bang(VALUE self)
@@ -353,8 +362,11 @@ reset_bang(VALUE self)
 
 /* call-seq: stmt.clear_bindings!
  *
- * Resets the statement. This is typically done internally, though it might
- * occasionally be necessary to manually reset the statement.
+ * Sets the value of each parameter in the statement to NULL.
+ *
+ * The values that you bind with #bind_param, #bind_params, or #execute stay
+ * bound when you execute or reset the statement. Call this method to clear
+ * them.
  */
 static VALUE
 clear_bindings_bang(VALUE self)

data/lib/sqlite3/resultset.rb

@@ -16,8 +16,12 @@ module SQLite3
       @stmt = stmt
     end
 
-    # Reset the cursor, so that a result set which has reached end-of-file
-    # can be rewound and reiterated.
+    # Resets the cursor to the first row, so that you can iterate over the
+    # result set again after it reaches the end.
+    #
+    # This method binds each argument to the statement with
+    # Statement#bind_params. The values that you bound before stay bound
+    # unless you bind new values to the same parameters.
     def reset(*bind_params)
       @stmt.reset!
       @stmt.bind_params(*bind_params)

data/lib/sqlite3/statement.rb

@@ -65,6 +65,10 @@ module SQLite3
     #   stmt = db.prepare( "select * from table where a=? and b=?" )
     #   stmt.bind_params( 15, "hello" )
     #
+    # The values that this method binds stay bound when you execute or reset
+    # the statement. To change a value, bind a new value to the same
+    # parameter. To clear all values, call #clear_bindings!.
+    #
     # See also #execute, #bind_param, Statement#bind_param, and
     # Statement#bind_params.
     def bind_params(*bind_vars)
@@ -83,7 +87,17 @@ module SQLite3
     # statement's virtual machine. If a block was given, the new ResultSet will
     # be yielded to it; otherwise, the ResultSet will be returned.
     #
-    # Any parameters will be bound to the statement using #bind_params.
+    # This method binds each argument to the statement with #bind_params. The
+    # values stay bound after this method returns. If a later call to #execute
+    # does not give a value for a parameter, the statement uses the value from
+    # the earlier call. To set all parameters to NULL before you execute the
+    # statement again, call #clear_bindings!:
+    #
+    #   stmt = db.prepare( "select :a, :b" )
+    #   stmt.execute( a: 1, b: 2 ).to_a  # => [[1, 2]]
+    #   stmt.execute( a: 3 ).to_a        # => [[3, 2]]
+    #   stmt.clear_bindings!
+    #   stmt.execute( a: 3 ).to_a        # => [[3, nil]]
     #
     # Example:
     #
@@ -92,7 +106,7 @@ module SQLite3
     #     ...
     #   end
     #
-    # See also #bind_params, #execute!.
+    # See also #bind_params, #execute!, #clear_bindings!.
     def execute(*bind_vars)
       reset! if active? || done?
 
@@ -109,7 +123,9 @@ module SQLite3
     # rows returned by executing the statement. Otherwise, each row will be
     # yielded to the block.
     #
-    # Any parameters will be bound to the statement using #bind_params.
+    # This method binds each argument to the statement with #bind_params. The
+    # values stay bound after this method returns. For more information, see
+    # #execute.
     #
     # Example:
     #

data/lib/sqlite3/version.rb

@@ -1,4 +1,4 @@
 module SQLite3
   # (String) the version of the sqlite3 gem, e.g. "2.1.1"
-  VERSION = "2.10.1"
+  VERSION = "2.10.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sqlite3
 version: !ruby/object:Gem::Version
-  version: 2.10.1
+  version: 2.10.2
 platform: aarch64-linux-gnu
 authors:
 - Jamis Buck