sqlite3 1.4.2 → 1.5.1

data/faq/faq.md

@@ -0,0 +1,431 @@
+
+## How do I do a database query?
+### I just want an array of the rows...
+
+Use the `Database#execute` method. If you don't give it a block, it will
+return an array of all the rows:
+
+```ruby
+  require 'sqlite3'
+
+  db = SQLite3::Database.new( "test.db" )
+  rows = db.execute( "select * from test" )
+```
+
+### I'd like to use a block to iterate through the rows...
+
+Use the `Database#execute` method. If you give it a block, each row of the
+result will be yielded to the block:
+
+
+```ruby
+  require 'sqlite3'
+
+  db = SQLite3::Database.new( "test.db" )
+  db.execute( "select * from test" ) do |row|
+    ...
+  end
+```
+
+### I need to get the column names as well as the rows...
+
+Use the `Database#execute2` method. This works just like `Database#execute`;
+if you don't give it a block, it returns an array of rows; otherwise, it
+will yield each row to the block. _However_, the first row returned is
+always an array of the column names from the query:
+
+
+```ruby
+  require 'sqlite3'
+
+  db = SQLite3::Database.new( "test.db" )
+  columns, *rows = db.execute2( "select * from test" )
+
+  # or use a block:
+
+  columns = nil
+  db.execute2( "select * from test" ) do |row|
+    if columns.nil?
+      columns = row
+    else
+      # process row
+    end
+  end
+```
+
+### I just want the first row of the result set...
+
+Easy. Just call `Database#get_first_row`:
+
+
+```ruby
+  row = db.get_first_row( "select * from table" )
+```
+
+
+This also supports bind variables, just like `Database#execute`
+and friends.
+
+### I just want the first value of the first row of the result set...
+
+Also easy. Just call `Database#get_first_value`:
+
+
+```ruby
+  count = db.get_first_value( "select count(*) from table" )
+```
+
+
+This also supports bind variables, just like `Database#execute`
+and friends.
+
+## How do I prepare a statement for repeated execution?
+
+If the same statement is going to be executed repeatedly, you can speed
+things up a bit by _preparing_ the statement. You do this via the
+`Database#prepare` method. It returns a `Statement` object, and you can
+then invoke `#execute` on that to get the `ResultSet`:
+
+
+```ruby
+  stmt = db.prepare( "select * from person" )
+
+  1000.times do
+    stmt.execute do |result|
+      ...
+    end
+  end
+
+  stmt.close
+
+  # or, use a block
+
+  db.prepare( "select * from person" ) do |stmt|
+    1000.times do
+      stmt.execute do |result|
+        ...
+      end
+    end
+  end
+```
+
+
+This is made more useful by the ability to bind variables to placeholders
+via the `Statement#bind_param` and `Statement#bind_params` methods. (See the
+next FAQ for details.)
+
+## How do I use placeholders in an SQL statement?
+    
+Placeholders in an SQL statement take any of the following formats:
+
+
+* `?`
+* `?_nnn_`
+* `:_word_`
+
+
+Where _n_ is an integer, and _word_ is an alpha-numeric identifier (or
+number). When the placeholder is associated with a number, that number
+identifies the index of the bind variable to replace it with. When it
+is an identifier, it identifies the name of the corresponding bind
+variable. (In the instance of the first format--a single question
+mark--the placeholder is assigned a number one greater than the last
+index used, or 1 if it is the first.)
+
+
+For example, here is a query using these placeholder formats:
+
+
+```sql
+  select *
+    from table
+   where ( c = ?2 or c = ? )
+     and d = :name
+     and e = :1
+```
+
+
+This defines 5 different placeholders: 1, 2, 3, and "name".
+
+
+You replace these placeholders by _binding_ them to values. This can be
+accomplished in a variety of ways.
+
+
+The `Database#execute`, and `Database#execute2` methods all accept additional
+arguments following the SQL statement. These arguments are assumed to be
+bind parameters, and they are bound (positionally) to their corresponding
+placeholders:
+
+
+```ruby
+  db.execute( "select * from table where a = ? and b = ?",
+              "hello",
+              "world" )
+```
+
+
+The above would replace the first question mark with 'hello' and the
+second with 'world'. If the placeholders have an explicit index given, they
+will be replaced with the bind parameter at that index (1-based).
+
+
+If a Hash is given as a bind parameter, then its key/value pairs are bound
+to the placeholders. This is how you bind by name:
+
+
+```ruby
+  db.execute( "select * from table where a = :name and b = :value",
+              "name" => "bob",
+              "value" => "priceless" )
+```
+
+
+You can also bind explicitly using the `Statement` object itself. Just pass
+additional parameters to the `Statement#execute` statement:
+
+
+```ruby
+  db.prepare( "select * from table where a = :name and b = ?" ) do |stmt|
+    stmt.execute "value", "name" => "bob"
+  end
+```
+
+
+Or do a `Database#prepare` to get the `Statement`, and then use either
+`Statement#bind_param` or `Statement#bind_params`:
+
+
+```ruby
+  stmt = db.prepare( "select * from table where a = :name and b = ?" )
+
+  stmt.bind_param( "name", "bob" )
+  stmt.bind_param( 1, "value" )
+
+  # or
+
+  stmt.bind_params( "value", "name" => "bob" )
+```
+
+## How do I discover metadata about a query?
+  
+If you ever want to know the names or types of the columns in a result
+set, you can do it in several ways.
+
+
+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:
+
+
+```ruby
+  rows = db.execute( "select * from table" )
+  p rows[0].fields
+  p rows[0].types
+```
+
+
+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:
+
+
+```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
+```
+
+## I'd like the rows to be indexible by column name.
+
+By default, each row from a query is returned as an `Array` of values. This
+means that you can only obtain values by their index. Sometimes, however,
+you would like to obtain values by their column name.
+
+
+The first way to do this is to set the Database property `results_as_hash`
+to true. If you do this, then all rows will be returned as Hash objects,
+with the column names as the keys. (In this case, the `fields` property
+is unavailable on the row, although the "types" property remains.)
+
+
+```ruby
+  db.results_as_hash = true
+  db.execute( "select * from table" ) do |row|
+    p row['column1']
+    p row['column2']
+  end
+```
+
+
+The other 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!
+
+
+```ruby
+  require 'arrayfields'
+
+  ...
+  db.execute( "select * from table" ) do |row|
+    p row[0] == row['column1']
+    p row[1] == row['column2']
+  end
+```
+
+## I'd like the values from a query to be the correct types, instead of String.
+    
+You can turn on "type translation" by setting `Database#type_translation` to
+true:
+
+
+```ruby
+  db.type_translation = true
+  db.execute( "select * from table" ) do |row|
+    p row
+  end
+```
+
+
+By doing this, each return value for each row will be translated to its
+correct type, based on its declared column type.
+
+
+You can even declare your own translation routines, if (for example) you are
+using an SQL type that is not handled by default:
+
+
+```ruby
+  # assume "objects" table has the following schema:
+  #   create table objects (
+  #     name varchar2(20),
+  #     thing object
+  #   )
+
+  db.type_translation = true
+  db.translator.add_translator( "object" ) do |type, value|
+    db.decode( value )
+  end
+
+  h = { :one=>:two, "three"=>"four", 5=>6 }
+  dump = db.encode( h )
+
+  db.execute( "insert into objects values ( ?, ? )", "bob", dump )
+
+  obj = db.get_first_value( "select thing from objects where name='bob'" )
+  p obj == h
+```
+
+## How do I insert binary data into the database?
+
+Use blobs. Blobs are new features of SQLite3. You have to use bind
+variables to make it work:
+
+
+```ruby
+  db.execute( "insert into foo ( ?, ? )",
+    SQLite3::Blob.new( "\0\1\2\3\4\5" ),
+    SQLite3::Blob.new( "a\0b\0c\0d ) )
+```
+
+
+The blob values must be indicated explicitly by binding each parameter to
+a value of type `SQLite3::Blob`.
+
+## How do I do a DDL (insert, update, delete) statement?
+
+You can actually do inserts, updates, and deletes in exactly the same way
+as selects, but in general the `Database#execute` method will be most
+convenient:
+
+
+```ruby
+  db.execute( "insert into table values ( ?, ? )", *bind_vars )
+```
+
+## How do I execute multiple statements in a single string?
+    
+The standard query methods (`Database#execute`, `Database#execute2`,
+`Database#query`, and `Statement#execute`) will only execute the first
+statement in the string that is given to them. Thus, if you have a
+string with multiple SQL statements, each separated by a string,
+you can't use those methods to execute them all at once.
+
+
+Instead, use `Database#execute_batch`:
+
+
+```ruby
+  sql = <<SQL
+    create table the_table (
+      a varchar2(30),
+      b varchar2(30)
+    );
+
+    insert into the_table values ( 'one', 'two' );
+    insert into the_table values ( 'three', 'four' );
+    insert into the_table values ( 'five', 'six' );
+  SQL
+
+  db.execute_batch( sql )
+```
+
+
+Unlike the other query methods, `Database#execute_batch` accepts no
+block. It will also only ever return `nil`. Thus, it is really only
+suitable for batch processing of DDL statements.
+
+## How do I begin/end a transaction
+    
+Use `Database#transaction` to start a transaction. If you give it a block,
+the block will be automatically committed at the end of the block,
+unless an exception was raised, in which case the transaction will be
+rolled back. (Never explicitly call `Database#commit` or `Database#rollback`
+inside of a transaction block--you'll get errors when the block
+terminates!)
+
+
+```ruby
+  database.transaction do |db|
+    db.execute( "insert into table values ( 'a', 'b', 'c' )" )
+    ...
+  end
+```
+
+
+Alternatively, if you don't give a block to `Database#transaction`, the
+transaction remains open until you explicitly call `Database#commit` or
+`Database#rollback`.
+
+
+```ruby
+  db.transaction
+  db.execute( "insert into table values ( 'a', 'b', 'c' )" )
+  db.commit
+```
+
+
+Note that SQLite does not allow nested transactions, so you'll get errors
+if you try to open a new transaction while one is already active. Use
+`Database#transaction_active?` to determine whether a transaction is
+active or not.
+
+## How do I discover metadata about a table/index?
+
+## How do I do tweak database settings?

