sqlite3 1.7.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa192827777bfe9eff54316d0310216ac32f709a52a8dab174d31ffd1e262796
-  data.tar.gz: bdd121ee85b74600e61778868665e17ef4e8b314fcdd94760d2ab408f2bbf17f
+  metadata.gz: 8a0bf66dc101ae27922443dfe78d8b876f95d94d4e1c77cef9ee94db6d4a77ba
+  data.tar.gz: 622b08d45d83da2cbad09e16340ff4aea6547f4583bb5bb82d2836fedabc62e3
 SHA512:
-  metadata.gz: eed82c398ae8eaf6d773998c8bd4162550263869aae17513d4e3274671c365dd4eb234f3a227c75dfd1a4b488c874697e1d208aee7a81ee593b8685e6ffb354b
-  data.tar.gz: 6cc96542b17c78472d648730506cb7b0ea77dc9ffb14f3b5c8fec966598b9dbb3441ba58765065e0bb8536059f50ecfed63f2f41badc2b84da3ee07a30d41418
+  metadata.gz: b065f2e43d2d0a64f74bc47d75fe71be7bfa7f39a6a58099c44fefe3f185eb84bc8f866521d8a3fcf0cea2a1dd4f98e5f4c079ee241a6c7ee124603c16561932
+  data.tar.gz: 0f42a5c3b23dd84b02fbd70f2f5bb4383056bb17be78e4356825eae3fb9afc238af782406ce8c0fc48ab0ce1557e4dcce660c2429e41224339200443846f6688

data/CHANGELOG.md

@@ -1,5 +1,157 @@
 # sqlite3-ruby Changelog
 
+## 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

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.
 

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:
-  # 1b02c58a711d15b50da8a1089e0f8807ebbdf3e674c714100eda9a03a69ac758
+  # cc1050780e0266de4d91b31c8deaf4638336908c12c21898e9f1fcae1e2ac303
   #
-  # $ sha3sum -a 256 ports/archives/sqlite-autoconf-3450200.tar.gz
-  # 1b02c58a711d15b50da8a1089e0f8807ebbdf3e674c714100eda9a03a69ac758  ports/archives/sqlite-autoconf-3450200.tar.gz
+  # $ sha3sum -a 256 ports/archives/sqlite-autoconf-3450300.tar.gz
+  # cc1050780e0266de4d91b31c8deaf4638336908c12c21898e9f1fcae1e2ac303  ports/archives/sqlite-autoconf-3450300.tar.gz
   #
-  # $ sha256sum ports/archives/sqlite-autoconf-3450200.tar.gz
-  # bc9067442eedf3dd39989b5c5cfbfff37ae66cc9c99274e0c3052dc4d4a8f6ae  ports/archives/sqlite-autoconf-3450200.tar.gz
-  :version: "3.45.2"
-  :files:
-    - :url: "https://sqlite.org/2024/sqlite-autoconf-3450200.tar.gz"
-      :sha256: "bc9067442eedf3dd39989b5c5cfbfff37ae66cc9c99274e0c3052dc4d4a8f6ae"
+  # $ sha256sum ports/archives/sqlite-autoconf-3450300.tar.gz
+  # b2809ca53124c19c60f42bf627736eae011afdcc205bb48270a5ee9a38191531  ports/archives/sqlite-autoconf-3450300.tar.gz
+  version: "3.45.3"
+  files:
+    - url: "https://sqlite.org/2024/sqlite-autoconf-3450300.tar.gz"
+      sha256: "b2809ca53124c19c60f42bf627736eae011afdcc205bb48270a5ee9a38191531"