sqlite3 2.3.1 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44f18cd0e1a516835e098651813a16650ee150cbca072d7b79cf01985a46cb17
-  data.tar.gz: 354f8cc6b3fdbc3fdcb94b7f5c059af5a546c7b27e97a37ba83054eca96845c0
+  metadata.gz: 587b8c3fba9ab76be92347be3c241505f2c09d0093145dce98a5eedd9015e2a8
+  data.tar.gz: a8d01d3ab6899819b2835122913498af86c0de2d535d08b40fb04755e50242cf
 SHA512:
-  metadata.gz: 45ac5eeb5c17f32b36e3e28ad07ed322466ead714a246e3a26714e7439c564b09ba22907b12b85d2b8fe1f5a40b4e064fb5e1d47f86b02477eb6cb14c16507f1
-  data.tar.gz: ff61bacb08bd6ef512fa160aabd0f0b47be0c3889801c17ec0c86764dc271e4b112e6ced95f9b504cf225247f885afddec1d6f3ea433323e00366fd9ce254a45
+  metadata.gz: 87a6d40f2ce8a425c0d0862c6e89cbee7ce0de85f4ac4538993a4dadc6e18bc8a6b72d584b609bbb5a489c80b6db625e2f74b6dd8383e3d20898d303e3225c20
+  data.tar.gz: a555066e5fce69ec409658c3ea8ffdf558d57ec3413d1fb21a002472c350527c303329a0a4c32c26814faa758640233abf9e71f8febf111922f8c4702ad52fb9

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # sqlite3-ruby Changelog
 
