sqlite3 1.7.2 → 2.7.0

data/lib/sqlite3/database.rb

@@ -1,14 +1,17 @@
-require 'sqlite3/constants'
-require 'sqlite3/errors'
-require 'sqlite3/pragmas'
-require 'sqlite3/statement'
-require 'sqlite3/translator'
-require 'sqlite3/value'
+# frozen_string_literal: true
 
-module SQLite3
+require "sqlite3/constants"
+require "sqlite3/errors"
+require "sqlite3/pragmas"
+require "sqlite3/statement"
+require "sqlite3/value"
+require "sqlite3/fork_safety"
 
-  # The Database class encapsulates a single connection to a SQLite3 database.
-  # Its usage is very straightforward:
+module SQLite3
+  # == Overview
+  #
+  # The Database class encapsulates a single connection to a SQLite3 database.  Here's a
+  # straightforward example of usage:
   #
   #   require 'sqlite3'
   #
@@ -18,31 +21,79 @@ 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.
+  #
+  # 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
+  #       - SQLean::Crypto                   # Rails 8.1+ accepts the name of a constant that responds to `to_path`
+  #
   class Database
     attr_reader :collations
 
     include Pragmas
 
     class << self
-
       # Without block works exactly as new.
       # With block, like new closes the database at the end, but unlike new
       # returns the result of the block instead of the database instance.
-      def open( *args )
+      def open(*args)
         database = new(*args)
 
         if block_given?
@@ -59,34 +110,34 @@ module SQLite3
       # Quotes the given string, making it safe to use in an SQL statement.
       # It replaces all instances of the single-quote character with two
       # single-quote characters. The modified string is returned.