data/faq/faq.yml

@@ -128,7 +128,7 @@
     Where _n_ is an integer, and _word_ is an alpha-numeric identifier (or
     number). When the placeholder is associated with a number, that number
     identifies the index of the bind variable to replace it with. When it
-    is an identifier, it identifies the name of the correponding bind
+    is an identifier, it identifies the name of the corresponding bind
     variable. (In the instance of the first format--a single question
     mark--the placeholder is assigned a number one greater than the last
     index used, or 1 if it is the first.)

data/lib/sqlite3/constants.rb

@@ -37,7 +37,7 @@ module SQLite3 ; module Constants
     EMPTY      = 16   # (Internal Only) Database table is empty
     SCHEMA     = 17   # The database schema changed
     TOOBIG     = 18   # Too much data for one row of a table
-    CONSTRAINT = 19   # Abort due to contraint violation
+    CONSTRAINT = 19   # Abort due to constraint violation
     MISMATCH   = 20   # Data type mismatch
     MISUSE     = 21   # Library used incorrectly
     NOLFS      = 22   # Uses OS features not supported on host

data/lib/sqlite3/database.rb

@@ -65,6 +65,7 @@ module SQLite3
     def initialize file, options = {}, zvfs = nil
       mode = Constants::Open::READWRITE | Constants::Open::CREATE
 
