sqlite3 2.0.4-arm64-darwin → 2.1.0-arm64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4fda41284b5cbc76faafcb5c91caba134045270b84ffb97b6bde6260d5434cc
-  data.tar.gz: 19a475ae4302ebc84aee3ef33d9be68c3207897d3e28e6aa0fcf723e67a47bd9
+  metadata.gz: 58efd48fc68d6c46767c603de815022f41d35eb2aaafb187b8f18fa71ff4330e
+  data.tar.gz: 3b904d8a115523e5a716ca2b1994fc66740181e40affddab7524c5c773a28576
 SHA512:
-  metadata.gz: dc80e97cfa3032788ccb5f615143ecd323ba56b729eb0d322f54e4bb19b695871441c1c3e9ca9ad87f37459cfc7969c5c8262a59b8f22b2148bcb1cbf9949d9a
-  data.tar.gz: ceb1d28498544812084c47eed7684a96d86e4b343148b4ad1bcde5d4fdb670e26576f904ce282b5b7beb3c091f6ee5dff9a93a24b0abaa857f657f5ee4673251
+  metadata.gz: 0e059c53db3c06f362ba18d1e8e3d2c588156225b3616adbff17d07f86c67688585d66807c4aa227b174e8dc9e0ea0f6acc23bc67d6a2c3ddec7dcf04aab0401
+  data.tar.gz: 2dc22242ff0d87c182c7b90dec3e14f85636d257d3576317142e30ad78b8ce7cc6d1638227d42ae968715d30e1ff17ecdbb07677fb713a2944e5f6fd4a5df415

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # sqlite3-ruby Changelog
 
+## 2.1.0 / 2024-09-24
+
+### 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. If absolutely necessary (and you know what you're doing), you may suppress the fork safety warnings by calling `SQLite3::ForkSafety.suppress_warnings!`.
+
+See the README's "Fork Safety" section and `adr/2024-09-fork-safety.md` for more information. [#558, #565, #566] @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
+
+
+### Documentation
+
+- The `FAQ.md` has been updated to fix some inaccuracies. [#562] @rickhull
+
+
 ## 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. 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

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"
 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
 platform: arm64-darwin
 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: []
 description: |
   Ruby library to interface with the SQLite3 database engine (http://www.sqlite.org). Precompiled
@@ -52,13 +52,13 @@ files:
 - ext/sqlite3/statement.h
 - ext/sqlite3/timespec.h
 - lib/sqlite3.rb
-- lib/sqlite3/3.0/sqlite3_native.bundle
 - lib/sqlite3/3.1/sqlite3_native.bundle
 - lib/sqlite3/3.2/sqlite3_native.bundle
 - lib/sqlite3/3.3/sqlite3_native.bundle
 - 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
@@ -84,7 +84,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
   - - "<"
     - !ruby/object:Gem::Version
       version: 3.4.dev