activerecord-enhancedsqlite3-adapter 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f138b7e075e546691856c8e45f22413a1e381df3024c6ef30e467dbde830c896
-  data.tar.gz: 0e6bde9f85883cacc12893f8ab2b1ca5820deea6d6a1357a262fb24401ed4980
+  metadata.gz: 24efb62453474faa0b37357d98f5b0f8ba13fa98d7e633b5d3a7de5e16d875f6
+  data.tar.gz: 0de2b8cae842c4262d81932c577df7731e570f347f0a22a2151ef9671bd8648d
 SHA512:
-  metadata.gz: dafd2a35c78565843b9aa384fb5988818c48bdc6852da55363c7e18e447a752b8194ef08ea4a40c9b482f30317cd7afc8e9501e22cb38abbab51dd16f3d6c7a7
-  data.tar.gz: 5c0d6b07eb0b3e90c4fd6f8859f90d944e33d90e100ee96981f24b4d1cb1212266045f81abe935b4ad1913caf22d43cb3386a73bdb0670b15f8686e680619a77
+  metadata.gz: a55c35f42fef85b0373df52f06d1b50b66c4191382844ee6a9836049af03386085bfe9616de8bfc259fcfd6325d5a84f4cc8ca396d721ff87fdcfc49c80dae17
+  data.tar.gz: b50f2484872aa18a0681c31abfd4d6a56e044ff9610cb288c73611cb0f56ed8b8242a771b9c4e95a07119ec094aef5bcf6c85f1bc363fd08e59d45a57b162902

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.3.0] - 2023-12-06
+
+- Added a more performant implementation of the the `timeout` mechanism
+
+## [0.2.0] - 2023-09-28
+
+- Added support for deferrable constraints
+
 ## [0.1.0] - 2023-09-28
 
 - Initial release
+- Added support for virtual columns
+- Added support setting PRAGMA statements via the `config/database.yml` file
+- Added support for loading extensions via the `config/database.yml` file

data/README.md

@@ -1,24 +1,85 @@
-# Activerecord::Enhanced::Sqlite3::Adapter
+# ActiveRecord Enhanced SQLite3 Adapter
 
-TODO: Delete this and the text below, and describe your gem
+Enhance ActiveRecord's 7.1 SQLite3 adapter. Adds support for:
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/activerecord/enhanced/sqlite3/adapter`. To experiment with that code, run `bin/console` for an interactive prompt.
+* generated columns,
+* deferred foreign keys,
+* `PRAGMA` tuning,
+* and extension loading
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```shell
+$ bundle add activerecord-enhancedsqlite3-adapter
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Usage
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+This gem hooks into your Rails application to enhance the `SQLite3Adapter` automatically. No setup required!
 
-## Usage
+Once installed, you can take advantage of the added features.
+
+### Generated columns
+
+You can now create `virtual` columns, both stored and dynamic. The [SQLite docs](https://www.sqlite.org/gencol.html) explain the difference:
+
+> Generated columns can be either VIRTUAL or STORED. The value of a VIRTUAL column is computed when read, whereas the value of a STORED column is computed when the row is written. STORED columns take up space in the database file, whereas VIRTUAL columns use more CPU cycles when being read.
+
+The default is to create dynamic/virtual columns.
+
+```ruby
+create_table :virtual_columns, force: true do |t|
+  t.string :name
+  t.virtual :upper_name, type: :string, as: "UPPER(name)", stored: true
+  t.virtual :lower_name, type: :string, as: "LOWER(name)", stored: false
+  t.virtual :octet_name, type: :integer, as: "LENGTH(name)"
+end
+```
+
+### Deferred foreign keys
+
+You can now specify whether or not a foreign key should be deferrable, whether `:deferred` or `:immediate`.
+
+`:deferred` foreign keys mean that the constraint check will be done once the transaction is committed and allows the constraint behavior to change within transaction. `:immediate` means that constraint check is immediate and allows the constraint behavior to change within transaction. The default is `:immediate`.
+
+```ruby
+add_reference :person, :alias, foreign_key: { deferrable: :deferred }
+add_reference :alias, :person, foreign_key: { deferrable: :deferred }
+```
+
+### `PRAGMA` tuning
+
+Pass any [`PRAGMA` key-value pair](https://www.sqlite.org/pragma.html) under a `pragmas` list in your `config/database.yml` file to ensure that these configuration settings are applied to all database connections.
+
+```yaml
+default: &default
+  adapter: sqlite3
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  pragmas:
+    # level of database durability, 2 = "FULL" (sync on every write), other values include 1 = "NORMAL" (sync every 1000 written pages) and 0 = "NONE"
+    # https://www.sqlite.org/pragma.html#pragma_synchronous
+    synchronous: "FULL"
+```
+
+### Extension loading
+
+There are a number of [SQLite extensions available as Ruby gems](https://github.com/asg017/sqlite-ecosystem). In order to load the extensions, you need to install the gem (`bundle add {extension-name}`) and then load it into the database connections. In order to support the latter, this gem enhances the `config/database.yml` file to support an `extensions` array. For example, to install and load [an extension](https://github.com/asg017/sqlite-ulid) for supporting [<abbr title="Universally Unique Lexicographically Sortable Identifiers">ULIDs</abbr>](https://github.com/ulid/spec), we would do:
+
+```shell
+$ bundle add sqlite_ulid
+```
+
+then
 
-TODO: Write usage instructions here
+```yaml
+default: &default
+  adapter: sqlite3
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  extensions:
+    - sqlite_ulid
+```
 
 ## Development
 
@@ -28,7 +89,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/activerecord-enhancedsqlite3-adapter.
+Bug reports and pull requests are welcome on GitHub at https://github.com/fractaledmind/activerecord-enhancedsqlite3-adapter.
 
 ## License
 

data/lib/enhanced_sqlite3/adapter.rb

@@ -22,6 +22,7 @@ module EnhancedSQLite3
     def configure_connection
       super
 
+      configure_busy_handler_timeout
       configure_pragmas
       configure_extensions
 
@@ -31,6 +32,28 @@ module EnhancedSQLite3
 
     private
 
+    def configure_busy_handler_timeout
+      return unless @config.key?(:timeout)
+
+      timeout = self.class.type_cast_config_to_integer(@config[:timeout])
+      @raw_connection.busy_handler do |count|
+        timed_out = false
+        # capture the start time of this blocked write
+        @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) if count == 0
+        # keep track of elapsed time every 100 iterations (to lower load)
+        if count % 100 == 0
+          @elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+          # fail if we exceed the timeout value (captured from the timeout config option, converted to seconds)
+          timed_out = @elapsed_time > timeout
+        end
+        if timed_out
+          false # this will cause the BusyException to be raised
+        else
+          sleep 0.001 # sleep 1 millisecond (or whatever)
+        end
+      end
+    end
+
     def configure_pragmas
       @config.fetch(:pragmas, []).each do |key, value|
         execute("PRAGMA #{key} = #{value}", "SCHEMA")

data/lib/enhanced_sqlite3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EnhancedSQLite3
-  VERSION = "0.2.0"
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-enhancedsqlite3-adapter
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Stephen Margheim
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-09 00:00:00.000000000 Z
+date: 2023-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord