sqlite3 1.7.3-aarch64-linux → 2.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 837bb496b0c150e3ed8e21e5c0f56366ca4a45e9cfa492f27ee3b21ecadcdbd4
-  data.tar.gz: c313e8711ef29344f2e022fadc38184abd14b9af51d8e7b18888736f94558fcd
+  metadata.gz: d07346cdcb69a6187d144247aefa90dbf7b2966513f94643e20baa18dd38fbbf
+  data.tar.gz: e1c7385c0d16942a8b3b9fc4976b486e1b1fed18524975e0d53a608d542a2943
 SHA512:
-  metadata.gz: 36533b4e40b0498e7fb0e5d3003ca11b61c142d2c5e91017f6e1c3de659b475d680329f7a84af2fabcd620578c675da726657b4aacac093a785dcdc4333d62d6
-  data.tar.gz: 80031abfa246e43c49bb24cf0e81339f4984382c005fdf8340d78d652e83a09aeb1b0acfa8be21dfa0888d080e062d7bcd677dc574fee717922636daec43c8f2
+  metadata.gz: 0e95401b70a9780e5e5a1903e3b9cf3d0aa588e75c89db0211642918d83305132b06ab169ee519633d507fc27a1d6674e344162acae905c8fe14478850a3b3cf
+  data.tar.gz: ab4fb4b3a3b7dba95cbb0e7cbb893c9223de6f5ca82469ac68f35f6b89293bc2ba8292cd5d561cfb245e038769880b60edb6a4896a4b9072305661dda2f9e999

data/CHANGELOG.md

@@ -1,5 +1,398 @@
 # sqlite3-ruby Changelog
 
