sqlite3 2.0.4 → 2.1.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6f21b08329df02d797b229d8f1cddd1dcc6b3d9239a07446798c02d0ecfe420
-  data.tar.gz: 7d0b94143e5f0239e9870bc041cedcfe06dc3f02ccdd38890207a432ab4f8f08
+  metadata.gz: f625987268dc96e27d1a765bc4a1be109444b46ed293ae332e104c8a988a5682
+  data.tar.gz: 4e85e9d72c9a58569d4f9c54b2a2186c958ced8a354d09274c22d760ad2d895c
 SHA512:
-  metadata.gz: 5ff806e2353d99c1e5eb642872d215f911cb952d7f6d34b326af2fb64bcd0ecafd84474499e352dd1e49cc35e8ffefa5658bf7c6e9bc0b4dfc46a2250c3cd300
-  data.tar.gz: c1ed5e1a6716f82af63291450955c8afac317297beae7e9ba3acf2d75ff9de48ac022373de14a54a8d7c9294585015edf90e70261c719a73d3749f3e1a0f14d4
+  metadata.gz: 6fe89b6a8af14427cf475bbcd68d6a55086d9857c44e7e84d380f0a28cf1e0f0dcfb2512391c48f8eef3ea1a22ab6b9ff9e9557f352ef5648a29d8f2b4adc84e
+  data.tar.gz: f0857a167acb9a134d5d6119b8621d47fdcb91a0eef076624cc4b563088283d0ad0f66cf7bf336e9b117e33422cc87d3b7ee50499e7d580912e0921517d88d27

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # sqlite3-ruby Changelog
 