+## 2.4.1 / 2024-12-08
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.47.2](https://sqlite.org/releaselog/3_47.2.html) #593 @flavorjones
+
+  The description from the upstream maintainers is:
+
+  > SQLite version 3.47.2, now available, fixes an important bug that first appeared in the 3.47.0
+  > release. In SQLite versions 3.47.0 and 3.47.1, if you try to convert a string into a
+  > floating-point value and the first 16 significant digits of the value are exactly
+  > "1844674407370955", then the floating-point number generated might be incorrect. The problem
+  > only affects x64 and i386 CPUs, so it does not affect you if you are running on ARM. And it only
+  > affects releases 3.47.0 and 3.47.1. **If you are running SQLite versions 3.47.0 or 3.47.1, then
+  > upgrading is recommended.**
+
+  Saving you a click, you should upgrade if you're running sqlite3-ruby v2.1.1 or later.
+
+
+### Fixed
+
+- Prevent unnecessary "Invalid Reference" warnings from the `ForkSafety` module when GC runs during the "after fork" hook. #592 @flavorjones
+
+
+## 2.4.0 / 2024-12-03
+
+### Added
+
+- `Database#load_extension` now accepts any object that responds to `#to_path`, in addition to String filesystem paths. [#586] @flavorjones
+- `Database.new` now accepts an `extensions:` parameter, which is an array of SQLite extensions that will be loaded during initialization. The array may contain String filesystem paths and objects that respond to `#to_path`. [#586] @flavorjones
+
+
 ## 2.3.1 / 2024-11-25
 
 ### Dependencies

data/README.md

@@ -9,20 +9,20 @@ Note that this module is only compatible with SQLite 3.6.16 or newer.
 * Source code: https://github.com/sparklemotion/sqlite3-ruby
 * Mailing list: http://groups.google.com/group/sqlite3-ruby
 * Download: http://rubygems.org/gems/sqlite3
-* Documentation: http://www.rubydoc.info/gems/sqlite3
+* Documentation: https://sparklemotion.github.io/sqlite3-ruby/
 
 [![Test suite](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/ci.yml)
 
 
 ## Quick start
 
-For help understanding the SQLite3 Ruby API, please read the [FAQ](./FAQ.md) and the [full API documentation](https://rubydoc.info/gems/sqlite3).
+For help understanding the SQLite3 Ruby API, please read the [FAQ](./FAQ.md) and the [full API documentation](https://sparklemotion.github.io/sqlite3-ruby/).
 
 A few key classes whose APIs are often-used are:
 
-- SQLite3::Database ([rdoc](https://rubydoc.info/gems/sqlite3/SQLite3/Database))
-- SQLite3::Statement ([rdoc](https://rubydoc.info/gems/sqlite3/SQLite3/Statement))
-- SQLite3::ResultSet ([rdoc](https://rubydoc.info/gems/sqlite3/SQLite3/ResultSet))
+- SQLite3::Database ([rdoc](https://sparklemotion.github.io/sqlite3-ruby/SQLite3/Database.html))
+- SQLite3::Statement ([rdoc](https://sparklemotion.github.io/sqlite3-ruby/SQLite3/Statement.html))
+- SQLite3::ResultSet ([rdoc](https://sparklemotion.github.io/sqlite3-ruby/SQLite3/ResultSet.html))
 
 If you have any questions that you feel should be addressed in the FAQ, please send them to [the mailing list](http://groups.google.com/group/sqlite3-ruby) or open a [discussion thread](https://github.com/sparklemotion/sqlite3-ruby/discussions/categories/q-a).
 

data/dependencies.yml

@@ -1,13 +1,13 @@
 sqlite3:
   # checksum verified by first checking the published sha3(256) checksum against https://sqlite.org/download.html:
-  # c6c1756fbeb1e34e0ee31f8609bfc1fd4630b3faadde71a28ad3a55df259d854
+  # 52cd4a2304b627abbabe1a438ba853d0f6edb8e2774fcb5773c7af11077afe94
   #
-  # $ sha3sum -a 256 ports/archives/sqlite-autoconf-3470100.tar.gz
-  # c6c1756fbeb1e34e0ee31f8609bfc1fd4630b3faadde71a28ad3a55df259d854  ports/archives/sqlite-autoconf-3470100.tar.gz
+  # $ sha3sum -a 256 ports/archives/sqlite-autoconf-3470200.tar.gz
+  # 52cd4a2304b627abbabe1a438ba853d0f6edb8e2774fcb5773c7af11077afe94  ports/archives/sqlite-autoconf-3470200.tar.gz
   #
-  # $ sha256sum ports/archives/sqlite-autoconf-3470100.tar.gz
-  # 416a6f45bf2cacd494b208fdee1beda509abda951d5f47bc4f2792126f01b452  ports/archives/sqlite-autoconf-3470100.tar.gz
-  version: "3.47.1"
+  # $ sha256sum ports/archives/sqlite-autoconf-3470200.tar.gz
+  # f1b2ee412c28d7472bc95ba996368d6f0cdcf00362affdadb27ed286c179540b  ports/archives/sqlite-autoconf-3470200.tar.gz
+  version: "3.47.2"
   files:
-    - url: "https://sqlite.org/2024/sqlite-autoconf-3470100.tar.gz"
-      sha256: "416a6f45bf2cacd494b208fdee1beda509abda951d5f47bc4f2792126f01b452"
+    - url: "https://sqlite.org/2024/sqlite-autoconf-3470200.tar.gz"
+      sha256: "f1b2ee412c28d7472bc95ba996368d6f0cdcf00362affdadb27ed286c179540b"

data/ext/sqlite3/database.c

@@ -771,14 +771,8 @@ collation(VALUE self, VALUE name, VALUE comparator)
 }
 
 #ifdef HAVE_SQLITE3_LOAD_EXTENSION
-/* call-seq: db.load_extension(file)
- *
- * Loads an SQLite extension library from the named file. Extension
- * loading must be enabled using db.enable_load_extension(true) prior
- * to calling this API.
- */
 static VALUE
-load_extension(VALUE self, VALUE file)
+load_extension_internal(VALUE self, VALUE file)
 {
     sqlite3RubyPtr ctx;
     int status;
@@ -997,7 +991,7 @@ init_sqlite3_database(void)
     rb_define_private_method(cSqlite3Database, "db_filename", db_filename, 1);
 
 #ifdef HAVE_SQLITE3_LOAD_EXTENSION
-    rb_define_method(cSqlite3Database, "load_extension", load_extension, 1);
+    rb_define_private_method(cSqlite3Database, "load_extension_internal", load_extension_internal, 1);
 #endif
 
 #ifdef HAVE_SQLITE3_ENABLE_LOAD_EXTENSION

data/lib/sqlite3/database.rb

@@ -8,8 +8,10 @@ require "sqlite3/value"
 require "sqlite3/fork_safety"
 
 module SQLite3
-  # The Database class encapsulates a single connection to a SQLite3 database.
-  # Its usage is very straightforward:
+  # == Overview
+  #
+  # The Database class encapsulates a single connection to a SQLite3 database.  Here's a
+  # straightforward example of usage:
   #
   #   require 'sqlite3'
   #
@@ -19,28 +21,68 @@ module SQLite3
   #     end
   #   end
   #
-  # It wraps the lower-level methods provided by the selected driver, and
-  # includes the Pragmas module for access to various pragma convenience
-  # methods.
+  # It wraps the lower-level methods provided by the selected driver, and includes the Pragmas
+  # module for access to various pragma convenience methods.
   #
-  # The Database class provides type translation services as well, by which
-  # the SQLite3 data types (which are all represented as strings) may be
-  # converted into their corresponding types (as defined in the schemas
-  # for their tables). This translation only occurs when querying data from
+  # The Database class provides type translation services as well, by which the SQLite3 data types
+  # (which are all represented as strings) may be converted into their corresponding types (as
+  # defined in the schemas for their tables). This translation only occurs when querying data from
   # the database--insertions and updates are all still typeless.
   #
-  # Furthermore, the Database class has been designed to work well with the
-  # ArrayFields module from Ara Howard. If you require the ArrayFields
-  # module before performing a query, and if you have not enabled results as
-  # hashes, then the results will all be indexible by field name.
+  # Furthermore, the Database class has been designed to work well with the ArrayFields module from
+  # Ara Howard. If you require the ArrayFields module before performing a query, and if you have not
+  # enabled results as hashes, then the results will all be indexible by field name.
+  #
+  # == Thread safety
+  #
+  # When SQLite3.threadsafe? returns true, it is safe to share instances of the database class
+  # among threads without adding specific locking. Other object instances may require applications
+  # to provide their own locks if they are to be shared among threads.  Please see the README.md for
+  # more information.
+  #
+  # == SQLite Extensions
+  #
+  # SQLite3::Database supports the universe of {sqlite
+  # extensions}[https://www.sqlite.org/loadext.html]. It's possible to load an extension into an
+  # existing Database object using the #load_extension method and passing a filesystem path:
+  #
+  #   db = SQLite3::Database.new(":memory:")
+  #   db.enable_load_extension(true)
+  #   db.load_extension("/path/to/extension")
+  #
+  # As of v2.4.0, it's also possible to pass an object that responds to +#to_path+. This
+  # documentation will refer to the supported interface as +_ExtensionSpecifier+, which can be
+  # expressed in RBS syntax as:
+  #
+  #   interface _ExtensionSpecifier
+  #     def to_path: () → String
+  #   end
+  #
+  # So, for example, if you are using the {sqlean gem}[https://github.com/flavorjones/sqlean-ruby]
+  # which provides modules that implement this interface, you can pass the module directly:
+  #
+  #   db = SQLite3::Database.new(":memory:")
+  #   db.enable_load_extension(true)
+  #   db.load_extension(SQLean::Crypto)
+  #
+  # It's also possible in v2.4.0+ to load extensions via the SQLite3::Database constructor by using
+  # the +extensions:+ keyword argument to pass an array of String paths or extension specifiers:
+  #
+  #   db = SQLite3::Database.new(":memory:", extensions: ["/path/to/extension", SQLean::Crypto])
+  #
+  # Note that when loading extensions via the constructor, there is no need to call
+  # #enable_load_extension; however it is still necessary to call #enable_load_extensions before any
+  # subsequently invocations of #load_extension on the initialized Database object.
   #
-  # Thread safety:
+  # You can load extensions in a Rails application by using the +extensions:+ configuration option:
+  #
+  #   # config/database.yml
+  #   development:
+  #     adapter: sqlite3
+  #     extensions:
+  #       - .sqlpkg/nalgeon/crypto/crypto.so # a filesystem path
+  #       - <%= SQLean::UUID.to_path %>      # or ruby code returning a path
   #
-  # When `SQLite3.threadsafe?` returns true, it is safe to share instances of
-  # the database class among threads without adding specific locking. Other
-  # object instances may require applications to provide their own locks if
-  # they are to be shared among threads.  Please see the README.md for more
-  # information.
   class Database
     attr_reader :collations
 
@@ -76,23 +118,25 @@ module SQLite3
     # as hashes or not. By default, rows are returned as arrays.
     attr_accessor :results_as_hash
 
-    # call-seq: SQLite3::Database.new(file, options = {})
+    # call-seq:
+    #   SQLite3::Database.new(file, options = {})
     #
     # Create a new Database object that opens the given file.
     #
     # Supported permissions +options+:
     # - the default mode is <tt>READWRITE | CREATE</tt>
-    # - +:readonly+: boolean (default false), true to set the mode to +READONLY+
-    # - +:readwrite+: boolean (default false), true to set the mode to +READWRITE+
-    # - +:flags+: set the mode to a combination of SQLite3::Constants::Open flags.
+    # - +readonly:+ boolean (default false), true to set the mode to +READONLY+
+    # - +readwrite:+ boolean (default false), true to set the mode to +READWRITE+
+    # - +flags:+ set the mode to a combination of SQLite3::Constants::Open flags.
     #
     # Supported encoding +options+:
-    # - +:utf16+: boolean (default false), is the filename's encoding UTF-16 (only needed if the filename encoding is not UTF_16LE or BE)
+    # - +utf16:+ +boolish+ (default false), is the filename's encoding UTF-16 (only needed if the filename encoding is not UTF_16LE or BE)
     #
     # Other supported +options+:
-    # - +:strict+: boolean (default false), disallow the use of double-quoted string literals (see https://www.sqlite.org/quirks.html#double_quoted_string_literals_are_accepted)
-    # - +:results_as_hash+: boolean (default false), return rows as hashes instead of arrays
-    # - +:default_transaction_mode+: one of +:deferred+ (default), +:immediate+, or +:exclusive+. If a mode is not specified in a call to #transaction, this will be the default transaction mode.
+    # - +strict:+ +boolish+ (default false), disallow the use of double-quoted string literals (see https://www.sqlite.org/quirks.html#double_quoted_string_literals_are_accepted)
+    # - +results_as_hash:+ +boolish+ (default false), return rows as hashes instead of arrays
+    # - +default_transaction_mode:+ one of +:deferred+ (default), +:immediate+, or +:exclusive+. If a mode is not specified in a call to #transaction, this will be the default transaction mode.
+    # - +extensions:+ <tt>Array[String | _ExtensionSpecifier]</tt> SQLite extensions to load into the database. See Database@SQLite+Extensions for more information.
     #
     def initialize file, options = {}, zvfs = nil
       mode = Constants::Open::READWRITE | Constants::Open::CREATE
@@ -135,6 +179,8 @@ module SQLite3
       @readonly = mode & Constants::Open::READONLY != 0
       @default_transaction_mode = options[:default_transaction_mode] || :deferred
 
+      initialize_extensions(options[:extensions])
+
       ForkSafety.track(self)
 
       if block_given?
@@ -658,6 +704,52 @@ module SQLite3
       end
     end
 
+    # call-seq:
+    #   load_extension(extension_specifier) -> self
+    #
+    # Loads an SQLite extension library from the named file. Extension loading must be enabled using
+    # #enable_load_extension prior to using this method.
+    #
+    # See also: Database@SQLite+Extensions
+    #
+    # [Parameters]
+    # - +extension_specifier+: (String | +_ExtensionSpecifier+) If a String, it is the filesystem path
+    #   to the sqlite extension file. If an object that responds to #to_path, the
+    #   return value of that method is used as the filesystem path to the sqlite extension file.
+    #
+    # [Example] Using a filesystem path:
+    #
+    #   db.load_extension("/path/to/my_extension.so")
+    #
+    # [Example] Using the {sqlean gem}[https://github.com/flavorjones/sqlean-ruby]:
+    #
+    #   db.load_extension(SQLean::VSV)
+    #
+    def load_extension(extension_specifier)
+      if extension_specifier.respond_to?(:to_path)
+        extension_specifier = extension_specifier.to_path
+      elsif !extension_specifier.is_a?(String)
+        raise TypeError, "extension_specifier #{extension_specifier.inspect} is not a String or a valid extension specifier object"
+      end
+      load_extension_internal(extension_specifier)
+    end
+
+    def initialize_extensions(extensions) # :nodoc:
+      return if extensions.nil?
+      raise TypeError, "extensions must be an Array" unless extensions.is_a?(Array)
+      return if extensions.empty?
+
+      begin
+        enable_load_extension(true)
+
+        extensions.each do |extension|
+          load_extension(extension)
+        end
+      ensure
+        enable_load_extension(false)
+      end
+    end
+
     # A helper class for dealing with custom functions (see #create_function,
     # #create_aggregate, and #create_aggregate_handler). It encapsulates the
     # opaque function object that represents the current invocation. It also

data/lib/sqlite3/fork_safety.rb

@@ -35,17 +35,21 @@ module SQLite3
         @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
+          begin
+            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
-            db.close
+          rescue WeakRef::RefError
+            # GC may run while this method is executing, and that's OK
           end
         end
         @databases.clear

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.3.1"
+  VERSION = "2.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sqlite3
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.1
 platform: ruby
 authors:
 - Jamis Buck
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-25 00:00:00.000000000 Z
+date: 2024-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mini_portile2
@@ -77,14 +77,14 @@ files:
 - lib/sqlite3/value.rb
 - lib/sqlite3/version.rb
 - lib/sqlite3/version_info.rb
-- ports/archives/sqlite-autoconf-3470100.tar.gz
+- ports/archives/sqlite-autoconf-3470200.tar.gz
 homepage: https://github.com/sparklemotion/sqlite3-ruby
 licenses:
 - BSD-3-Clause
 metadata:
   homepage_uri: https://github.com/sparklemotion/sqlite3-ruby
   bug_tracker_uri: https://github.com/sparklemotion/sqlite3-ruby/issues
-  documentation_uri: https://www.rubydoc.info/gems/sqlite3
+  documentation_uri: https://sparklemotion.github.io/sqlite3-ruby/
   changelog_uri: https://github.com/sparklemotion/sqlite3-ruby/blob/master/CHANGELOG.md
   source_code_uri: https://github.com/sparklemotion/sqlite3-ruby
   msys2_mingw_dependencies: sqlite3