class SQLite3::Database

Overview ↑

The Database class encapsulates a single connection to a SQLite3 database. Here’s a straightforward example of usage:

require 'sqlite3'

SQLite3::Database.new( "data.db" ) do |db|
  db.execute( "select * from table" ) do |row|
    p row
  end
end

It wraps the lower-level methods provided by the selected driver, and includes the Pragmas module for access to various pragma convenience methods.

The Database class provides type translation services as well, by which the SQLite3 data types (which are all represented as strings) may be converted into their corresponding types (as defined in the schemas for their tables). This translation only occurs when querying data from the database–insertions and updates are all still typeless.

Furthermore, the Database class has been designed to work well with the ArrayFields module from Ara Howard. If you require the ArrayFields module before performing a query, and if you have not enabled results as hashes, then the results will all be indexible by field name.

Thread safety ↑

When SQLite3.threadsafe? returns true, it is safe to share instances of the database class among threads without adding specific locking. Other object instances may require applications to provide their own locks if they are to be shared among threads. Please see the README.md for more information.

SQLite Extensions ↑

SQLite3::Database supports the universe of sqlite extensions. It’s possible to load an extension into an existing Database object using the load_extension method and passing a filesystem path:

db = SQLite3::Database.new(":memory:")
db.enable_load_extension(true)
db.load_extension("/path/to/extension")

As of v2.4.0, it’s also possible to pass an object that responds to #to_path. This documentation will refer to the supported interface as _ExtensionSpecifier, which can be expressed in RBS syntax as:

interface _ExtensionSpecifier
  def to_path: () → String
end

So, for example, if you are using the sqlean gem which provides modules that implement this interface, you can pass the module directly:

db = SQLite3::Database.new(":memory:")
db.enable_load_extension(true)
db.load_extension(SQLean::Crypto)

It’s also possible in v2.4.0+ to load extensions via the SQLite3::Database constructor by using the extensions: keyword argument to pass an array of String paths or extension specifiers:

db = SQLite3::Database.new(":memory:", extensions: ["/path/to/extension", SQLean::Crypto])

Note that when loading extensions via the constructor, there is no need to call enable_load_extension; however it is still necessary to call enable_load_extensions before any subsequently invocations of load_extension on the initialized Database object.

You can load extensions in a Rails application by using the extensions: configuration option:

# config/database.yml
development:
  adapter: sqlite3
  extensions:
    - .sqlpkg/nalgeon/crypto/crypto.so # a filesystem path
    - <%= SQLean::UUID.to_path %>      # or ruby code returning a path