+      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
       else
@@ -87,6 +88,10 @@ module SQLite3
         end
 
         open_v2 file.encode("utf-8"), mode, zvfs
+
+        if options[:strict]
+          disable_quirk_mode
+        end
       end
 
       @tracefunc        = nil
@@ -237,7 +242,7 @@ Support for bind parameters as *args will be removed in 2.0.0.
     # rows.
     #
     # See also #execute_batch2 for additional ways of
-    # executing statments.
+    # executing statements.
     def execute_batch( sql, bind_vars = [], *args )
       # FIXME: remove this stuff later
       unless [Array, Hash].include?(bind_vars.class)
@@ -294,7 +299,7 @@ Support for this behavior will be removed in version 2.0.0.
     # a block can be passed to parse the values accordingly.
     #
     # See also #execute_batch for additional ways of
-    # executing statments.
+    # executing statements.
     def execute_batch2(sql, &block)
       if block_given?
         result = exec_batch(sql, @results_as_hash)
@@ -307,7 +312,7 @@ Support for this behavior will be removed in version 2.0.0.
     end
 
     # This is a convenience method for creating a statement, binding
-    # paramters to it, and calling execute:
+    # parameters to it, and calling execute:
     #
     #   result = db.query( "select * from foo where a=?", [5])
     #   # is the same as
