Merge branch 'main' into sandlerr/ractor

* main:
  build(deps-dev): update rdoc requirement from 6.12.0 to 6.13.0
  ci: get upstream sqlite-head job green
  build(deps-dev): update minitest requirement from 5.25.4 to 5.25.5
  Add parameter checking for string value pragmas
  Simplify PRAGMA related constants
  Add some regression tests for setting pragmas
  Freeze strings and constants in pragmas

Author: tenderlove

.github/workflows/upstream.yml

@@ -25,7 +25,6 @@ jobs:
         with:
           ruby-version: "3.3"
           bundler-cache: true
-          apt-get: tcl-dev # https://sqlite.org/forum/forumpost/45c4862d37
       - run: bundle exec rake compile -- --with-sqlite-source-dir=${GITHUB_WORKSPACE}/sqlite
       - run: bundle exec rake test
 

Gemfile

@@ -3,7 +3,7 @@ source "https://rubygems.org"
 gemspec
 
 group :test do
-  gem "minitest", "5.25.4"
+  gem "minitest", "5.25.5"
 
   gem "ruby_memcheck", "3.0.1" if Gem::Platform.local.os == "linux"
 
@@ -12,7 +12,7 @@ group :test do
 end
 
 group :development do
-  gem "rdoc", "6.12.0"
+  gem "rdoc", "6.13.0"
 
   gem "rubocop", "1.59.0", require: false
   gem "rubocop-minitest", "0.34.5", require: false

RACTOR.md