+## prerelease 2.1.0.rc3 / 2024-09-18
+
+### Improved
+
+- Allow suppression of fork safety warnings. [#566] @flavorjones
+
+
+## prerelease 2.1.0.rc2 / 2024-09-18
+
+### Improved
+
+- Address a performance regression in 2.1.0.rc1.
+
+
+## prerelease 2.1.0.rc1 / 2024-09-18
+
+### Ruby
+
+- This release drops support for Ruby 3.0. [#563] @flavorjones
+
+
+### Fork safety improvements
+
+Sqlite itself is [not fork-safe](https://www.sqlite.org/howtocorrupt.html#_carrying_an_open_database_connection_across_a_fork_). Specifically, writing in a child process to a database connection that was created in the parent process may corrupt the database file. To mitigate this risk, sqlite3-ruby has implemented the following changes:
+
+- All open writable database connections carried across a `fork()` will immediately be closed in the child process to mitigate the risk of corrupting the database file.
+- These connections will be incompletely closed ("discarded") which will result in a one-time memory leak in the child process.
+
+If it's at all possible, we strongly recommend that you close writable database connections in the parent before forking.
+
+See the README "Fork Safety" section and `adr/2024-09-fork-safety.md` for more information. [#558] @flavorjones
+
+
+### Improved
+
+- Use `sqlite3_close_v2` to close databases in a deferred manner if there are unclosed prepared statements. Previously closing a database while statements were open resulted in a `BusyException`. See https://www.sqlite.org/c3ref/close.html for more context. [#557] @flavorjones
+- When setting a Database `busy_handler`, fire the write barrier to prevent potential crashes during the GC mark phase. [#556] @jhawthorn
+
+
 ## 2.0.4 / 2024-08-13
 
 ### Dependencies

data/CONTRIBUTING.md

@@ -7,24 +7,24 @@ This doc is a short introduction on how to modify and maintain the sqlite3-ruby
 
 ## Architecture notes
 
+### Decision record
+
+As of 2024-09, we're starting to keep some architecture decisions in the subdirectory `/adr`, so
+please look there for additional information.
+
 ### Garbage collection
 
 All statements keep pointers back to their respective database connections.
 The `@connection` instance variable on the `Statement` handle keeps the database
-connection alive.  Memory allocated for a statement handler will be freed in
-two cases:
-
-1. `#close` is called on the statement
-2. The `SQLite3::Database` object gets garbage collected
+connection alive.
 
-We can't free the memory for the statement in the garbage collection function
-for the statement handler.  The reason is because there exists a race
-condition.  We cannot guarantee the order in which objects will be garbage
-collected.  So, it is possible that a connection and a statement are up for
-garbage collection.  If the database connection were to be free'd before the
-statement, then boom.  Instead we'll be conservative and free unclosed
-statements when the connection is terminated.
+We use `sqlite3_close_v2` in `Database#close` since v2.1.0 which defers _actually_ closing the
+connection and freeing the underlying memory until all open statments are closed; though the
+`Database` object will immediately behave as though it's been fully closed. If a Database is not
+explicitly closed, it will be closed when it is GCed.
 
+`Statement#close` finalizes the underlying statement. If a Statement is not explicitly closed, it
+will be closed/finalized when it is GCed.
 
 
 ## Building gems

data/FAQ.md

@@ -207,48 +207,46 @@ Or do a `Database#prepare` to get the `Statement`, and then use either
   stmt.bind_params( "value", "name" => "bob" )
 ```
 
-## How do I discover metadata about a query?
+## How do I discover metadata about a query result?
   
-If you ever want to know the names or types of the columns in a result
-set, you can do it in several ways.
+IMPORTANT: `Database#execute` returns an Array of Array of Strings
+which will have no metadata about the query or the result, such
+as column names.
 
 
-The first way is to ask the row object itself. Each row will have a
-property "fields" that returns an array of the column names. The row
-will also have a property "types" that returns an array of the column
-types:
+There are 2 main sources of query metadata:
 
-
-```ruby
-  rows = db.execute( "select * from table" )
-  p rows[0].fields
-  p rows[0].types
-```
+* `Statement`
+* `ResultSet`
 
 
-Obviously, this approach requires you to execute a statement that actually
-returns data. If you don't know if the statement will return any rows, but
-you still need the metadata, you can use `Database#query` and ask the
-`ResultSet` object itself:
+You can get a `Statement` via `Database#prepare`, and you can get
+a `ResultSet` via `Statement#execute` or `Database#query`.
 
 
 ```ruby
-  db.query( "select * from table" ) do |result|
-    p result.columns
-    p result.types
-    ...
-  end
-```
-
-
-Lastly, you can use `Database#prepare` and ask the `Statement` object what
-the metadata are:
-
-
-```ruby
-  stmt = db.prepare( "select * from table" )
-  p stmt.columns
-  p stmt.types
+sql = 'select * from table'
+
+# No metadata
+rows = db.execute(sql)
+rows.class # => Array, no metadata
+rows.first.class # => Array, no metadata
+rows.first.first.class #=> String, no metadata
+
+# Statement has metadata
+stmt = db.prepare(sql)
+stmt.columns # => [ ... ]
+stmt.types # => [ ... ]
+
+# ResultSet has metadata
+results = stmt.execute
+results.columns # => [ ... ]
+results.types # => [ ... ]
+
+# ResultSet has metadata
+results = db.query(sql)
+results.columns # => [ ... ]
+results.types # => [ ... ]
 ```
 
 ## I'd like the rows to be indexible by column name.
@@ -273,7 +271,18 @@ is unavailable on the row, although the "types" property remains.)
 ```
 
 
-The other way is to use Ara Howard's
+A more granular way to do this is via `ResultSet#next_hash` or
+`ResultSet#each_hash`.
+
+
+```ruby
+  results = db.query( "select * from table" )
+  row = results.next_hash
+  p row['column1']
+```
+
+
+Another way is to use Ara Howard's
 [`ArrayFields`](http://rubyforge.org/projects/arrayfields)
 module. Just `require "arrayfields"`, and all of your rows will be indexable
 by column name, even though they are still arrays!

data/INSTALLATION.md

@@ -14,15 +14,13 @@ In v2.0.0 and later, native (precompiled) gems are available for recent Ruby ver
 - `arm-linux-gnu` (requires: glibc >= 2.29)
 - `arm-linux-musl`
 - `arm64-darwin`
-- `x64-mingw32` / `x64-mingw-ucrt`
+- `x64-mingw-ucrt`
 - `x86-linux-gnu` (requires: glibc >= 2.17)
 - `x86-linux-musl`
 - `x86_64-darwin`
 - `x86_64-linux-gnu` (requires: glibc >= 2.17)
 - `x86_64-linux-musl`
 
-⚠ Ruby 3.0 linux users must use Rubygems >= 3.3.22 in order to use these gems.
-
 ⚠ Musl linux users should update to Bundler >= 2.5.6 to avoid https://github.com/rubygems/rubygems/issues/7432
 
 If you are using one of these Ruby versions on one of these platforms, the native gem is the recommended way to install sqlite3-ruby.

data/README.md

@@ -148,6 +148,23 @@ 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.
+
+See [./adr/2024-09-fork-safety.md](./adr/2024-09-fork-safety.md) for more information and context.
+
+
 ## Support
 
 ### Installation or database extensions

data/ext/sqlite3/database.c

@@ -12,6 +12,64 @@
 
 VALUE cSqlite3Database;
 
+/* See adr/2024-09-fork-safety.md */
+static void
+discard_db(sqlite3RubyPtr ctx)
+{
+    sqlite3_file *sfile;
+    int status;
+
+    // release as much heap memory as possible by deallocating non-essential memory
+    // allocations held by the database library. Memory used to cache database pages to
+    // improve performance is an example of non-essential memory.
+    // on my development machine, this reduces the lost memory from 152k to 69k.
+    sqlite3_db_release_memory(ctx->db);
+
+    // release file descriptors
+#ifdef HAVE_SQLITE3_DB_NAME
+    const char *db_name;
+    int j_db = 0;
+    while ((db_name = sqlite3_db_name(ctx->db, j_db)) != NULL) {
+        status = sqlite3_file_control(ctx->db, db_name, SQLITE_FCNTL_FILE_POINTER, &sfile);
+        if (status == 0 && sfile->pMethods != NULL) {
+            sfile->pMethods->xClose(sfile);
+        }
+        j_db++;
+    }
+#else
+    status = sqlite3_file_control(ctx->db, NULL, SQLITE_FCNTL_FILE_POINTER, &sfile);
+    if (status == 0 && sfile->pMethods != NULL) {
+        sfile->pMethods->xClose(sfile);
+    }
+#endif
+
+    status = sqlite3_file_control(ctx->db, NULL, SQLITE_FCNTL_JOURNAL_POINTER, &sfile);
+    if (status == 0 && sfile->pMethods != NULL) {
+        sfile->pMethods->xClose(sfile);
+    }
+
+    ctx->db = NULL;
+    ctx->flags |= SQLITE3_RB_DATABASE_DISCARDED;
+}
+
+static void
+close_or_discard_db(sqlite3RubyPtr ctx)
+{
+    if (ctx->db) {
+        int is_readonly = (ctx->flags & SQLITE3_RB_DATABASE_READONLY);
+
+        if (is_readonly || ctx->owner == getpid()) {
+            // Ordinary close.
+            sqlite3_close_v2(ctx->db);
+            ctx->db = NULL;
+        } else {
+            // This is an open connection carried across a fork(). "Discard" it.
+            discard_db(ctx);
+        }
+    }
+}
+
+
 static void
 database_mark(void *ctx)
 {
@@ -22,11 +80,8 @@ database_mark(void *ctx)
 static void
 deallocate(void *ctx)
 {
-    sqlite3RubyPtr c = (sqlite3RubyPtr)ctx;
-    sqlite3 *db     = c->db;
-
-    if (db) { sqlite3_close(db); }
-    xfree(c);
+    close_or_discard_db((sqlite3RubyPtr)ctx);
+    xfree(ctx);
 }
 
 static size_t
@@ -51,7 +106,9 @@ static VALUE
 allocate(VALUE klass)
 {
     sqlite3RubyPtr ctx;
-    return TypedData_Make_Struct(klass, sqlite3Ruby, &database_type, ctx);
+    VALUE object = TypedData_Make_Struct(klass, sqlite3Ruby, &database_type, ctx);
+    ctx->owner = getpid();
+    return object;
 }
 
 static char *
@@ -62,8 +119,6 @@ utf16_string_value_ptr(VALUE str)
     return RSTRING_PTR(str);
 }
 
-static VALUE sqlite3_rb_close(VALUE self);
-
 sqlite3RubyPtr
 sqlite3_database_unwrap(VALUE database)
 {
@@ -77,6 +132,7 @@ rb_sqlite3_open_v2(VALUE self, VALUE file, VALUE mode, VALUE zvfs)
 {
     sqlite3RubyPtr ctx;
     int status;
+    int flags;
 
     TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
 
@@ -89,14 +145,18 @@ rb_sqlite3_open_v2(VALUE self, VALUE file, VALUE mode, VALUE zvfs)
 #  endif
 #endif
 
+    flags = NUM2INT(mode);
     status = sqlite3_open_v2(
                  StringValuePtr(file),
                  &ctx->db,
-                 NUM2INT(mode),
+                 flags,
                  NIL_P(zvfs) ? NULL : StringValuePtr(zvfs)
              );
 
-    CHECK(ctx->db, status)
+    CHECK(ctx->db, status);
+    if (flags & SQLITE_OPEN_READONLY) {
+        ctx->flags |= SQLITE3_RB_DATABASE_READONLY;
+    }
 
     return self;
 }
@@ -119,21 +179,38 @@ rb_sqlite3_disable_quirk_mode(VALUE self)
 #endif
 }
 
-/* call-seq: db.close
+/*
+ *  Close the database and release all associated resources.
  *
- * Closes this database.
+ *  ⚠ Writable connections that are carried across a <tt>fork()</tt> are not completely
+ *  closed. {Sqlite does not support forking}[https://www.sqlite.org/howtocorrupt.html],
+ *  and fully closing a writable connection that has been carried across a fork may corrupt the
+ *  database. Since it is an incomplete close, not all memory resources are freed, but this is safer
+ *  than risking data loss.
+ *
+ *  See rdoc-ref:adr/2024-09-fork-safety.md for more information on fork safety.
  */
 static VALUE
 sqlite3_rb_close(VALUE self)
 {
     sqlite3RubyPtr ctx;
-    sqlite3 *db;
     TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
 
-    db = ctx->db;
-    CHECK(db, sqlite3_close(ctx->db));
+    close_or_discard_db(ctx);
 
-    ctx->db = NULL;
+    rb_iv_set(self, "-aggregators", Qnil);
+
+    return self;
+}
+
+/* private method, primarily for testing */
+static VALUE
+sqlite3_rb_discard(VALUE self)
+{
+    sqlite3RubyPtr ctx;
+    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
+
+    discard_db(ctx);
 
     rb_iv_set(self, "-aggregators", Qnil);
 
@@ -246,7 +323,7 @@ busy_handler(int argc, VALUE *argv, VALUE self)
     rb_scan_args(argc, argv, "01", &block);
 
     if (NIL_P(block) && rb_block_given_p()) { block = rb_block_proc(); }
-    ctx->busy_handler = block;
+    RB_OBJ_WRITE(self, &ctx->busy_handler, block);
 
     status = sqlite3_busy_handler(
                  ctx->db,
@@ -869,6 +946,9 @@ rb_sqlite3_open16(VALUE self, VALUE file)
 #endif
 #endif
 
+    // sqlite3_open16 implicitly uses flags (SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE)
+    // see https://www.sqlite.org/capi3ref.html#sqlite3_open
+    // so we do not ever set SQLITE3_RB_DATABASE_READONLY in ctx->flags
     status = sqlite3_open16(utf16_string_value_ptr(file), &ctx->db);
 
     CHECK(ctx->db, status)
@@ -889,6 +969,7 @@ init_sqlite3_database(void)
     rb_define_private_method(cSqlite3Database, "open16", rb_sqlite3_open16, 1);
     rb_define_method(cSqlite3Database, "collation", collation, 2);
     rb_define_method(cSqlite3Database, "close", sqlite3_rb_close, 0);
+    rb_define_private_method(cSqlite3Database, "discard", sqlite3_rb_discard, 0);
     rb_define_method(cSqlite3Database, "closed?", closed_p, 0);
     rb_define_method(cSqlite3Database, "total_changes", total_changes, 0);
     rb_define_method(cSqlite3Database, "trace", trace, -1);

data/ext/sqlite3/database.h

@@ -3,11 +3,17 @@
 
 #include <sqlite3_ruby.h>
 
+/* bits in the `flags` field */
+#define SQLITE3_RB_DATABASE_READONLY  0x01
+#define SQLITE3_RB_DATABASE_DISCARDED 0x02
+
 struct _sqlite3Ruby {
     sqlite3 *db;
     VALUE busy_handler;
     int stmt_timeout;
     struct timespec stmt_deadline;
+    rb_pid_t owner;
+    int flags;
 };
 
 typedef struct _sqlite3Ruby sqlite3Ruby;

data/ext/sqlite3/extconf.rb

@@ -131,6 +131,8 @@ module Sqlite3
         end
 
         have_func("sqlite3_prepare_v2")
+        have_func("sqlite3_db_name", "sqlite3.h") # v3.39.0
+
         have_type("sqlite3_int64", "sqlite3.h")
         have_type("sqlite3_uint64", "sqlite3.h")
       end

data/ext/sqlite3/statement.c

@@ -1,9 +1,13 @@
 #include <sqlite3_ruby.h>
 
 #define REQUIRE_OPEN_STMT(_ctxt) \
-  if(!_ctxt->st) \
+  if (!_ctxt->st) \
     rb_raise(rb_path2class("SQLite3::Exception"), "cannot use a closed statement");
 
+#define REQUIRE_LIVE_DB(_ctxt) \
+  if (_ctxt->db->flags & SQLITE3_RB_DATABASE_DISCARDED) \
+    rb_raise(rb_path2class("SQLite3::Exception"), "cannot use a statement associated with a discarded database");
+
 VALUE cSqlite3Statement;
 
 static void
@@ -57,6 +61,11 @@ prepare(VALUE self, VALUE db, VALUE sql)
 
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
 
+    /* Dereferencing a pointer to the database struct will be faster than accessing it through the
+     * instance variable @connection. The struct pointer is guaranteed to be live because instance
+     * variable will keep it from being GCed. */
+    ctx->db = db_ctx;
+
 #ifdef HAVE_SQLITE3_PREPARE_V2
     status = sqlite3_prepare_v2(
 #else
@@ -121,6 +130,7 @@ step(VALUE self)
 
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
 
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     if (ctx->done_p) { return Qnil; }
@@ -216,6 +226,8 @@ bind_param(VALUE self, VALUE key, VALUE value)
     int index;
 
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     switch (TYPE(key)) {
@@ -308,6 +320,8 @@ reset_bang(VALUE self)
     sqlite3StmtRubyPtr ctx;
 
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     sqlite3_reset(ctx->st);
@@ -328,6 +342,8 @@ clear_bindings_bang(VALUE self)
     sqlite3StmtRubyPtr ctx;
 
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     sqlite3_clear_bindings(ctx->st);
@@ -360,6 +376,8 @@ column_count(VALUE self)
 {
     sqlite3StmtRubyPtr ctx;
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     return INT2NUM(sqlite3_column_count(ctx->st));
@@ -391,6 +409,8 @@ column_name(VALUE self, VALUE index)
     const char *name;
 
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     name = sqlite3_column_name(ctx->st, (int)NUM2INT(index));
@@ -414,6 +434,8 @@ column_decltype(VALUE self, VALUE index)
     const char *name;
 
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     name = sqlite3_column_decltype(ctx->st, (int)NUM2INT(index));
@@ -431,6 +453,8 @@ bind_parameter_count(VALUE self)
 {
     sqlite3StmtRubyPtr ctx;
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     return INT2NUM(sqlite3_bind_parameter_count(ctx->st));
@@ -538,7 +562,10 @@ stats_as_hash(VALUE self)
 {
     sqlite3StmtRubyPtr ctx;
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
+
     VALUE arg = rb_hash_new();
 
     stmt_stat_internal(arg, ctx->st);
@@ -554,6 +581,8 @@ stat_for(VALUE self, VALUE key)
 {
     sqlite3StmtRubyPtr ctx;
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     if (SYMBOL_P(key)) {
@@ -574,6 +603,8 @@ memused(VALUE self)
 {
     sqlite3StmtRubyPtr ctx;
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     return INT2NUM(sqlite3_stmt_status(ctx->st, SQLITE_STMTSTATUS_MEMUSED, 0));
@@ -591,6 +622,8 @@ database_name(VALUE self, VALUE index)
 {
     sqlite3StmtRubyPtr ctx;
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     return SQLITE3_UTF8_STR_NEW2(
@@ -608,6 +641,8 @@ get_sql(VALUE self)
 {
     sqlite3StmtRubyPtr ctx;
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     return rb_obj_freeze(SQLITE3_UTF8_STR_NEW2(sqlite3_sql(ctx->st)));
@@ -626,6 +661,8 @@ get_expanded_sql(VALUE self)
     VALUE rb_expanded_sql;
 
     TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
     REQUIRE_OPEN_STMT(ctx);
 
     expanded_sql = sqlite3_expanded_sql(ctx->st);

data/ext/sqlite3/statement.h

@@ -5,6 +5,7 @@
 
 struct _sqlite3StmtRuby {
     sqlite3_stmt *st;
+    sqlite3Ruby *db;
     int done_p;
 };
 

data/lib/sqlite3/database.rb

@@ -5,6 +5,7 @@ require "sqlite3/errors"
 require "sqlite3/pragmas"
 require "sqlite3/statement"
 require "sqlite3/value"
+require "sqlite3/fork_safety"
 
 module SQLite3
   # The Database class encapsulates a single connection to a SQLite3 database.
@@ -127,7 +128,6 @@ module SQLite3
 
       @tracefunc = nil
       @authorizer = nil
-      @busy_handler = nil
       @progress_handler = nil
       @collations = {}
       @functions = {}
@@ -135,6 +135,8 @@ module SQLite3
       @readonly = mode & Constants::Open::READONLY != 0
       @default_transaction_mode = options[:default_transaction_mode] || :deferred
 
+      ForkSafety.track(self)
+
       if block_given?
         begin
           yield self

data/lib/sqlite3/fork_safety.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "weakref"
+
+# based on Rails's active_support/fork_tracker.rb
+module SQLite3
+  module ForkSafety
+    module CoreExt
+      def _fork
+        pid = super
+        if pid == 0
+          ForkSafety.discard
+        end
+        pid
+      end
+    end
+
+    @databases = []
+    @mutex = Mutex.new
+    @suppress = false
+
+    class << self
+      def hook!
+        ::Process.singleton_class.prepend(CoreExt)
+      end
+
+      def track(database)
+        @mutex.synchronize do
+          @databases << WeakRef.new(database)
+        end
+      end
+
+      def discard
+        warned = @suppress
+        @databases.each do |db|
+          next unless db.weakref_alive?
+
+          unless db.closed? || db.readonly?
+            unless warned
+              # If you are here, you may want to read
+              # https://github.com/sparklemotion/sqlite3-ruby/pull/558
+              warn("Writable sqlite database connection(s) were inherited from a forked process. " \
+                   "This is unsafe and the connections are being closed to prevent possible data " \
+                   "corruption. Please close writable sqlite database connections before forking.",
+                uplevel: 0)
+              warned = true
+            end
+            db.close
+          end
+        end
+        @databases.clear
+      end
+
+      # Call to suppress the fork-related warnings.
+      def suppress_warnings!
+        @suppress = true
+      end
+    end
+  end
+end
+
+SQLite3::ForkSafety.hook!

data/lib/sqlite3/version.rb

@@ -1,3 +1,3 @@
 module SQLite3
-  VERSION = "2.0.4"
+  VERSION = "2.1.0.rc3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sqlite3
 version: !ruby/object:Gem::Version
-  version: 2.0.4
+  version: 2.1.0.rc3
 platform: ruby
 authors:
 - Jamis Buck
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-13 00:00:00.000000000 Z
+date: 2024-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mini_portile2
@@ -27,7 +27,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.8.0
-  force_ruby_platform: false
 description: |
   Ruby library to interface with the SQLite3 database engine (http://www.sqlite.org). Precompiled
   binaries are available for common platforms for recent versions of Ruby.
@@ -71,6 +70,7 @@ files:
 - lib/sqlite3/constants.rb
 - lib/sqlite3/database.rb
 - lib/sqlite3/errors.rb
+- lib/sqlite3/fork_safety.rb
 - lib/sqlite3/pragmas.rb
 - lib/sqlite3/resultset.rb
 - lib/sqlite3/statement.rb
@@ -98,14 +98,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Ruby library to interface with the SQLite3 database engine (http://www.sqlite.org).