sqlite3 1.7.1 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29f918d3ca102b856248a3c33ffa077b46f394aa548a26f69c7dd7ac5bc63d1c
-  data.tar.gz: 676cc3802634e743b601717c6fbcf6c89bd269d58edfd45a65590f1667193c93
+  metadata.gz: f55003062c0de8516574697a3a8aa323c0ec16265c6fea50ab51012447ea3751
+  data.tar.gz: 4c176a14ff9f12850b9f2cb5ebc1b7141127076a25d7ce75fd36aa14514a5b98
 SHA512:
-  metadata.gz: 5b764f248fe028c26968325e744b8d638b7491e1e960ec4791bc010c2a1b1d2a90874b3bc73b43fb593d4ef3236508cb90665d232226191e9002cd3e784d04a8
-  data.tar.gz: '069640c56388fa759a879d79c3c4ac91c194ec8e312b89aad2659f74255d69ea0b870e17c5b4d164a76ef5df5af07a0e29e9243758ad68333dbddb1d33cd5cf8'
+  metadata.gz: a7f2b0891c6480a9cf2731ac8712cedcf15ffab08f2d2a68967cb9e1afc2a33e7d7501050d2056de74a069f65ae113e2e8bf195edb7f28dc010f8b6e70c2d795
+  data.tar.gz: aad1f26e943b7dd01543f86682b36a0f319fab42446501f747f2add4825d767eacf4efcb4f32d652e306d4ecd41ab2d4556501b7b3072361d9276fa99023a6d8

data/CHANGELOG.md

@@ -1,10 +1,191 @@
 # sqlite3-ruby Changelog
 