@@ -0,0 +1,121 @@
+# Ractor support in SQLite3-Ruby
+
+SQLite3 has [3 different modes of threading support](https://www.sqlite.org/threadsafe.html).
+
+1. Single-thread
+2. Multi-thread
+3. Serialized
+
+"Single thread" mode means there are no mutexes, so the library itself is not
+thread safe.  In other words if two threads do `SQLite3::Database.new` on the
+same file, it will have thread safety problems.
+
+"Multi thread" mode means that SQLite3 puts mutexes in place, but it does not
+mean that the SQLite3 API itself is thread safe.  In other words, in this mode
+it is SAFE for two threads to do `SQLite3::Database.new` on the same file, but
+it is NOT SAFE to share that database object between two threads.
+
+"Serialized" mode is like "Multi thread" mode except that there are mutexes in
+place such that it IS SAFE to share the same database object between threads.
+
+## Ractor Safety
+
+When a C extension claims to be Ractor safe by calling `rb_ext_ractor_safe`,
+it's merely claiming that it's C API is thread safe.  This _does not_ mean that
+objects allocated from said C extension are allowed to cross between Ractor
+boundaries.
+
+In other words, `rb_ext_ractor_safe` matches the expectations of the
+"multi-thread" mode of SQLite3.  We can detect the multithread mode via the
+`sqlite3_threadsafe` function.  In other words, it's fine to declare this
+extension is Ractor safe, but only if `sqlite3_threadsafe` returns true.
+
+Even if we call `rb_ext_ractor_safe`, no database objects are allowed to be
+passed between Ractors.  For example, this code will break with a Ractor error:
+
+```ruby
+require "sqlite3"
+
+r = Ractor.new {
+  loop do
+    break unless Ractor.receive
+  end
+}
+
+db = SQLite3::Database.new ":memory:"
+
+begin
+  r.send db
+  puts "unreachable"
+rescue Ractor::Error
+end
+```
+
+If the user opens the database in "Serialized" mode, then it _is_ OK to pass
+the database object between Ractors, or access the database in parallel because
+the SQLite API is fully thread-safe.
+
+Passing the db connection is fine:
+
+```ruby
+r = Ractor.new {
+  loop do
+    break unless Ractor.receive
+  end
+}
+
+db = SQLite3::Database.new ":memory:",
+  flags: SQLite3::Constants::Open::FULLMUTEX |
+      SQLite3::Constants::Open::READWRITE |
+      SQLite3::Constants::Open::CREATE
+
+# works
+r.send db
+```
+
+Access the DB connection via global is fine:
+
+```ruby
+require "sqlite3"
+
+DB = SQLite3::Database.new ":memory:",
+  flags: SQLite3::Constants::Open::FULLMUTEX |
+      SQLite3::Constants::Open::READWRITE |
+      SQLite3::Constants::Open::CREATE
+
+r = Ractor.new {
+  loop do
+    Ractor.receive
+    p DB
+  end
+}
+
+
+r.send 123
+sleep
+```
+
+## Fork Safety
+
+Fork safety is restricted to database objects that were created on the main
+Ractor.  When a process forks, the child process shuts down all Ractors, so
+any database connections that are inside a Ractor should be released.
+
+However, this doesn't account for a situation where a child Ractor passes a
+database to the main Ractor:
+
+```ruby
+require "sqlite3"
+
+db = Ractor.new {
+    SQLite3::Database.new ":memory:",
+        flags: SQLite3::Constants::Open::FULLMUTEX |
+            SQLite3::Constants::Open::READWRITE |
+            SQLite3::Constants::Open::CREATE
+}.take
+
+fork {
+  # db wasn't tracked
+  p db
+}
+```

ext/sqlite3/database.c

@@ -160,6 +160,7 @@ rb_sqlite3_open_v2(VALUE self, VALUE file, VALUE mode, VALUE zvfs)
 
     if (flags & SQLITE_OPEN_FULLMUTEX) {
         FL_SET_RAW(self, RUBY_FL_SHAREABLE);
+        OBJ_FREEZE(self);
     }
 
     return self;

lib/sqlite3/database.rb

@@ -141,6 +141,15 @@ def quote(string)
     def initialize file, options = {}, zvfs = nil
       mode = Constants::Open::READWRITE | Constants::Open::CREATE
 
+      @tracefunc = nil
+      @authorizer = nil
+      @progress_handler = nil
+      @collations = {}
+      @functions = {}
+      @results_as_hash = options[:results_as_hash]
+      @readonly = false
+      @default_transaction_mode = options[:default_transaction_mode] || :deferred
+
       file = file.to_path if file.respond_to? :to_path
       if file.encoding == ::Encoding::UTF_16LE || file.encoding == ::Encoding::UTF_16BE || options[:utf16]
         open16 file
@@ -163,22 +172,15 @@ def initialize file, options = {}, zvfs = nil
           mode = options[:flags]
         end
 
+        @readonly = mode & Constants::Open::READONLY != 0
+
         open_v2 file.encode("utf-8"), mode, zvfs
 
         if options[:strict]
           disable_quirk_mode
         end
       end
 
-      @tracefunc = nil
-      @authorizer = nil
-      @progress_handler = nil
-      @collations = {}
-      @functions = {}
-      @results_as_hash = options[:results_as_hash]
-      @readonly = mode & Constants::Open::READONLY != 0
-      @default_transaction_mode = options[:default_transaction_mode] || :deferred
-
       initialize_extensions(options[:extensions])
 
       ForkSafety.track(self) if Ractor.main?
@@ -196,7 +198,7 @@ def initialize file, options = {}, zvfs = nil
     #
     # Fetch the encoding set on this database
     def encoding
-      prepare("PRAGMA encoding") { |stmt| Encoding.find(stmt.first.first) }
+      Encoding.find super
     end
 
     # Installs (or removes) a block that will be invoked for every access

lib/sqlite3/pragmas.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "sqlite3/errors"
 
 module SQLite3
@@ -58,11 +60,20 @@ def get_enum_pragma(name)
     # have duplicate values. See #synchronous, #default_synchronous,
     # #temp_store, and #default_temp_store for usage examples.
     def set_enum_pragma(name, mode, enums)
-      match = enums.find { |p| p.find { |i| i.to_s.downcase == mode.to_s.downcase } }
+      match = if enums.is_a?(Array)
+        # maybe deprecate this?
+        enums.find { |p| p.find { |i| i.to_s.downcase == mode.to_s.downcase } }
+      elsif mode.is_a?(String)
+        enums.fetch(mode.downcase)
+      else
+        mode
+      end
+
       unless match
         raise SQLite3::Exception, "unrecognized #{name} #{mode.inspect}"
       end
-      execute("PRAGMA #{name}='#{match.first.upcase}'")
+
+      execute("PRAGMA #{name}='#{match}'")
     end
 
     # Returns the value of the given pragma as an integer.
@@ -77,26 +88,57 @@ def set_int_pragma(name, value)
     end
 
     # The enumeration of valid synchronous modes.
-    SYNCHRONOUS_MODES = [["full", 2], ["normal", 1], ["off", 0]]
+    SYNCHRONOUS_MODES = {
+      "full" => 2,
+      "normal" => 1,
+      "off" => 0
+    }.freeze
 
     # The enumeration of valid temp store modes.
-    TEMP_STORE_MODES = [["default", 0], ["file", 1], ["memory", 2]]
+    TEMP_STORE_MODES = {
+      "default" => 0,
+      "file" => 1,
+      "memory" => 2
+    }.freeze
 
     # The enumeration of valid auto vacuum modes.
-    AUTO_VACUUM_MODES = [["none", 0], ["full", 1], ["incremental", 2]]
+    AUTO_VACUUM_MODES = {
+      "none" => 0,
+      "full" => 1,
+      "incremental" => 2
+    }.freeze
 
     # The list of valid journaling modes.
-    JOURNAL_MODES = [["delete"], ["truncate"], ["persist"], ["memory"],
-      ["wal"], ["off"]]
+    JOURNAL_MODES = {
+      "delete" => "delete",
+      "truncate" => "truncate",
+      "persist" => "persist",
+      "memory" => "memory",
+      "wal" => "wal",
+      "off" => "off"
+    }.freeze
 
     # The list of valid locking modes.
-    LOCKING_MODES = [["normal"], ["exclusive"]]
+    LOCKING_MODES = {
+      "normal" => "normal",
+      "exclusive" => "exclusive"
+    }.freeze
 
     # The list of valid encodings.
-    ENCODINGS = [["utf-8"], ["utf-16"], ["utf-16le"], ["utf-16be"]]
+    ENCODINGS = {
+      "utf-8" => "utf-8",
+      "utf-16" => "utf-16",
+      "utf-16le" => "utf-16le",
+      "utf-16be" => "utf-16be"
+    }.freeze
 
     # The list of valid WAL checkpoints.
-    WAL_CHECKPOINTS = [["passive"], ["full"], ["restart"], ["truncate"]]
+    WAL_CHECKPOINTS = {
+      "passive" => "passive",
+      "full" => "full",
+      "restart" => "restart",
+      "truncate" => "truncate"
+    }.freeze
 
     def application_id
       get_int_pragma "application_id"
@@ -227,7 +269,7 @@ def encoding
     end
 
     def encoding=(mode)
-      set_enum_pragma "encoding", mode, ENCODINGS
+      set_string_pragma "encoding", mode, ENCODINGS
     end
 
     def foreign_key_check(*table, &block) # :yields: row
@@ -295,7 +337,7 @@ def journal_mode
     end
 
     def journal_mode=(mode)
-      set_enum_pragma "journal_mode", mode, JOURNAL_MODES
+      set_string_pragma "journal_mode", mode, JOURNAL_MODES
     end
 
     def journal_size_limit
@@ -319,7 +361,7 @@ def locking_mode
     end
 
     def locking_mode=(mode)
-      set_enum_pragma "locking_mode", mode, LOCKING_MODES
+      set_string_pragma "locking_mode", mode, LOCKING_MODES
     end
 
     def max_page_count
@@ -525,7 +567,7 @@ def wal_checkpoint
     end
 
     def wal_checkpoint=(mode)
-      set_enum_pragma "wal_checkpoint", mode, WAL_CHECKPOINTS
+      set_string_pragma "wal_checkpoint", mode, WAL_CHECKPOINTS
     end
 
     def writable_schema=(mode)
@@ -568,6 +610,13 @@ def table_info table
 
     private
 
+    def set_string_pragma(pragma_name, value, valid_values)
+      valid_values.fetch(value.to_s.downcase) {
+        raise SQLite3::Exception, "unrecognized #{pragma_name} #{value.inspect}"
+      }
+      set_enum_pragma(pragma_name, value, valid_values)
+    end
+
     # Compares two version strings
     def version_compare(v1, v2)
       v1 = v1.split(".").map { |i| i.to_i }

test/test_pragmas.rb

@@ -27,6 +27,18 @@ def teardown
       @db.close
     end
 
+    def test_temp_store_mode
+      @db.temp_store = "memory"
+      assert_equal 2, @db.temp_store
+      @db.temp_store = 1
+      assert_equal 1, @db.temp_store
+    end
+
+    def test_encoding
+      @db.encoding = "utf-16le"
+      assert_equal Encoding.find("utf-16le"), @db.encoding
+    end
+
     def test_pragma_errors
       assert_raises(SQLite3::Exception) do
         @db.set_enum_pragma("foo", "bar", [])
@@ -41,6 +53,12 @@ def test_pragma_errors
       end
     end
 
+    def test_invalid_pragma
+      assert_raises(SQLite3::Exception) do
+        @db.journal_mode = 0
+      end
+    end
+
     def test_get_boolean_pragma
       refute(@db.get_boolean_pragma("read_uncommitted"))
     end