-      def quote( string )
-        string.gsub( /'/, "''" )
+      def quote(string)
+        string.gsub("'", "''")
       end
-
     end
 
     # A boolean that indicates whether rows in result sets should be returned
     # 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
-    # - +:type_translation+: boolean (default false), enable type translation
-    # - +: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
@@ -120,18 +171,19 @@ module SQLite3
         end
       end
 
-      @tracefunc        = nil
-      @authorizer       = nil
-      @encoding         = nil
-      @busy_handler     = nil
-      @collations       = {}
-      @functions        = {}
-      @results_as_hash  = options[:results_as_hash]
-      @type_translation = options[:type_translation]
-      @type_translator  = make_type_translator @type_translation
-      @readonly         = mode & Constants::Open::READONLY != 0
+      @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 block_given?
         begin
           yield self
@@ -141,30 +193,18 @@ module SQLite3
       end
     end
 
-    def type_translation= value # :nodoc:
-      warn(<<-eowarn) if $VERBOSE
-#{caller[0]} is calling `SQLite3::Database#type_translation=` which is deprecated and will be removed in version 2.0.0.
-      eowarn
-      @type_translator  = make_type_translator value
-      @type_translation = value
-    end
-    attr_reader :type_translation # :nodoc:
-
-    # Return the type translator employed by this database instance. Each
-    # database instance has its own type translator; this allows for different
-    # type handlers to be installed in each instance without affecting other
-    # instances. Furthermore, the translators are instantiated lazily, so that
-    # if a database does not use type translation, it will not be burdened by
-    # the overhead of a useless type translator. (See the Translator class.)
-    def translator
-      @translator ||= Translator.new
+    # call-seq: db.encoding
+    #
+    # Fetch the encoding set on this database
+    def encoding
+      Encoding.find super
     end
 
     # Installs (or removes) a block that will be invoked for every access
     # to the database. If the block returns 0 (or +nil+), the statement
     # is allowed to proceed. Returning 1 causes an authorization error to
     # occur, and returning 2 causes the access to be silently denied.
-    def authorizer( &block )
+    def authorizer(&block)
       self.authorizer = block
     end
 
@@ -174,7 +214,7 @@ module SQLite3
     # The Statement can then be executed using Statement#execute.
     #
     def prepare sql
-      stmt = SQLite3::Statement.new( self, sql )
+      stmt = SQLite3::Statement.new(self, sql)
       return stmt unless block_given?
 
       begin
@@ -187,7 +227,7 @@ module SQLite3
     # Returns the filename for the database named +db_name+.  +db_name+ defaults
     # to "main".  Main return `nil` or an empty string if the database is
     # temporary or in-memory.
-    def filename db_name = 'main'
+    def filename db_name = "main"
       db_filename db_name
     end
 
@@ -205,29 +245,17 @@ module SQLite3
     #
     # See also #execute2, #query, and #execute_batch for additional ways of
     # executing statements.
-    def execute sql, bind_vars = [], *args, &block
-      if bind_vars.nil? || !args.empty?
-        if args.empty?
-          bind_vars = []
-        else
-          bind_vars = [bind_vars] + args
-        end
-
-        warn(<<-eowarn) if $VERBOSE
-#{caller[0]} is calling `SQLite3::Database#execute` with nil or multiple bind params without using an array.  Please switch to passing bind parameters as an array. Support for bind parameters as *args will be removed in 2.0.0.
-        eowarn
-      end
-
-      prepare( sql ) do |stmt|
+    def execute sql, bind_vars = [], &block
+      prepare(sql) do |stmt|
         stmt.bind_params(bind_vars)
-        stmt    = ResultSet.new self, stmt
+        stmt = build_result_set stmt
 
-        if block_given?
+        if block
           stmt.each do |row|
             yield row
           end
         else
-          stmt.to_a
+          stmt.to_a.freeze
         end
       end
     end
@@ -242,15 +270,16 @@ module SQLite3
     #
     # See also #execute, #query, and #execute_batch for additional ways of
     # executing statements.
-    def execute2( sql, *bind_vars )
-      prepare( sql ) do |stmt|
-        result = stmt.execute( *bind_vars )
+    def execute2(sql, *bind_vars)
+      prepare(sql) do |stmt|
+        result = stmt.execute(*bind_vars)
         if block_given?
           yield stmt.columns
           result.each { |row| yield row }
         else
-          return result.inject( [ stmt.columns ] ) { |arr,row|
-            arr << row; arr }
+          return result.each_with_object([stmt.columns]) { |row, arr|
+                   arr << row
+                 }
         end
       end
     end
@@ -261,49 +290,28 @@ module SQLite3
     # in turn. The same bind parameters, if given, will be applied to each
     # statement.
     #
-    # This always returns +nil+, making it unsuitable for queries that return
-    # rows.
+    # This always returns the result of the last statement.
     #
     # See also #execute_batch2 for additional ways of
     # executing statements.
-    def execute_batch( sql, bind_vars = [], *args )
-      # FIXME: remove this stuff later
-      unless [Array, Hash].include?(bind_vars.class)
-        bind_vars = [bind_vars]
-        warn(<<-eowarn) if $VERBOSE
-#{caller[0]} is calling `SQLite3::Database#execute_batch` with bind parameters that are not a list of a hash.  Please switch to passing bind parameters as an array or hash. Support for this behavior will be removed in version 2.0.0.
-        eowarn
-      end
-
-      # FIXME: remove this stuff later
-      if bind_vars.nil? || !args.empty?
-        if args.empty?
-          bind_vars = []
-        else
-          bind_vars = [nil] + args
-        end
-
-        warn(<<-eowarn) if $VERBOSE
-#{caller[0]} is calling `SQLite3::Database#execute_batch` with nil or multiple bind params without using an array.  Please switch to passing bind parameters as an array. Support for this behavior will be removed in version 2.0.0.
-        eowarn
-      end
-
+    def execute_batch(sql, bind_vars = [])
       sql = sql.strip
-      until sql.empty? do
-        prepare( sql ) do |stmt|
+      result = nil
+      until sql.empty?
+        prepare(sql) do |stmt|
           unless stmt.closed?
             # FIXME: this should probably use sqlite3's api for batch execution
             # This implementation requires stepping over the results.
             if bind_vars.length == stmt.bind_parameter_count
               stmt.bind_params(bind_vars)
             end
-            stmt.step
+            result = stmt.step
           end
           sql = stmt.remainder.strip
         end
       end
-      # FIXME: we should not return `nil` as a success return value
-      nil
+
+      result
     end
 
     # Executes all SQL statements in the given string. By contrast, the other
@@ -320,7 +328,7 @@ module SQLite3
     # See also #execute_batch for additional ways of
     # executing statements.
     def execute_batch2(sql, &block)
-      if block_given?
+      if block
         result = exec_batch(sql, @results_as_hash)
         result.map do |val|
           yield val
@@ -341,21 +349,8 @@ module SQLite3
     # returned, or you could have problems with locks on the table. If called
     # with a block, +close+ will be invoked implicitly when the block
     # terminates.
-    def query( sql, bind_vars = [], *args )
-
-      if bind_vars.nil? || !args.empty?
-        if args.empty?
-          bind_vars = []
-        else
-          bind_vars = [bind_vars] + args
-        end
-
-        warn(<<-eowarn) if $VERBOSE
-#{caller[0]} is calling `SQLite3::Database#query` with nil or multiple bind params without using an array.  Please switch to passing bind parameters as an array. Support for this will be removed in version 2.0.0.
-        eowarn
-      end
-
-      result = prepare( sql ).execute( bind_vars )
+    def query(sql, bind_vars = [])
+      result = prepare(sql).execute(bind_vars)
       if block_given?
         begin
           yield result
@@ -363,7 +358,7 @@ module SQLite3
           result.close
         end
       else
-        return result
+        result
       end
     end
 
@@ -371,8 +366,8 @@ module SQLite3
     # discarding all others. It is otherwise identical to #execute.
     #
     # See also #get_first_value.
-    def get_first_row( sql, *bind_vars )
-      execute( sql, *bind_vars ).first
+    def get_first_row(sql, *bind_vars)
+      execute(sql, *bind_vars).first
     end
 
     # A convenience method for obtaining the first value of the first row of a
@@ -380,8 +375,8 @@ module SQLite3
     # identical to #execute.
     #
     # See also #get_first_row.
-    def get_first_value( sql, *bind_vars )
-      query( sql, bind_vars ) do |rs|
+    def get_first_value(sql, *bind_vars)
+      query(sql, bind_vars) do |rs|
         if (row = rs.next)
           return @results_as_hash ? row[rs.columns[0]] : row[0]
         end
@@ -389,7 +384,7 @@ module SQLite3
       nil
     end
 
-    alias :busy_timeout :busy_timeout=
+    alias_method :busy_timeout, :busy_timeout=
 
     # Creates a new function for use in SQL statements. It will be added as
     # +name+, with the given +arity+. (For variable arity functions, use
@@ -414,7 +409,7 @@ module SQLite3
     #   end
     #
     #   puts db.get_first_value( "select maim(name) from table" )
-    def create_function name, arity, text_rep=Constants::TextRep::UTF8, &block
+    def create_function name, arity, text_rep = Constants::TextRep::UTF8, &block
       define_function_with_flags(name, text_rep) do |*args|
         fp = FunctionProxy.new
         block.call(fp, *args)
@@ -459,20 +454,20 @@ module SQLite3
     #
     # See also #create_aggregate_handler for a more object-oriented approach to
     # aggregate functions.
-    def create_aggregate( name, arity, step=nil, finalize=nil,
-      text_rep=Constants::TextRep::ANY, &block )
+    def create_aggregate(name, arity, step = nil, finalize = nil,
+      text_rep = Constants::TextRep::ANY, &block)
 
       proxy = Class.new do
-        def self.step( &block )
+        def self.step(&block)
           define_method(:step_with_ctx, &block)
         end
 
-        def self.finalize( &block )
+        def self.finalize(&block)
           define_method(:finalize_with_ctx, &block)
         end
       end
 
-      if block_given?
+      if block
         proxy.instance_eval(&block)
       else
         proxy.class_eval do
@@ -498,7 +493,7 @@ module SQLite3
           @ctx = FunctionProxy.new
         end
 
-        def step( *args )
+        def step(*args)
           step_with_ctx(@ctx, *args)
         end
 
@@ -557,7 +552,7 @@ module SQLite3
     #
     #   db.create_aggregate_handler( LengthsAggregateHandler )
     #   puts db.get_first_value( "select lengths(name) from A" )
-    def create_aggregate_handler( handler )
+    def create_aggregate_handler(handler)
       # This is a compatibility shim so the (basically pointless) FunctionProxy
       # "ctx" object is passed as first argument to both step() and finalize().
       # Now its up to the library user whether he prefers to store his
@@ -571,7 +566,7 @@ module SQLite3
           @fp = FunctionProxy.new
         end
 
-        def step( *args )
+        def step(*args)
           super(@fp, *args)
         end
 
@@ -594,7 +589,7 @@ module SQLite3
     # individual instances of the aggregate function. Regular ruby objects
     # already provide a suitable +clone+.
     # The functions arity is the arity of the +step+ method.
-    def define_aggregator( name, aggregator )
+    def define_aggregator(name, aggregator)
       # Previously, this has been implemented in C. Now this is just yet
       # another compatibility shim
       proxy = Class.new do
@@ -648,9 +643,9 @@ module SQLite3
     # If a block is not given, it is the caller's responsibility to end the
     # transaction explicitly, either by calling #commit, or by calling
     # #rollback.
-    def transaction( mode = nil )
+    def transaction(mode = nil)
       mode = @default_transaction_mode if mode.nil?
-      execute "begin #{mode.to_s} transaction"
+      execute "begin #{mode} transaction"
 
       if block_given?
         abort = false
@@ -662,9 +657,9 @@ module SQLite3
         ensure
           abort and rollback or commit
         end
+      else
+        true
       end
-
-      true
     end
 
     # Commits the current transaction. If there is no current transaction,
@@ -691,6 +686,71 @@ module SQLite3
       @readonly
     end
 
+    # Sets a #busy_handler that releases the GVL between retries,
+    # but only retries up to the indicated number of +milliseconds+.
+    # This is an alternative to #busy_timeout, which holds the GVL
+    # while SQLite sleeps and retries.
+    def busy_handler_timeout=(milliseconds)
+      timeout_seconds = milliseconds.fdiv(1000)
+
+      busy_handler do |count|
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        if count.zero?
+          @timeout_deadline = now + timeout_seconds
+        elsif now > @timeout_deadline
+          next false
+        else
+          sleep(0.001)
+        end
+      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
@@ -707,54 +767,31 @@ module SQLite3
       # it is non-nil, it must quack like a Hash. If it is nil, then none of
       # the context functions will be available.
       def initialize
-        @result   = nil
-        @context  = {}
-      end
-
-      # Set the result of the function to the given error message.
-      # The function will then return that error.
-      def set_error( error )
-        @driver.result_error( @func, error.to_s, -1 )
-      end
-
-      # (Only available to aggregate functions.) Returns the number of rows
-      # that the aggregate has processed so far. This will include the current
-      # row, and so will always return at least 1.
-      def count
-        @driver.aggregate_count( @func )
+        @result = nil
+        @context = {}
       end
 
       # Returns the value with the given key from the context. This is only
       # available to aggregate functions.
-      def []( key )
-        @context[ key ]
+      def [](key)
+        @context[key]
       end
 
       # Sets the value with the given key in the context. This is only
       # available to aggregate functions.
-      def []=( key, value )
-        @context[ key ] = value
+      def []=(key, value)
+        @context[key] = value
       end
     end
 
-    # Translates a +row+ of data from the database with the given +types+
-    def translate_from_db types, row
-      @type_translator.call types, row
-    end
-
-    private
-
-    NULL_TRANSLATOR = lambda { |_, row| row }
-
-    def make_type_translator should_translate
-      if should_translate
-        lambda { |types, row|
-          types.zip(row).map do |type, value|
-            translator.translate( type, value )
-          end
-        }
+    # Given a statement, return a result set.
+    # This is not intended for general consumption
+    # :nodoc:
+    def build_result_set stmt
+      if results_as_hash
+        HashResultSet.new(self, stmt)
       else
-        NULL_TRANSLATOR
+        ResultSet.new(self, stmt)
       end
     end
   end