+## 2.0.2 / 2024-05-23
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.46.0](https://sqlite.org/releaselog/3_46_0.html) @flavorjones
+
+
+## 2.0.1 / 2024-04-20
+
+### Fixed
+
+- Raise `ArgumentError` if `Database#execute`, `#execute_batch`, or `#query` are passed multiple bind parameters that are not in an Array. In v2.0.0 these methods would silently swallow additional arguments, and this change makes the failure explicit. See the CHANGELOG notes for v2.0.0 for examples on how to update your code. [#527] @flavorjones
+- Fixed a regression in v2.0.0 that caused `Database#execute_batch` to raise an encoding exception when passed some non-ascii strings. As a result of this fix, `Database#prepare` now ensures the "remainder" string will always be encoded as UTF-8. [#524] @flavorjones
+
+
+## 2.0.0 / 2024-04-17
+
+This is a major release which contains some breaking changes, primarily the removal of
+long-deprecated functionality. Before upgrading, please make sure to address deprecation warnings
+emitted from your application using sqlite3-ruby v1.7.x.
+
+
+### Ruby
+
+- This release drops support for Ruby 2.7. [#453] @flavorjones
+
+
+### Packaging
+
+Native (precompiled) gems are now available for Linux Musl. [#442] @flavorjones
+
+Here are the platforms for which native gems are shipped:
+
+- `aarch64-linux-gnu` (requires: glibc >= 2.29)
+- `aarch64-linux-musl`
+- `arm-linux-gnu` (requires: glibc >= 2.29)
+- `arm-linux-musl`
+- `arm64-darwin`
+- `x64-mingw32` / `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
+
+See [the INSTALLATION doc](https://github.com/sparklemotion/sqlite3-ruby/blob/main/INSTALLATION.md) for more information.
+
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.45.3](https://sqlite.org/releaselog/3_45_3.html). @flavorjones
+
+
+### Added
+
+- `Database#busy_handler_timeout=` introduced as an alternative to `#busy_timeout=` that can be used when it's desired to release the GVL between retries. [#443, #456] @fractaledmind
+- Support the `SUPER_JOURNAL` flag which is an alias for `MASTER_JOURNAL` as of sqlite 3.33.0. [#467] @flavorjones
+- `Statement#stat` and `Statement#memused` introduced to report statistics. [#461] @fractaledmind
+- `Statement#sql` and `Statement#expanded_sql` introduced to retrieve the SQL statement associated with the `Statement` object. [#293, #498] @tenderlove
+- `SQLite3.status` introduced to return run-time status and reset high-water marks. See `SQLite3::Constants::Status` for details. [#520] @wjlroe
+
+
+### Improved
+
+- Avoid leaking memory for statements that are not closed properly. [#392] @haileys
+- Moved some C code into Ruby. [#451, #455] @tenderlove
+- Improve performance of `ResultSet` hashes. [#154, #484, #468] @tenderlove
+- Fix a GC compaction issue with `busy_handler`. [#466] @byroot
+- Remove unused `ResultSet` instance variable. [#469] @tenderlove
+- Fix encoding for values passed to custom functions. [#218, #488] @tenderlove
+
+
+### Changed
+
+- Consistently use `SQLite3::Exception` or subclasses. Previously some `Pragmas` methods raised `Exception`, and `Database#execute_batch2` and `Database#load_extension` raised `RuntimeError`. [#467, #490] @flavorjones
+- `Database#columns` returns a list of internal frozen strings. [#155, #474, #486] @tenderlove
+- Freeze results that come from the database. [#480] @tenderlove
+- The encoding of a Database is no longer cached. [#485] @tenderlove
+- `Database#transaction` returns the result of the block when used with a block. [#508] @alexcwatt
+- `Database#execute_batch` returns the result of the last statement executed. [#512] @alexcwatt
+
+
+### Removed
+
+- Removed class `SQLite3::Translator` and all related type translation methods which have been deprecated since v1.3.2. [#470] @tenderlove
+
+  If you need to do type translation on values returned from the statement object, please wrap it
+  with a delegate object.  Here is an example of using a delegate class to implement type
+  translation:
+
+  ```ruby
+  require "sqlite3"
+  require "delegate"
+
+  db = SQLite3::Database.new(":memory:")
+
+  return_value = db.execute_batch2 <<-EOSQL
+          CREATE TABLE items (id integer PRIMARY KEY AUTOINCREMENT, name string);
+          INSERT INTO items (name) VALUES ("foo");
+          INSERT INTO items (name) VALUES ("bar");
+  EOSQL
+
+  class MyTranslator < DelegateClass(SQLite3::Statement)
+    def step
+      row = super
+      return if done?
+
+      row.map.with_index do |item, i|
+        case types[i]
+        when "integer" # turn all integers to floats
+          item.to_f
+        when "string" # add "hello" to all strings
+          item + "hello"
+        end
+      end
+    end
+  end
+
+  db.prepare("SELECT * FROM items") do |stmt|
+    stmt = MyTranslator.new(stmt)
+    while row = stmt.step
+      p row
+    end
+  end
+  ```
+
+- Removed `types` and `fields` readers on row objects, which have been deprecated since
+  v1.3.6. [#471] @tenderlove
+
+  Deprecated code looks like this:
+
+  ```ruby
+  row = @db.execute("select * from foo")
+  assert_equal ["blob"], row.first.types
+  ```
+
+  If you would like to access the "types" associated with a returned query,
+  use a prepared statement like this:
+
+  ```ruby
+  @db.prepare("select * from foo") do |v|
+    assert_equal ["blob"], v.types
+  end
+  ```
+
+- Removed support for non-Array bind parameters to methods `Database#execute`, `#execute_batch`, and `#query`, which has been deprecated since v1.3.0. [#511] @flavorjones
+
+  Deprecated code looks like this:
+
+  ``` ruby
+  @db.query("select * from foo where a = ? and b = ? and c = ?", 1, 2, 3)
+  ```
+
+  For these cases, pass the bind parameters as an array:
+
+  ``` ruby
+  @db.query("select * from foo where a = ? and b = ? and c = ?", [1, 2, 3])
+  ```
+
+- Removed class `SQLite3::VersionProxy` which has been deprecated since v1.3.2. [#453] @flavorjones
+- Removed methods `SQLite3::Database::FunctionProxy#count` and `#set_error` which have been broken since at least v1.3.13. [#164, #509, #510] @alexcwatt @flavorjones
+
+
+## 1.7.3 / 2024-03-15
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.45.2](https://www.sqlite.org/releaselog/3_45_2.html). @flavorjones
+
+
+## 1.7.2 / 2024-01-30
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.45.1](https://www.sqlite.org/releaselog/3_45_1.html). @flavorjones
+
+
 ## 1.7.1 / 2024-01-24
 
 ### Dependencies
 
-- Vendored sqlite is update to [v3.45.0](https://www.sqlite.org/releaselog/3_45_0.html). @flavorjones
+- Vendored sqlite is updated to [v3.45.0](https://www.sqlite.org/releaselog/3_45_0.html). @flavorjones
 
 
 ## 1.7.0 / 2023-12-27

data/CONTRIBUTING.md

@@ -5,6 +5,28 @@
 This doc is a short introduction on how to modify and maintain the sqlite3-ruby gem.
 
 
+## Architecture notes
+
+### 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
+
+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.
+
+
+
 ## Building gems
 
 As a prerequisite please make sure you have `docker` correctly installed, so that you're able to cross-compile the native gems.
@@ -26,7 +48,7 @@ Update `/dependencies.yml` to reflect:
 A quick checklist:
 
 - [ ] make sure CI is green!
-- [ ] update `CHANGELOG.md` and `lib/sqlite3/version.rb` including `VersionProxy::{MINOR,TINY}`
+- [ ] update `CHANGELOG.md` and `lib/sqlite3/version.rb`
 - [ ] run `bin/build-gems` and make sure it completes and all the tests pass
 - [ ] create a git tag using a format that matches the pattern `v\d+\.\d+\.\d+`, e.g. `v1.3.13`
 - [ ] `git push && git push --tags`

data/FAQ.md

@@ -289,49 +289,6 @@ by column name, even though they are still arrays!
   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

data/INSTALLATION.md

@@ -7,15 +7,23 @@ This document will help you install the `sqlite3` ruby gem. It also contains ins
 
 ### Native Gems (recommended)
 
-In v1.5.0 and later, native (precompiled) gems are available for recent Ruby versions on these platforms:
+In v2.0.0 and later, native (precompiled) gems are available for recent Ruby versions on these platforms:
 
-- `aarch64-linux` (requires: glibc >= 2.29)
-- `arm-linux` (requires: glibc >= 2.29)
+- `aarch64-linux-gnu` (requires: glibc >= 2.29)
+- `aarch64-linux-musl`
+- `arm-linux-gnu` (requires: glibc >= 2.29)
+- `arm-linux-musl`
 - `arm64-darwin`
 - `x64-mingw32` / `x64-mingw-ucrt`
-- `x86-linux` (requires: glibc >= 2.17)
+- `x86-linux-gnu` (requires: glibc >= 2.17)
+- `x86-linux-musl`
 - `x86_64-darwin`
-- `x86_64-linux` (requires: glibc >= 2.17)
+- `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.
 
@@ -57,6 +65,8 @@ If you are on a platform or version of Ruby that is not covered by the Native Ge
 
 By default, as of v1.5.0 of this library, the latest available version of libsqlite3 is packaged with the gem and will be compiled and used automatically. This takes a bit longer than the native gem, but will provide a modern, well-supported version of libsqlite3.
 
+⚠ A prerequisite to build the gem with the packaged sqlite3 is that you must have `pkgconf` installed.
+
 For example, on a linux system running Ruby 2.5:
 
 ``` text

data/LICENSE

@@ -1,27 +1,23 @@
-Copyright (c) 2004, Jamis Buck (jamis@jamisbuck.org)
-All rights reserved.
+Copyright (c) 2004-2024, Jamis Buck, Luis Lavena, Aaron Patterson, Mike Dalessio, et al.
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+Redistribution and use in source and binary forms, with or without modification, are permitted
+provided that the following conditions are met:
 
-    * Redistributions of source code must retain the above copyright notice,
-      this list of conditions and the following disclaimer.
+  1. Redistributions of source code must retain the above copyright notice, this list of conditions
+  and the following disclaimer.
 
-    * Redistributions in binary form must reproduce the above copyright
-      notice, this list of conditions and the following disclaimer in the
-      documentation and/or other materials provided with the distribution.
+  2. Redistributions in binary form must reproduce the above copyright notice, this list of
+  conditions and the following disclaimer in the documentation and/or other materials provided with
+  the distribution.
 
-    * The names of its contributors may not be used to endorse or promote
-      products derived from this software without specific prior written
-      permission.
+  3. Neither the name of the copyright holder nor the names of its contributors may be used to
+  endorse or promote products derived from this software without specific prior written permission.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -11,8 +11,7 @@ Note that this module is only compatible with SQLite 3.6.16 or newer.
 * Download: http://rubygems.org/gems/sqlite3
 * Documentation: http://www.rubydoc.info/gems/sqlite3
 
-[![Unit tests](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/sqlite3-ruby.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/sqlite3-ruby.yml)
-[![Native packages](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml)
+[![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
@@ -77,6 +76,78 @@ end
 # => ["Jane", "me@janedoe.com", "A", "http://blog.janedoe.com"]
 ```
 
+## Thread Safety
+
+When `SQLite3.threadsafe?` returns `true`, then SQLite3 has been compiled to
+support running in a multithreaded environment.  However, this doesn't mean
+that all classes in the SQLite3 gem can be considered "thread safe".
+
+When `SQLite3.threadsafe?` returns `true`, it is safe to share only
+`SQLite3::Database` instances among threads without providing your own locking
+mechanism.  For example, the following code is fine because only the database
+instance is shared among threads:
+
+```ruby
+require 'sqlite3'
+
+db = SQLite3::Database.new ":memory:"
+
+latch = Queue.new
+
+ts = 10.times.map {
+  Thread.new {
+    latch.pop
+    db.execute "SELECT '#{Thread.current.inspect}'"
+  }
+}
+10.times { latch << nil }
+
+p ts.map(&:value)
+```
+
+Other instances can be shared among threads, but they require that you provide
+your own locking for thread safety.  For example, `SQLite3::Statement` objects
+(prepared statements) are mutable, so applications must take care to add
+appropriate locks to avoid data race conditions when sharing these objects
+among threads.
+
+Lets rewrite the above example but use a prepared statement and safely share
+the prepared statement among threads:
+
+```ruby
+db = SQLite3::Database.new ":memory:"
+
+# Prepare a statement
+stmt = db.prepare "SELECT :inspect"
+stmt_lock = Mutex.new
+
+latch = Queue.new
+
+ts = 10.times.map {
+  Thread.new {
+    latch.pop
+
+    # Add a lock when using the prepared statement.
+    # Binding values, and walking over results will mutate the statement, so
+    # in order to prevent other threads from "seeing" this thread's data, we
+    # must lock when using the statement object
+    stmt_lock.synchronize do
+      stmt.execute(Thread.current.inspect).to_a
+    end
+  }
+}
+
+10.times { latch << nil }
+
+p ts.map(&:value)
+
+stmt.close
+```
+
+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.
+
 ## Support
 
 ### Installation or database extensions
@@ -104,7 +175,7 @@ See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 
 This library is licensed under `BSD-3-Clause`, see [`LICENSE`](./LICENSE).
 
-
 ### Dependencies
 
-The source code of `sqlite` is distributed in the "ruby platform" gem. This code is public domain, see [`LICENSE-DEPENDENCIES`](./LICENSE-DEPENDENCIES) for details.
+The source code of `sqlite` is distributed in the "ruby platform" gem. This code is public domain,
+see https://www.sqlite.org/copyright.html for details.

data/dependencies.yml

@@ -1,14 +1,13 @@
-# TODO: stop using symbols here once we no longer support Ruby 2.7 and can rely on symbolize_names
-:sqlite3:
+sqlite3:
   # checksum verified by first checking the published sha3(256) checksum against https://sqlite.org/download.html:
-  # 9fc2a78088875ae7c112957d58ccc52b1a0a4afa34ac669290be42f352b1aa76
+  # 83d2acf79453deb7d6520338b1f4585f12e39b27cd370fb08593afa198f471fc
   #
-  # $ sha3sum -a 256 ports/archives/sqlite-autoconf-3450000.tar.gz
-  # 9fc2a78088875ae7c112957d58ccc52b1a0a4afa34ac669290be42f352b1aa76  ports/archives/sqlite-autoconf-3450000.tar.gz
+  # $ sha3sum -a 256 ports/archives/sqlite-autoconf-3460000.tar.gz
+  # 83d2acf79453deb7d6520338b1f4585f12e39b27cd370fb08593afa198f471fc  ports/archives/sqlite-autoconf-3460000.tar.gz
   #
-  # $ sha256sum ports/archives/sqlite-autoconf-3450000.tar.gz
-  # 72887d57a1d8f89f52be38ef84a6353ce8c3ed55ada7864eb944abd9a495e436  ports/archives/sqlite-autoconf-3450000.tar.gz
-  :version: "3.45.0"
-  :files:
-    - :url: "https://sqlite.org/2024/sqlite-autoconf-3450000.tar.gz"
-      :sha256: "72887d57a1d8f89f52be38ef84a6353ce8c3ed55ada7864eb944abd9a495e436"
+  # $ sha256sum ports/archives/sqlite-autoconf-3460000.tar.gz
+  # 6f8e6a7b335273748816f9b3b62bbdc372a889de8782d7f048c653a447417a7d  ports/archives/sqlite-autoconf-3460000.tar.gz
+  version: "3.46.0"
+  files:
+    - url: "https://sqlite.org/2024/sqlite-autoconf-3460000.tar.gz"
+      sha256: "6f8e6a7b335273748816f9b3b62bbdc372a889de8782d7f048c653a447417a7d"