@@ -536,10 +541,10 @@ Support for this will be removed in version 2.0.0.
     #   db.create_aggregate_handler( LengthsAggregateHandler )
     #   puts db.get_first_value( "select lengths(name) from A" )
     def create_aggregate_handler( handler )
-      # This is a compatiblity shim so the (basically pointless) FunctionProxy
+      # 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
-      # temporaries as instance varibales or fields in the FunctionProxy.
+      # temporaries as instance variables or fields in the FunctionProxy.
       # The library user still must set the result value with
       # FunctionProxy.result= as there is no backwards compatible way to
       # change this.
@@ -574,7 +579,7 @@ Support for this will be removed in version 2.0.0.
     # The functions arity is the arity of the +step+ method.
     def define_aggregator( name, aggregator )
       # Previously, this has been implemented in C. Now this is just yet
-      # another compatiblity shim
+      # another compatibility shim
       proxy = Class.new do
         @template = aggregator
         @name = name

data/lib/sqlite3/pragmas.rb

@@ -42,11 +42,11 @@ module SQLite3
     # Requests the given pragma (and parameters), and if the block is given,
     # each row of the result set will be yielded to it. Otherwise, the results
     # are returned as an array.
-    def get_query_pragma( name, *parms, &block ) # :yields: row
-      if parms.empty?
+    def get_query_pragma( name, *params, &block ) # :yields: row
+      if params.empty?
         execute( "PRAGMA #{name}", &block )
       else
-        args = "'" + parms.join("','") + "'"
+        args = "'" + params.join("','") + "'"
         execute( "PRAGMA #{name}( #{args} )", &block )
       end
     end
@@ -543,6 +543,13 @@ module SQLite3
 
         tweak_default(new_row) if needs_tweak_default
 
+        # Ensure the type value is downcased.  On Mac and Windows
+        # platforms this value is now being returned as all upper
+        # case.
+        if new_row['type']
+          new_row['type'] = new_row['type'].downcase
+        end
+
         if block_given?
           yield new_row
         else

data/lib/sqlite3/statement.rb

@@ -137,7 +137,8 @@ module SQLite3
         column_name column
       end
       @types = Array.new(column_count) do |column|
-        column_decltype column
+        val = column_decltype(column)
+        val.nil? ? nil : val.downcase
       end
     end
   end

data/lib/sqlite3/translator.rb

@@ -43,7 +43,7 @@ Built in translators are deprecated and will be removed in version 2.0.0
     end
 
     # Translate the given string value to a value of the given type. In the
-    # absense of an installed translator block for the given type, the value
+    # absence of an installed translator block for the given type, the value
     # itself is always returned. Further, +nil+ values are never translated,
     # and are always passed straight through regardless of the type parameter.
     def translate( type, value )

data/lib/sqlite3/version.rb

@@ -1,16 +1,14 @@
 module SQLite3
 
-  VERSION = '1.4.2'
+  VERSION = "1.5.1"
 
   module VersionProxy
-
     MAJOR = 1
-    MINOR = 4
-    TINY  = 2
+    MINOR = 5
+    TINY  = 1
     BUILD = nil
 
     STRING = [ MAJOR, MINOR, TINY, BUILD ].compact.join( "." )
-    #:beta-tag:
 
     VERSION = ::SQLite3::VERSION
   end

data/test/helper.rb

@@ -1,6 +1,15 @@
 require 'sqlite3'
 require 'minitest/autorun'
 