+## 2.9.5 / 2026-06-07
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.53.2](https://www.sqlite.org/releaselog/3_53_3.html) (from v3.53.1). #709 @flavorjones
+
+### Security / Stability
+
+- Fix use-after-free issue with custom functions, when the same function name is used with multiple arities. See https://github.com/sparklemotion/sqlite3-ruby/security/advisories/GHSA-28hh-pr2h-2w89 for more information. #710 @flavorjones
+- Fix use-after-free issue with aggregate functions, if a statement is used after a soft database close. See https://github.com/sparklemotion/sqlite3-ruby/security/advisories/GHSA-j7fr-3v8c-3qc3 for more information. #711 @flavorjones
+
+
+## 2.9.4 / 2026-05-05
+
+- Vendored sqlite is updated to [v3.53.1](https://www.sqlite.org/releaselog/3_53_1.html) (from v3.53.0). #704 @flavorjones
+
+
+## 2.9.3 / 2026-04-15
+
+- Vendored sqlite is updated to [v3.53.0](https://www.sqlite.org/releaselog/3_53_0.html) (from v3.51.3). #696 @flavorjones
+
+
+## 2.9.2 / 2026-03-15
+
+- Vendored sqlite is updated to [v3.51.3](https://www.sqlite.org/releaselog/3_51_3.html) (from v3.51.2). #688 @flavorjones
+
+
+## 2.9.1 / 2026-02-28
+
+- Vendored sqlite is updated to [v3.51.2](https://www.sqlite.org/releaselog/3_51_2.html) (from v3.51.1). #683 @flavorjones
+
+## 2.9.0 / 2025-12-27
+
+### Ruby
+
+- Introduce native gem packages for Ruby 4.0. @flavorjones
+- Drop support for Ruby 3.1. @flavorjones
+
+### Added
+
+- Introduce `Statement#named_params` to introspect on a parameterized SQL statement. #627 #642 @captn3m0
+
+### Improved
+
+- Small improvements to docstrings and comments. @flavorjones @houyuanjie
+
+
+## 2.8.1 / 2025-11-29
+
+- Vendored sqlite is updated to [v3.51.1](https://www.sqlite.org/releaselog/3_51_1.html) (from v3.51.0). #659 @flavorjones
+- Precompiled native gems are built with rake-compiler-dock v1.10.0 (previously v1.9.1).
+
+
+## 2.8.0 / 2025-11-05
+
+- Vendored sqlite is updated to [v3.51.0](https://www.sqlite.org/releaselog/3_51_0.html) (from v3.50.4). #652 @flavorjones
+
+
+## 2.7.4 / 2025-09-19
+
+- Vendored sqlite is updated to [v3.50.4](https://www.sqlite.org/releaselog/3_50_4.html) (from v3.50.3). #644 @flavorjones
+
+
+## 2.7.3 / 2025-07-18
+
+- Vendored sqlite is updated to [v3.50.3](https://sqlite.org/releaselog/3_50_3.html) (from v3.50.2). #638 @flavorjones
+
+
+## 2.7.2 / 2025-07-05
+
+- Backport a [fix](https://sqlite.org/src/info/64f5f14322) to the vendored SQLite to support compilation on Rocky Linux. See the [SQLite forum post](https://sqlite.org/forum/forumpost/44a58c8073) for more details. #634, #635 @flavorjones
+
+
+## 2.7.1 / 2025-06-30
+
+- Vendored sqlite is updated to [v3.50.2](https://sqlite.org/releaselog/3_50_2.html) (from v3.50.1). #633 @flavorjones
+
+
+## 2.7.0 / 2025-06-09
+
+- Vendored sqlite is updated to [v3.50.1](https://sqlite.org/releaselog/3_50_1.html) (from v3.49.1). #630 @flavorjones
+
+
+## 2.6.0 / 2025-02-20
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.49.1](https://sqlite.org/releaselog/3_49_1.html) (from v3.47.2). #605 @flavorjones
+- Updated to rake-compiler-dock v1.9.1. #610 @flavorjones
+
+### Important note for Window users
+
+Loading extensions is not available on Windows when using the precompiled native gems or compiling the vendored sqlite library from source, starting with sqlite3-ruby v2.6.0.
+
+Sqlite 3.48.0 and later have dramatically changed the "autoconf amalgamation" that is vendored in this gem. Specifically, the configuration is no longer actually autoconf, but some scripts that emulate autoconf's interface and behavior.
+
+Although this _mostly_ "just worked", we're having a problem resolving the libraries necessary for loading extensions. As a result, starting with sqlite3-ruby v2.6.0, extensions cannot be loaded on Windows when using precompiled native gems or when compiling the vendored sqlite library.
+
+If you are willing and able to help fix this, let us know at https://github.com/sparklemotion/sqlite3-ruby/issues/618.
+
+
+## 2.5.0 / 2024-12-25
+
+### Ruby
+
+This release introduces native gem packages that include Ruby 3.4.
+
+
+## 2.4.1 / 2024-12-08
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.47.2](https://sqlite.org/releaselog/3_47.2.html) #593 @flavorjones
+
+  The description from the upstream maintainers is:
+
+  > SQLite version 3.47.2, now available, fixes an important bug that first appeared in the 3.47.0
+  > release. In SQLite versions 3.47.0 and 3.47.1, if you try to convert a string into a
+  > floating-point value and the first 16 significant digits of the value are exactly
+  > "1844674407370955", then the floating-point number generated might be incorrect. The problem
+  > only affects x64 and i386 CPUs, so it does not affect you if you are running on ARM. And it only
+  > affects releases 3.47.0 and 3.47.1. **If you are running SQLite versions 3.47.0 or 3.47.1, then
+  > upgrading is recommended.**
+
+  Saving you a click, you should upgrade if you're running sqlite3-ruby v2.1.1 or later.
+
+
+### Fixed
+
+- Prevent unnecessary "Invalid Reference" warnings from the `ForkSafety` module when GC runs during the "after fork" hook. #592 @flavorjones
+
+
+## 2.4.0 / 2024-12-03
+
+### Added
+
+- `Database#load_extension` now accepts any object that responds to `#to_path`, in addition to String filesystem paths. [#586] @flavorjones
+- `Database.new` now accepts an `extensions:` parameter, which is an array of SQLite extensions that will be loaded during initialization. The array may contain String filesystem paths and objects that respond to `#to_path`. [#586] @flavorjones
+
+
+## 2.3.1 / 2024-11-25
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.47.1](https://sqlite.org/releaselog/3_47_1.html) [#589] @flavorjones
+
+
+## 2.3.0 / 2024-11-20
+
+### Added
+
+- The SQLITE_DBPAGE extension is now enabled by default, which implements an eponymous-only virtual table that provides direct access to the underlying database file by interacting with the pager. See https://www.sqlite.org/dbpage.html for more information. [#578] @flavorjones
+- The DBSTAT extension is now enabled by default, which implements a read-only eponymous virtual table that returns information about the amount of disk space used to store the content of an SQLite database. See https://sqlite.org/dbstat.html for more information. [#580] @pawurb @flavorjones
+- `Database#optimize` which wraps the `pragma optimize;` statement. Also added `Constants::Optimize` to allow advanced users to pass a bitmask of options. See https://www.sqlite.org/pragma.html#pragma_optimize. [#572] @alexcwatt @flavorjones
+- `SQLite3::VERSION_INFO` is contains a bag of metadata about the gem and the sqlite library used. `SQLite3::SQLITE_PACKAGED_LIBRARIES` and `SQLite3::SQLITE_PRECOMPILED_LIBRARIES` are indicate how the gem was built. [#581] @flavorjones
+
+
+### Fixed
+
+- `Database#encoding=` support for switching the database encoding to `UTF-16BE`, which has been broken since `Database#encoding=` was introduced in v1.3.12 in 2016. [#575] @miyucy
+- Omit mention of the `pkg-config` gem when failing to build from source, since it is not used. [#358] @flavorjones
+
+
+## 2.2.0 / 2024-10-30
+
+### Added
+
+- URI filenames are now allowed. This allows the injection of some behavior via recognized query parameters. See https://www.sqlite.org/uri.html for more information. [#571] @flavorjones
+
+
+### Improved
+
+- SQL Syntax errors during `Database#prepare` will raise a verbose exception with a multiline message indicating with a "^" exactly where in the statement the error occurred. [#554] @fractaledmind @flavorjones
+
+
+## 2.1.1 / 2024-10-22
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.47.0](https://sqlite.org/releaselog/3_47_0.html) [#570] @flavorjones
+
+
+## 2.1.0 / 2024-09-24
+
+### Ruby
+
+- This release drops support for Ruby 3.0. [#563] @flavorjones
+
+
+### Fork safety improvements
+
+Sqlite itself is [not fork-safe](https://www.sqlite.org/howtocorrupt.html#_carrying_an_open_database_connection_across_a_fork_). Specifically, writing in a child process to a database connection that was created in the parent process may corrupt the database file. To mitigate this risk, sqlite3-ruby has implemented the following changes:
+
+- All open writable database connections carried across a `fork()` will immediately be closed in the child process to mitigate the risk of corrupting the database file.
+- These connections will be incompletely closed ("discarded") which will result in a one-time memory leak in the child process.
+
+If it's at all possible, we strongly recommend that you close writable database 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 the README's "Fork Safety" section and `adr/2024-09-fork-safety.md` for more information. [#558, #565, #566] @flavorjones
+
+
+### Improved
+
+- Use `sqlite3_close_v2` to close databases in a deferred manner if there are unclosed prepared statements. Previously closing a database while statements were open resulted in a `BusyException`. See https://www.sqlite.org/c3ref/close.html for more context. [#557] @flavorjones
+- When setting a Database `busy_handler`, fire the write barrier to prevent potential crashes during the GC mark phase. [#556] @jhawthorn
+
+
+### Documentation
+
+- The `FAQ.md` has been updated to fix some inaccuracies. [#562] @rickhull
+
+
+## 2.0.4 / 2024-08-13
+
+### Dependencies
+
+- Vendored sqlite is updated to [v3.46.1](https://sqlite.org/releaselog/3_46_1.html) @flavorjones
+
+
+## 2.0.3 / 2024-07-29
+
+### Improved
+
+- `Database#quote` avoids allocating strings where reusing frozen strings is preferable. #548 @casperisfine
+
+
+## 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
@@ -299,7 +692,7 @@ You can opt-out of the packaged version of sqlite (and use your system-installed
 
 ## 1.4.1
 
-* Don't mandate dl functions for the extention build
+* Don't mandate dl functions for the extension build
 * bumping version
 
 

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
+
+### Decision record
+
+As of 2024-09, we're starting to keep some architecture decisions in the subdirectory `/adr`, so
+please look there for additional information.
+
+### 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.
+
+We use `sqlite3_close_v2` in `Database#close` since v2.1.0 which defers _actually_ closing the
+connection and freeing the underlying memory until all open statements are closed; though the
+`Database` object will immediately behave as though it's been fully closed. If a Database is not
+explicitly closed, it will be closed when it is GCed.
+
+`Statement#close` finalizes the underlying statement. If a Statement is not explicitly closed, it
+will be closed/finalized when it is GCed.
+
+
 ## Building gems
 
 As a prerequisite please make sure you have `docker` correctly installed, so that you're able to cross-compile the native gems.
@@ -23,12 +45,21 @@ Update `/dependencies.yml` to reflect:
 
 ## Making a release
 
-A quick checklist:
+A quick checklist to cutting a release of the sqlite3 gem:
 
-- [ ] make sure CI is green!
-- [ ] update `CHANGELOG.md` and `lib/sqlite3/version.rb` including `VersionProxy::{MINOR,TINY}`
-- [ ] 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`
+Prep
+- [ ] Make sure CI is green!
+- [ ] Update `CHANGELOG.md` and `lib/sqlite3/version.rb`
+- [ ] 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`
+
+Automated build and release
+- [ ] Run workflow https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/release.yml
+- [ ] Copy checksums from the push job
+
+Manual build and release
+- [ ] Run `bin/build-gems` and make sure it completes and all the tests pass
 - [ ] `for g in gems/*.gem ; do gem push $g ; done`
-- [ ] create a release at https://github.com/sparklemotion/sqlite3-ruby/releases and include sha2 checksums
+
+Post-release
+- [ ] Create a release at https://github.com/sparklemotion/sqlite3-ruby/releases and include sha2 checksums

data/FAQ.md

@@ -122,15 +122,17 @@ Placeholders in an SQL statement take any of the following formats:
 * `?`
 * `?_nnn_`
 * `:_word_`
+* `$_word_`
+* `@_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.)
+Where _n_ is an integer, and _word_ is an alpha-numeric identifier(or number).
+When the placeholder is associated with a number (only in case of `?_nnn_`),
+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:
@@ -207,48 +209,46 @@ Or do a `Database#prepare` to get the `Statement`, and then use either
   stmt.bind_params( "value", "name" => "bob" )
 ```
 
-## How do I discover metadata about a query?
+## How do I discover metadata about a query result?
   
-If you ever want to know the names or types of the columns in a result
-set, you can do it in several ways.
+IMPORTANT: `Database#execute` returns an Array of Array of Strings
+which will have no metadata about the query or the result, such
+as column names.
 
 
-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:
+There are 2 main sources of query metadata:
 
-
-```ruby
-  rows = db.execute( "select * from table" )
-  p rows[0].fields
-  p rows[0].types
-```
+* `Statement`
+* `ResultSet`
 
 
-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:
+You can get a `Statement` via `Database#prepare`, and you can get
+a `ResultSet` via `Statement#execute` or `Database#query`.
 
 
 ```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
+sql = 'select * from table'
+
+# No metadata
+rows = db.execute(sql)
+rows.class # => Array, no metadata
+rows.first.class # => Array, no metadata
+rows.first.first.class #=> String, no metadata
+
+# Statement has metadata
+stmt = db.prepare(sql)
+stmt.columns # => [ ... ]
+stmt.types # => [ ... ]
+
+# ResultSet has metadata
+results = stmt.execute
+results.columns # => [ ... ]
+results.types # => [ ... ]
+
+# ResultSet has metadata
+results = db.query(sql)
+results.columns # => [ ... ]
+results.types # => [ ... ]
 ```
 
 ## I'd like the rows to be indexible by column name.
@@ -273,7 +273,18 @@ is unavailable on the row, although the "types" property remains.)
 ```
 
 
-The other way is to use Ara Howard's
+A more granular way to do this is via `ResultSet#next_hash` or
+`ResultSet#each_hash`.
+
+
+```ruby
+  results = db.query( "select * from table" )
+  row = results.next_hash
+  p row['column1']
+```
+
+
+Another 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!
@@ -289,49 +300,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