aim-sqlite3 2.9.6.1.rc1

data/INSTALLATION.md

@@ -0,0 +1,267 @@
+
+# Installation and Using SQLite3 extensions
+
+This document will help you install the `sqlite3` ruby gem. It also contains instructions on loading database extensions and building against drop-in replacements for sqlite3.
+
+## Installation
+
+### Native Gems (recommended)
+
+In v2.5.0 and later, native (precompiled) gems are available for recent Ruby versions on these platforms:
+
+- `aarch64-linux-gnu` (requires: glibc >= 2.29)
+- `aarch64-linux-musl`
+- `arm-linux-gnu` (requires: glibc >= 2.29)
+- `arm-linux-musl`
+- `arm64-darwin`
+- `x64-mingw-ucrt`
+- `x86-linux-gnu` (requires: glibc >= 2.29)
+- `x86-linux-musl`
+- `x86_64-darwin`
+- `x86_64-linux-gnu` (requires: glibc >= 2.29)
+- `x86_64-linux-musl`
+
+⚠ 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.
+
+For example, on a linux system running Ruby 3.4:
+
+``` text
+$ ruby -v
+ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [x86_64-linux]
+
+$ time gem install sqlite3
+Fetching sqlite3-2.8.1-x86_64-linux-gnu.gem
+Successfully installed sqlite3-2.8.1-x86_64-linux-gnu
+1 gem installed
+
+real    0m1.273s
+user    0m0.496s
+sys     0m0.078s
+```
+
+#### Avoiding the precompiled native gem
+
+The maintainers strongly urge you to use a native gem if at all possible. It will be a better experience for you and allow us to focus our efforts on improving functionality rather than diagnosing installation issues.
+
+If you're on a platform that supports a native gem but you want to avoid using it in your project, do one of the following:
+
+- If you're not using Bundler, then run `gem install sqlite3 --platform=ruby`
+- If you are using Bundler
+  - version 2.3.18 or later, you can specify [`gem "sqlite3", force_ruby_platform: true`](https://bundler.io/v2.3/man/gemfile.5.html#FORCE_RUBY_PLATFORM)
+  - version 2.1 or later, then you'll need to run `bundle config set force_ruby_platform true`
+  - version 2.0 or earlier, then you'll need to run `bundle config force_ruby_platform true`
+
+
+### Compiling the source gem
+
+If you are on a platform or version of Ruby that is not covered by the Native Gems, then the vanilla "ruby platform" (non-native) gem will be installed by the `gem install` or `bundle` commands.
+
+
+#### Packaged libsqlite3
+
+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
+$ ruby -v
+ruby 2.5.9p229 (2021-04-05 revision 67939) [x86_64-linux]
+
+$ time gem install sqlite3
+Building native extensions. This could take a while...
+Successfully installed sqlite3-1.5.0
+1 gem installed
+
+real    0m20.620s
+user    0m23.361s
+sys     0m5.839s
+```
+
+##### Controlling compilation flags for sqlite
+
+Upstream sqlite allows for the setting of some parameters at compile time. If you're an expert and would like to set these, you may do so at gem install time in two different ways ...
+
+**If you're installing the gem using `gem install`** then you can pass in these compile-time flags like this:
+
+``` sh
+gem install sqlite3 --platform=ruby -- \
+  --with-sqlite-cflags="-DSQLITE_DEFAULT_CACHE_SIZE=9999 -DSQLITE_DEFAULT_PAGE_SIZE=4444"
+```
+
+or the equivalent:
+
+``` sh
+CFLAGS="-DSQLITE_DEFAULT_CACHE_SIZE=9999 -DSQLITE_DEFAULT_PAGE_SIZE=4444" \
+  gem install sqlite3 --platform=ruby
+```
+
+**If you're installing the gem using `bundler`** then you should first pin the gem to the "ruby" platform gem, so that you are compiling from source:
+
+``` ruby
+# Gemfile
+gem "sqlite3", force_ruby_platform: true # requires bundler >= 2.3.18
+```
+
+and then set up a bundler config parameter for `build.sqlite3`:
+
+``` sh
+bundle config set build.sqlite3 \
+  "--with-sqlite-cflags='-DSQLITE_DEFAULT_CACHE_SIZE=9999 -DSQLITE_DEFAULT_PAGE_SIZE=4444'"
+```
+
+NOTE the use of single quotes within the double-quoted string to ensure the space between compiler flags is interpreted correctly. The contents of your `.bundle/config` file should look like:
+
+``` yaml
+---
+BUNDLE_BUILD__SQLITE3: "--with-sqlite-cflags='-DSQLITE_DEFAULT_CACHE_SIZE=9999 -DSQLITE_DEFAULT_PAGE_SIZE=4444'"
+```
+
+
+#### System libsqlite3
+
+If you would prefer to build the sqlite3-ruby gem against your system libsqlite3, which requires that you install libsqlite3 and its development files yourself, you may do so by using the `--enable-system-libraries` flag at gem install time.
+
+PLEASE NOTE:
+
+- you must avoid installing a precompiled native gem (see [previous section](#avoiding-the-precompiled-native-gem))
+- only versions of libsqlite3 `>= 3.5.0` are supported,
+- and some library features may depend on how your libsqlite3 was compiled.
+
+For example, on a linux system running Ruby 2.5:
+
+``` text
+$ time gem install sqlite3 -- --enable-system-libraries
+Building native extensions with: '--enable-system-libraries'
+This could take a while...
+Successfully installed sqlite3-1.5.0
+1 gem installed
+
+real    0m4.234s
+user    0m3.809s
+sys     0m0.912s
+```
+
+If you're using bundler, you can opt into system libraries like this:
+
+``` sh
+bundle config build.sqlite3 --enable-system-libraries
+```
+
+If you have sqlite3 installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
+
+``` sh
+gem install sqlite3 -- \
+  --enable-system-libraries \
+  --with-sqlite3-include=/opt/local/include \
+  --with-sqlite3-lib=/opt/local/lib
+```
+
+
+#### System libsqlcipher
+
+If you'd like to link against a system-installed libsqlcipher, you may do so by using the `--with-sqlcipher` flag:
+
+``` text
+$ time gem install sqlite3 -- --with-sqlcipher
+Building native extensions with: '--with-sqlcipher'
+This could take a while...
+Successfully installed sqlite3-1.5.0
+1 gem installed
+
+real    0m4.772s
+user    0m3.906s
+sys     0m0.896s
+```
+
+If you have sqlcipher installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
+
+
+## Using SQLite3 extensions
+
+### How do I load a sqlite extension?
+
+Some add-ons are available to sqlite as "extensions". The instructions that upstream sqlite provides at https://www.sqlite.org/loadext.html are the canonical source of advice, but here's a brief example showing how you can do this with the `sqlite3` ruby gem.
+
+In this example, I'll be loading the ["spellfix" extension](https://www.sqlite.org/spellfix1.html):
+
+``` text
+# download spellfix.c from somewherehttp://www.sqlite.org/src/finfo?name=ext/misc/spellfix.c
+$ wget https://raw.githubusercontent.com/sqlite/sqlite/master/ext/misc/spellfix.c
+spellfix.c                     100%[=================================================>] 100.89K  --.-KB/s    in 0.09s
+
+# follow instructions at https://www.sqlite.org/loadext.html
+# (you will need sqlite3 development packages for this)
+$ gcc -g -fPIC -shared spellfix.c -o spellfix.o
+
+$ ls -lt
+total 192
+-rwxrwxr-x 1 flavorjones flavorjones  87984 2023-05-24 10:44 spellfix.o
+-rw-rw-r-- 1 flavorjones flavorjones 103310 2023-05-24 10:43 spellfix.c
+```
+
+Then, in your application, use that `spellfix.o` file like this:
+
+``` ruby
+require "sqlite3"
+
+db = SQLite3::Database.new(':memory:')
+db.enable_load_extension(true)
+db.load_extension("/path/to/sqlite/spellfix.o")
+db.execute("CREATE VIRTUAL TABLE demo USING spellfix1;")
+```
+
+### How do I use my own sqlite3 shared library?
+
+Some folks have strong opinions about what features they want compiled into sqlite3; or may be using a package like SQLite Encryption Extension ("SEE"). This section will explain how to get your Ruby application to load that specific shared library.
+
+If you've installed your alternative as an autotools-style installation, the directory structure will look like this:
+
+```
+/opt/sqlite3
+├── bin
+│   └── sqlite3
+├── include
+│   ├── sqlite3.h
+│   └── sqlite3ext.h
+├── lib
+│   ├── libsqlite3.a
+│   ├── libsqlite3.la
+│   ├── libsqlite3.so -> libsqlite3.so.0.8.6
+│   ├── libsqlite3.so.0 -> libsqlite3.so.0.8.6
+│   ├── libsqlite3.so.0.8.6
+│   └── pkgconfig
+│       └── sqlite3.pc
+└── share
+    └── man
+        └── man1
+            └── sqlite3.1
+```
+
+You can build this gem against that library like this:
+
+```
+gem install sqlite3 --platform=ruby -- \
+  --enable-system-libraries \
+  --with-opt-dir=/opt/sqlite
+```
+
+Explanation:
+
+- use `--platform=ruby` to avoid the precompiled native gems (see the README)
+- the `--` separates arguments passed to "gem install" from arguments passed to the C extension builder
+- use `--enable-system-libraries` to avoid the vendored sqlite3 source
+- use `--with-opt-dir=/path/to/installation` to point the build process at the desired header files and shared object files
+
+Alternatively, if you've simply downloaded an "amalgamation" and so your compiled library and header files are in arbitrary locations, try this more detailed command:
+
+```
+gem install sqlite3 --platform=ruby -- \
+  --enable-system-libraries \
+  --with-opt-include=/path/to/include \
+  --with-opt-lib=/path/to/lib
+```
+

data/LICENSE

@@ -0,0 +1,23 @@
+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:
+
+  1. Redistributions of source code must retain the above copyright notice, this list of conditions
+  and the following disclaimer.
+
+  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.
+
+  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 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

@@ -0,0 +1,218 @@
+> [!NOTE]
+> **AccountAim fork** of [sparklemotion/sqlite3-ruby](https://github.com/sparklemotion/sqlite3-ruby).
+> Our changes sit as a few commits on top of upstream `main` (`git log upstream/main..`):
+>
+> - **`statement_timeout` honors its duration.** Upstream sets the deadline to "now", so long
+>   queries are interrupted almost at once; the deadline is also cleared on `Statement#reset!`.
+> - **Queries run without the GVL.** `Statement#step` and `execute_batch2` release the GVL, so
+>   other threads keep running during long queries, and `Thread#kill` / `Thread#raise` cancel a
+>   running query through `sqlite3_interrupt`. Ruby callbacks (UDFs, aggregates, busy handler,
+>   authorizer, collations, trace) take the GVL back first. See `ext/sqlite3/gvl.c`.
+> - **Published as `aim-sqlite3`**, versioned `<upstream>.<n>` (e.g. `2.9.6.1`) and released by
+>   pushing tag `v2.9.6.1` on `main`. PR branches publish release candidates (`v2.9.6.1.rc1`,
+>   `rc2`, …) to validate in apps before merging. Precompiled for x86_64/aarch64 Linux and x86_64/arm64 macOS, with a
+>   source gem for anything else. The packaged sqlite is built with `SQLITE_MAX_ATTACHED=50`,
+>   and every gem carries the `sqlite3` program from the same build at `SQLite3.cli_path`.
+>   CI and releases use `aim-ci.yml` / `aim-release.yml`; upstream workflows are disabled in the
+>   repository settings.
+>
+> To pull in upstream: `git fetch upstream && git rebase upstream/main`.
+
+# Ruby Interface for SQLite3
+
+## Overview
+
+This library allows Ruby programs to use the SQLite3 database engine (http://www.sqlite.org).
+
+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: 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://sparklemotion.github.io/sqlite3-ruby/).
+
+A few key classes whose APIs are often-used are:
+
+- 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).
+
+
+``` ruby
+require "sqlite3"
+
+# Open a database
+db = SQLite3::Database.new "test.db"
+
+# Create a table
+rows = db.execute <<-SQL
+  create table numbers (
+    name varchar(30),
+    val int
+  );
+SQL
+
+# Execute a few inserts
+{
+  "one" => 1,
+  "two" => 2,
+}.each do |pair|
+  db.execute "insert into numbers values ( ?, ? )", pair
+end
+
+# Find a few rows
+db.execute( "select * from numbers" ) do |row|
+  p row
+end
+# => ["one", 1]
+#    ["two", 2]
+
+# Create another table with multiple columns
+db.execute <<-SQL
+  create table students (
+    name varchar(50),
+    email varchar(50),
+    grade varchar(5),
+    blog varchar(50)
+  );
+SQL
+
+# Execute inserts with parameter markers
+db.execute("INSERT INTO students (name, email, grade, blog)
+            VALUES (?, ?, ?, ?)", ["Jane", "me@janedoe.com", "A", "http://blog.janedoe.com"])
+
+db.execute( "select * from students" ) do |row|
+  p row
+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.
+
+
+## Fork Safety
+
+[Sqlite is not fork
+safe](https://www.sqlite.org/howtocorrupt.html#_carrying_an_open_database_connection_across_a_fork_)
+and instructs users to not carry an open writable database connection across a `fork()`. Using an inherited
+connection in the child may corrupt your database, leak memory, or cause other undefined behavior.
+
+To help protect users of this gem from accidental corruption due to this lack of fork safety, the gem will immediately close any open writable databases in the child after a fork. Discarding writable
+connections in the child will incur a small one-time memory leak per connection, but that's
+preferable to potentially corrupting your database.
+
+Whenever possible, close writable connections in the parent before forking. If absolutely necessary (and you know what you're doing), you may suppress the fork safety warnings by calling `SQLite3::ForkSafety.suppress_warnings!`.
+
+See [./adr/2024-09-fork-safety.md](./adr/2024-09-fork-safety.md) for more information and context.
+
+
+## Support
+
+### Installation or database extensions
+
+If you're having trouble with installation, please first read [`INSTALLATION.md`](./INSTALLATION.md).
+
+### General help requests
+
+You can ask for help or support:
+
+* by emailing the [sqlite3-ruby mailing list](http://groups.google.com/group/sqlite3-ruby)
+* by opening a [discussion thread](https://github.com/sparklemotion/sqlite3-ruby/discussions/categories/q-a) on Github
+
+### Bug reports
+
+You can file the bug at the [github issues page](https://github.com/sparklemotion/sqlite3-ruby/issues).
+
+
+## Contributing
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+
+## License
+
+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 https://www.sqlite.org/copyright.html for details.

data/dependencies.yml

@@ -0,0 +1,13 @@
+sqlite3:
+  # checksum verified by first checking the published sha3(256) checksum against https://sqlite.org/download.html:
+  # 025328da165109f48abccc6e7478508060804412bed2bd81d47e98ba1b72983b
+  #
+  # $ sha3sum -a 256 ports/archives/sqlite-autoconf-3530200.tar.gz
+  # 025328da165109f48abccc6e7478508060804412bed2bd81d47e98ba1b72983b  ports/archives/sqlite-autoconf-3530200.tar.gz
+  #
+  # $ sha256sum ports/archives/sqlite-autoconf-3530200.tar.gz
+  # 588ad51949419a56ebe81fe56193d510c559eb94c9a57748387860b5d3069316  ports/archives/sqlite-autoconf-3530200.tar.gz
+  version: "3.53.2"
+  files:
+    - url: "https://sqlite.org/2026/sqlite-autoconf-3530200.tar.gz"
+      sha256: "588ad51949419a56ebe81fe56193d510c559eb94c9a57748387860b5d3069316"