+if ENV['GITHUB_ACTIONS'] == 'true' || ENV['CI']
+  $VERBOSE = nil
+end
+
+puts "info: sqlite3-ruby version: #{SQLite3::VERSION}/#{SQLite3::VersionProxy::STRING}"
+puts "info: sqlite3 version: #{SQLite3::SQLITE_VERSION}/#{SQLite3::SQLITE_LOADED_VERSION}"
+puts "info: sqlcipher?: #{SQLite3.sqlcipher?}"
+puts "info: threadsafe?: #{SQLite3.threadsafe?}"
+
 unless RUBY_VERSION >= "1.9"
   require 'iconv'
 end

data/test/test_database.rb

@@ -20,7 +20,7 @@ module SQLite3
       assert_equal '', @db.filename('main')
       tf = Tempfile.new 'thing'
       @db = SQLite3::Database.new tf.path
-      assert_equal File.expand_path(tf.path), File.expand_path(@db.filename('main'))
+      assert_equal File.realdirpath(tf.path), File.realdirpath(@db.filename('main'))
     ensure
       tf.unlink if tf
     end
@@ -30,7 +30,7 @@ module SQLite3
       assert_equal '', @db.filename
       tf = Tempfile.new 'thing'
       @db = SQLite3::Database.new tf.path
-      assert_equal File.expand_path(tf.path), File.expand_path(@db.filename)
+      assert_equal File.realdirpath(tf.path), File.realdirpath(@db.filename)
     ensure
       tf.unlink if tf
     end
@@ -40,11 +40,23 @@ module SQLite3
       assert_equal '', @db.filename
       tf = Tempfile.new 'thing'
       @db.execute "ATTACH DATABASE '#{tf.path}' AS 'testing'"
-      assert_equal File.expand_path(tf.path), File.expand_path(@db.filename('testing'))
+
+      assert_equal File.realdirpath(tf.path), File.realdirpath(@db.filename('testing'))
     ensure
       tf.unlink if tf
     end
 
+
+    def test_filename_to_path
+      tf = Tempfile.new 'thing'
+      pn = Pathname tf.path
+      db = SQLite3::Database.new pn
+      assert_equal pn.realdirpath.to_s, File.realdirpath(db.filename)
+    ensure
+      tf.close! if tf
+    end
+
+
     def test_error_code
       begin
         db.execute 'SELECT'
@@ -349,7 +361,10 @@ module SQLite3
         nil
       end
       @db.execute("select hello(2.2, 'foo', NULL)")
-      assert_equal [2.2, 'foo', nil], called_with
+
+      assert_in_delta(2.2, called_with[0], 0.0001)
+      assert_equal("foo", called_with[1])
+      assert_nil(called_with[2])
     end
 
     def test_define_varargs
@@ -359,7 +374,10 @@ module SQLite3
         nil
       end
       @db.execute("select hello(2.2, 'foo', NULL)")
-      assert_equal [2.2, 'foo', nil], called_with
+
+      assert_in_delta(2.2, called_with[0], 0.0001)
+      assert_equal("foo", called_with[1])
+      assert_nil(called_with[2])
     end
 
     def test_call_func_blob
@@ -499,5 +517,29 @@ module SQLite3
     def test_execute_with_named_bind_params
       assert_equal [['foo']], @db.execute("select :n", {'n' => 'foo'})
     end
+
+    def test_strict_mode
+      unless Gem::Requirement.new(">= 3.29.0").satisfied_by?(Gem::Version.new(SQLite3::SQLITE_VERSION))
+        skip("strict mode feature not available in #{SQLite3::SQLITE_VERSION}")
+      end
+
+      db = SQLite3::Database.new(':memory:')
+      db.execute('create table numbers (val int);')
+      db.execute('create index index_numbers_nope ON numbers ("nope");') # nothing raised
+
+      db = SQLite3::Database.new(':memory:', :strict => true)
+      db.execute('create table numbers (val int);')
+      error = assert_raises SQLite3::SQLException do
+        db.execute('create index index_numbers_nope ON numbers ("nope");')
+      end
+      assert_includes error.message, "no such column: nope"
+    end
+
+    def test_load_extension_with_nonstring_argument
+      db = SQLite3::Database.new(':memory:')
+      skip("extensions are not enabled") unless db.respond_to?(:load_extension)
+      assert_raises(TypeError) { db.load_extension(1) }
+      assert_raises(TypeError) { db.load_extension(Pathname.new("foo.so")) }
+    end
   end
 end