solid_cache 0.4.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbca784f86b0c917fa3deb2eb48da304530332424df3e74d0d7241fa4d465ef0
-  data.tar.gz: f94bcbf1aee676ef3a9a719ec3dc40ce7b0a62838cdc903686de0f61bbf29cc4
+  metadata.gz: 1045c342c381976b1af701309a06bcfc3334afb1e7f2b83e39f1064718fefeb5
+  data.tar.gz: 59a6672e613a99b4bcf3d9c4215bd1d80a1bb2bd1ffcda3a4c5a0ac00d51bade
 SHA512:
-  metadata.gz: 6634aa88669e4f64d296e84883a524e406c6692ff47c8f2a92543923cb7da57d14caf74fe3da0273dd68920316fdcaab6b596c6904882cdf508b3658e3f202ba
-  data.tar.gz: e07c191310d07621fd8056f902611e519334f70578141cdd0e0230434370819161e53600cbf839006cc1238357a65a51ea9c7e4932146a6d72906bfce6f8bc12
+  metadata.gz: a55f8ce342e3b205ba5b37230328199adb194ec138eb78a27a6a1458c257377e9bf4d36db82bccaba7da3c345d92b25f2f3ae3d5f1da3296b4dbc75fdac69000
+  data.tar.gz: 270d176c9271089141fe72e6464f5cfb09f6dd052636831a63cd862eb0fc694ad3c210d4dacc70becd34371c1710e27b0d316068964ee45729d1adc75a184ad3

data/README.md

@@ -1,15 +1,11 @@
 # Solid Cache
 
-**Upgrading from v0.3.0 or earlier? Please see [upgrading to version 0.4.0](upgrading_to_version_0.4.x.md)**
+**Upgrading from v0.3.0 or earlier? Please see [upgrading to version v0.4.x and beyond](upgrading_to_version_0.4.x.md)**
 
 Solid Cache is a database-backed Active Support cache store implementation.
 
 Using SQL databases backed by SSDs we can have caches that are much larger and cheaper than traditional memory only Redis or Memcached backed caches.
 
-Testing on [HEY](https://hey.com) shows that reads and writes are 25%-50% slower than with a Redis cache (1.2ms vs 0.8-1ms per single-key read), but this is not a significant percentage of the overall request time.
-
-If cache misses are expensive (up to 50x the cost of a hit on HEY), then there are big advantages to caches that can hold months rather than days of data.
-
 ## Usage
 
 To set Solid Cache as your Rails cache, you should add this to your environment config:
@@ -18,7 +14,7 @@ To set Solid Cache as your Rails cache, you should add this to your environment
 config.cache_store = :solid_cache_store
 ```
 
-Solid Cache is a FIFO (first in, first out) cache. While this is not as efficient as an LRU cache, this is mitigated by the longer cache lifespans.
+Solid Cache is a FIFO (first in, first out) cache. While this is not as efficient as an LRU cache, this is mitigated by the longer cache lifespan.
 
 A FIFO cache is much easier to manage:
 1. We don't need to track when items are read
@@ -55,23 +51,66 @@ $ bin/rails db:migrate
 
 ### Configuration
 
+Configuration will be read from `config/solid_cache.yml`. You can change the location of the config file by setting the `SOLID_CACHE_CONFIG` env variable.
+
+The format of the file is:
+
+```yml
+default:
+  store_options: &default_store_options
+    max_age: <%= 60.days.to_i %>
+    namespace: <%= Rails.env %>
+  size_estimate_samples: 1000
+
+development: &development
+  database: development_cache
+  store_options:
+    <<: *default_store_options
+    max_size: <%= 256.gigabytes %>
+
+production: &production
+  databases: [production_cache1, production_cache2]
+  store_options:
+    <<: *default_store_options
+    max_entries: <%= 256.gigabytes %>
+```
+
+For the full list of keys for `store_options` see [Cache configuration](#cache-configuration). Any options passed to the cache lookup will overwrite those specified here.
+
+#### Connection configuration
+
+You can set one of `database`, `databases` and `connects_to` in the config file. They will be used to configure the cache databases in `SolidCache::Record#connects_to`.
+
+Setting `database` to `cache_db` will configure with:
+
+```ruby
+SolidCache::Record.connects_to database: { writing: :cache_db }
+```
+
+Setting `databases` to `[cache_db, cache_db2]` is the equivalent of:
+
+```ruby
+SolidCache::Record.connects_to shards: { cache_db1: { writing: :cache_db1 },  cache_db2: { writing: :cache_db2 } }
+```
+
+If `connects_to` is set it will be passed directly.
+
+If none of these are set, then Solid Cache will use the `ActiveRecord::Base` connection pool. This means that cache reads and writes will be part of any wrapping
+database transaction.
+
 #### Engine configuration
 
-There are two options that can be set on the engine:
+There are three options that can be set on the engine:
 
 - `executor` - the [Rails executor](https://guides.rubyonrails.org/threading_and_code_execution.html#executor) used to wrap asynchronous operations, defaults to the app executor
-- `connects_to` - a custom connects to value for the abstract `SolidCache::Record` active record model. Required for sharding and/or using a separate cache database to the main app.
+- `connects_to` - a custom connects to value for the abstract `SolidCache::Record` active record model. Required for sharding and/or using a separate cache database to the main app. This will overwrite any value set in `config/solid_cache.yml`
+- `size_estimate_samples` - if `max_size` is set on the cache, the number of the samples used to estimates the size.
 
 These can be set in your Rails configuration:
 
 ```ruby
 Rails.application.configure do
-  config.solid_cache.connects_to = {
-    shards: {
-      shard1: { writing: :cache_primary_shard1 },
-      shard2: { writing: :cache_primary_shard2 }
-    }
-  }
+  config.solid_cache.size_estimate_samples = 1000
 end
 ```
 
@@ -85,6 +124,7 @@ Solid Cache supports these options in addition to the standard `ActiveSupport::C
 - `expiry_queue` - which queue to add expiry jobs to (default: `default`)
 - `max_age` - the maximum age of entries in the cache (default: `2.weeks.to_i`). Can be set to `nil`, but this is not recommended unless using `max_entries` to limit the size of the cache.
 - `max_entries` - the maximum number of entries allowed in the cache (default: `nil`, meaning no limit)
+- `max_size` - the maximum size of the cache entries (default `nil`, meaning no limit)
 - `cluster` - a Hash of options for the cache database cluster, e.g `{ shards: [:database1, :database2, :database3] }`
 - `clusters` - and Array of Hashes for multiple cache clusters (ignored if `:cluster` is set)
 - `active_record_instrumentation` - whether to instrument the cache's queries (default: `true`)
@@ -95,13 +135,15 @@ For more information on cache clusters see [Sharding the cache](#sharding-the-ca
 
 ### Cache expiry
 
-Solid Cache tracks writes to the cache. For every write it increments a counter by 1. Once the counter reaches 80% of the `expiry_batch_size` it adds a task to run on a background thread. That task will:
+Solid Cache tracks writes to the cache. For every write it increments a counter by 1. Once the counter reaches 50% of the `expiry_batch_size` it adds a task to run on a background thread. That task will:
 
-1. Check if we have exceeded the `max_entries` value (if set) by subtracting the max and min IDs from the `SolidCache::Entry` table (this is an estimate that ignores any gaps).
+1. Check if we have exceeded the `max_entries` or `max_size` values (if set)
+   The current entries are estimated by subtracting the max and min IDs from the `SolidCache::Entry` table.
+   The current size is estimated by sampling the entry `byte_size` columns.
 2. If we have it will delete `expiry_batch_size` entries
 3. If not it will delete up to `expiry_batch_size` entries, provided they are all older than `max_age`.
 
-Expiring when we reach 80% of the batch size allows us to expire records from the cache faster than we write to it when we need to reduce the cache size.
+Expiring when we reach 50% of the batch size allows us to expire records from the cache faster than we write to it when we need to reduce the cache size.
 
 Only triggering expiry when we write means that the if the cache is idle, the background thread is also idle.
 
@@ -136,10 +178,10 @@ $ mv db/migrate/*.solid_cache.rb db/cache/migrate
 ```
 
 Set the engine configuration to point to the new database:
-```
-Rails.application.configure do
-  config.solid_cache.connects_to = { database: { writing: :cache } }
-end
+```yaml
+# config/solid_cache.yml
+production:
+  database: cache
 ```
 
 Run migrations:
@@ -172,44 +214,28 @@ production:
     host: cache3-db
 ```
 
-```ruby
-# config/environment/production.rb
-Rails.application.configure do
-  config.solid_cache.connects_to = {
-    shards: {
-      cache_shard1: { writing: :cache_shard1 },
-      cache_shard2: { writing: :cache_shard2 },
-      cache_shard3: { writing: :cache_shard3 },
-    }
-  }
-
-  config.cache_store = [ :solid_cache_store, cluster: { shards: [ :cache_shard1, :cache_shard2, :cache_shard3 ] } ]
-end
+```yaml
+# config/solid_cache.yml
+production:
+  databases: [cache_shard1, cache_shard2, cache_shard3]
 ```
 
 ### Secondary cache clusters
 
 You can add secondary cache clusters. Reads will only be sent to the primary cluster (i.e. the first one listed).
 
-Writes will go to all clusters. The writes to the primary cluster are synchronous, but asyncronous to the secondary clusters.
+Writes will go to all clusters. The writes to the primary cluster are synchronous, but asynchronous to the secondary clusters.
 
 To specific multiple clusters you can do:
 
-```ruby
-Rails.application.configure do
-  config.solid_cache.connects_to = {
-    shards: {
-      cache_primary_shard1: { writing: :cache_primary_shard1 },
-      cache_primary_shard2: { writing: :cache_primary_shard2 },
-      cache_secondary_shard1: { writing: :cache_secondary_shard1 },
-      cache_secondary_shard2: { writing: :cache_secondary_shard2 },
-    }
-  }
-
-  primary_cluster = { shards: [ :cache_primary_shard1, :cache_primary_shard2 ] }
-  secondary_cluster = { shards: [ :cache_secondary_shard1, :cache_secondary_shard2 ] }
-  config.cache_store = [ :solid_cache_store, clusters: [ primary_cluster, secondary_cluster ] ]
-end
+```yaml
+# config/solid_cache.yml
+production:
+  databases: [cache_primary_shard1, cache_primary_shard2, cache_secondary_shard1, cache_secondary_shard2]
+  store_options:
+    clusters:
+      - shards: [cache_primary_shard1, cache_primary_shard2]
+      - shards: [cache_secondary_shard1, cache_secondary_shard2]
 ```
 
 ### Named shard destinations
@@ -218,24 +244,19 @@ By default, the node key used for sharding is the name of the database in `datab
 
 It is possible to add names for the shards in the cluster config. This will allow you to shuffle or remove shards without breaking consistent hashing.
 
-```ruby
-Rails.application.configure do
-  config.solid_cache.connects_to = {
-    shards: {
-      cache_primary_shard1: { writing: :cache_primary_shard1 },
-      cache_primary_shard2: { writing: :cache_primary_shard2 },
-      cache_secondary_shard1: { writing: :cache_secondary_shard1 },
-      cache_secondary_shard2: { writing: :cache_secondary_shard2 },
-    }
-  }
-
-  primary_cluster = { shards: { cache_primary_shard1: :node1, cache_primary_shard2: :node2 } }
-  secondary_cluster = { shards: { cache_primary_shard1: :node3, cache_primary_shard2: :node4 } }
-  config.cache_store = [ :solid_cache_store, clusters: [ primary_cluster, secondary_cluster ] ]
-end
+```yaml
+production:
+  databases: [cache_primary_shard1, cache_primary_shard2, cache_secondary_shard1, cache_secondary_shard2]
+  store_options:
+    clusters:
+      - shards:
+          cache_primary_shard1: node1
+          cache_primary_shard2: node2
+      - shards:
+          cache_secondary_shard1: node3
+          cache_secondary_shard2: node4
 ```
 
-
 ### Enabling encryption
 
 Add this to an initializer:
@@ -254,7 +275,7 @@ The Solid Cache migrations try to create an index with 1024 byte entries. If tha
 
 ## Development
 
-Run the tests with `bin/rails test`. By default, these will run against SQLite.
+Run the tests with `bin/rake test`. By default, these will run against SQLite.
 
 You can also run the tests against MySQL and PostgreSQL. First start up the databases:
 
@@ -273,8 +294,8 @@ $ TARGET_DB=postgres bin/rails db:setup
 Then run the tests for the target database:
 
 ```shell
-$ TARGET_DB=mysql bin/rails test
-$ TARGET_DB=postgres bin/rails test
+$ TARGET_DB=mysql bin/rake test
+$ TARGET_DB=postgres bin/rake test
 ```
 
 ### Testing with multiple Rails version
@@ -285,7 +306,7 @@ multiple Rails version.
 To run a test for a specific version run:
 
 ```shell
-bundle exec appraisal rails-7-1 bin/rails test
+bundle exec appraisal rails-7-1 bin/rake test
 ```
 
 After updating the dependencies in the `Gemfile` please run:

data/Rakefile

@@ -8,3 +8,37 @@ load "rails/tasks/engine.rake"
 load "rails/tasks/statistics.rake"
 
 require "bundler/gem_tasks"
+require "rake/testtask"
+
+def run_without_aborting(*tasks)
+  errors = []
+
+  tasks.each do |task|
+    Rake::Task[task].invoke
+  rescue Exception
+    errors << task
+  end
+
+  abort "Errors running #{errors.join(', ')}" if errors.any?
+end
+
+def configs
+  [ :default, :cluster, :cluster_inferred, :clusters, :clusters_named, :database, :no_database ]
+end
+
+task :test do
+  tasks = configs.map { |config| "test:#{config}" }
+  run_without_aborting(*tasks)
+end
+
+configs.each do |config|
+  namespace :test do
+    task config do
+      if config == :default
+        sh("bin/rails test")
+      else
+        sh("SOLID_CACHE_CONFIG=config/solid_cache_#{config}.yml bin/rails test")
+      end
+    end
+  end
+end

data/app/jobs/solid_cache/expiry_job.rb

@@ -2,9 +2,9 @@
 
 module SolidCache
   class ExpiryJob < ActiveJob::Base
-    def perform(count, shard: nil, max_age:, max_entries:)
+    def perform(count, shard: nil, max_age: nil, max_entries: nil, max_size: nil)
       Record.with_shard(shard) do
-        Entry.expire(count, max_age: max_age, max_entries: max_entries)
+        Entry.expire(count, max_age: max_age, max_entries: max_entries, max_size: max_size)
       end
     end
   end

data/app/models/solid_cache/entry/expiration.rb

@@ -6,21 +6,25 @@ module SolidCache
       extend ActiveSupport::Concern
 
       class_methods do
-        def id_range
-          uncached do
-            pick(Arel.sql("max(id) - min(id) + 1")) || 0
-          end
-        end
-
-        def expire(count, max_age:, max_entries:)
-          if (ids = expiry_candidate_ids(count, max_age: max_age, max_entries: max_entries)).any?
+        def expire(count, max_age:, max_entries:, max_size:)
+          if (ids = expiry_candidate_ids(count, max_age: max_age, max_entries: max_entries, max_size: max_size)).any?
             delete(ids)
           end
         end
 
         private
-          def expiry_candidate_ids(count, max_age:, max_entries:)
-            cache_full = max_entries && max_entries < id_range
+          def cache_full?(max_entries:, max_size:)
+            if max_entries && max_entries < id_range
+              true
+            elsif max_size && max_size < estimated_size
+              true
+            else
+              false
+            end
+          end
+
+          def expiry_candidate_ids(count, max_age:, max_entries:, max_size:)
+            cache_full = cache_full?(max_entries: max_entries, max_size: max_size)
             return [] unless cache_full || max_age
 
             # In the case of multiple concurrent expiry operations, it is desirable to

data/app/models/solid_cache/entry/size/estimate.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module SolidCache
+  class Entry
+    # # Cache size estimation
+    #
+    # We store the size of each cache row in the byte_size field. This allows us to estimate the size of the cache
+    # by sampling those rows.
+    #
+    # To reduce the effect of outliers though we'll grab the N largest rows, and add their size to a sampled based
+    # estimate of the size of the remaining rows.
+    #
+    # ## Outliers
+    #
+    # There is an index on the byte_size column, so we can efficiently grab the N largest rows. We also grab the
+    # minimum byte_size of those rows, which we'll use as a cutoff for the non outlier sampling.
+    #
+    # ## Sampling
+    #
+    # To efficiently sample the data we use the key_hash column, which is a random 64 bit integer. There's an index
+    # on key_hash and byte_size so we can grab a sum of the byte_sizes in a range of key_hash directly from that
+    # index.
+    #
+    # To decide how big the range should be, we use the difference between the smallest and largest database IDs as
+    # an estimate of the number of rows in the table. This should be a good estimate, because we delete rows in ID order
+    #
+    # We then calculate the fraction of the rows we want to sample by dividing the sample size by the estimated number
+    # of rows.
+    #
+    # The we grab the byte_size sum of the rows in the range of key_hash values excluding any rows that are larger than
+    # our minimum outlier cutoff. We then divide this by the sampling fraction to get an estimate of the size of the
+    # non outlier rows
+    #
+    # ## Equations
+    #
+    #  Given N samples and a key_hash range of Kmin..Kmax
+    #
+    #    outliers_cutoff              OC = min(byte_size of N largest rows)
+    #    outliers_size                OS = sum(byte_size of N largest rows)
+    #
+    #    estimated number of rows     R = max(ID) - min(ID) + 1
+    #    sample_fraction              F = N / R
+    #    sample_range_size            S = (Kmax - Kmin) * F
+    #    sample range is              K1..K2 where K1 = Kmin + rand(Kmax - S) and K2 = K1 + S
+    #
+    #    non_outlier_sample_size      NSS = sum(byte_size of rows in key_hash range K1..K2 where byte_size <= OC)
+    #    non_outlier_estimated_size   NES = NSS / F
+    #    estimated_size               ES = OS + NES
+    module Size
+      class Estimate
+        attr_reader :samples, :max_records
+
+        def initialize(samples:)
+          @samples = samples
+          @max_records ||= Entry.id_range
+        end
+
+        def size
+          outliers_size + non_outlier_estimated_size
+        end
+
+        def exact?
+          outliers_count < samples || sampled_fraction == 1
+        end
+
+        private
+          def outliers_size
+            outliers_size_count_and_cutoff[0]
+          end
+
+          def outliers_count
+            outliers_size_count_and_cutoff[1]
+          end
+
+          def outliers_cutoff
+            outliers_size_count_and_cutoff[2]
+          end
+
+          def outliers_size_count_and_cutoff
+            @outlier_size_and_cutoff ||= Entry.uncached do
+              sum, count, min = Entry.largest_byte_sizes(samples).pick(Arel.sql("sum(byte_size), count(*), min(byte_size)"))
+              sum ? [sum, count, min] : [0, 0, nil]
+            end
+          end
+
+          def non_outlier_estimated_size
+            @non_outlier_estimated_size ||= sampled_fraction.zero? ? 0 : (sampled_non_outlier_size / sampled_fraction).round
+          end
+
+          def sampled_fraction
+            @sampled_fraction ||=
+              if max_records <= samples
+                0
+              else
+                [samples.to_f / (max_records - samples), 1].min
+              end
+          end
+
+          def sampled_non_outlier_size
+            @sampled_non_outlier_size ||= Entry.uncached do
+              Entry.in_key_hash_range(sample_range).up_to_byte_size(outliers_cutoff).sum(:byte_size)
+            end
+          end
+
+          def sample_range
+            if sampled_fraction == 1
+              key_hash_range
+            else
+              start = rand(key_hash_range.begin..(key_hash_range.end - sample_range_size))
+              start..(start + sample_range_size)
+            end
+          end
+
+          def key_hash_range
+            Entry::KEY_HASH_ID_RANGE
+          end
+
+          def sample_range_size
+            @sample_range_size ||= (key_hash_range.size * sampled_fraction).to_i
+          end
+      end
+    end
+  end
+end

data/app/models/solid_cache/entry/size/moving_average_estimate.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SolidCache
+  class Entry
+    module Size
+      # Moving averate cache size estimation
+      #
+      # To reduce variablitity in the cache size estimate, we'll use a moving average of the previous 20 estimates.
+      # The estimates are stored directly in the cache, under the "__solid_cache_entry_size_moving_average_estimates" key.
+      #
+      # We'll remove the largest and smallest estimates, and then average remaining ones.
+      class MovingAverageEstimate
+        ESTIMATES_KEY = "__solid_cache_entry_size_moving_average_estimates"
+        MAX_RETAINED_ESTIMATES = 50
+        TARGET_SAMPLED_FRACTION = 0.0005
+
+        attr_reader :samples, :size
+        delegate :exact?, to: :estimate
+
+        def initialize(samples:)
+          @samples = samples
+          @estimate = Estimate.new(samples: samples)
+          values = latest_values
+          @size = (values.sum / values.size.to_f).round
+          write_values(values)
+        end
+
+        private
+          attr_reader :estimate
+
+          def previous_values
+            Entry.read(ESTIMATES_KEY).presence&.split("|")&.map(&:to_i) || []
+          end
+
+          def latest_value
+            estimate.size
+          end
+
+          def latest_values
+            (previous_values + [latest_value]).last(retained_estimates)
+          end
+
+          def write_values(values)
+            Entry.write(ESTIMATES_KEY, values.join("|"))
+          end
+
+          def retained_estimates
+            [retained_estimates_for_target_fraction, MAX_RETAINED_ESTIMATES].min
+          end
+
+          def retained_estimates_for_target_fraction
+            (estimate.max_records / samples * TARGET_SAMPLED_FRACTION).floor + 1
+          end
+      end
+    end
+  end
+end

data/app/models/solid_cache/entry/size.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidCache
+  class Entry
+    module Size
+      extend ActiveSupport::Concern
+
+      included do
+        scope :largest_byte_sizes, -> (limit) { from(order(byte_size: :desc).limit(limit).select(:byte_size)) }
+        scope :in_key_hash_range, -> (range) { where(key_hash: range) }
+        scope :up_to_byte_size, -> (cutoff) { where("byte_size <= ?", cutoff) }
+      end
+
+      class_methods do
+        def estimated_size(samples: SolidCache.configuration.size_estimate_samples)
+          MovingAverageEstimate.new(samples: samples).size
+        end
+      end
+    end
+  end
+end

data/app/models/solid_cache/entry.rb

@@ -2,15 +2,13 @@
 
 module SolidCache
   class Entry < Record
-    include Expiration
+    include Expiration, Size
 
-    ID_BYTE_SIZE = 8
-    CREATED_AT_BYTE_SIZE = 8
-    KEY_HASH_BYTE_SIZE = 8
-    VALUE_BYTE_SIZE = 4
-    FIXED_SIZE_COLUMNS_BYTE_SIZE = ID_BYTE_SIZE + CREATED_AT_BYTE_SIZE + KEY_HASH_BYTE_SIZE + VALUE_BYTE_SIZE
-
-    self.ignored_columns += [ :key_hash, :byte_size] if SolidCache.key_hash_stage == :ignored
+    # The estimated cost of an extra row in bytes, including fixed size columns, overhead, indexes and free space
+    # Based on expirimentation on SQLite, MySQL and Postgresql.
+    # A bit high for SQLite (more like 90 bytes), but about right for MySQL/Postgresql.
+    ESTIMATED_ROW_OVERHEAD = 140
+    KEY_HASH_ID_RANGE = -(2**63)..(2**63 - 1)
 
     class << self
       def write(key, value)
@@ -22,23 +20,23 @@ module SolidCache
       end
 
       def read(key)
-        result = select_all_no_query_cache(get_sql, lookup_value(key)).first
+        result = select_all_no_query_cache(get_sql, key_hash_for(key)).first
         result[1] if result&.first == key
       end
 
       def read_multi(keys)
-        key_hashes = keys.map { |key| lookup_value(key) }
+        key_hashes = keys.map { |key| key_hash_for(key) }
         results = select_all_no_query_cache(get_all_sql(key_hashes), key_hashes).to_h
         results.except!(results.keys - keys)
       end
 
       def delete_by_key(key)
-        delete_no_query_cache(lookup_column, lookup_value(key))
+        delete_no_query_cache(:key_hash, key_hash_for(key))
       end
 
       def delete_multi(keys)
-        serialized_keys = keys.map { |key| lookup_value(key) }
-        delete_no_query_cache(lookup_column, serialized_keys)
+        serialized_keys = keys.map { |key| key_hash_for(key) }
+        delete_no_query_cache(:key_hash, serialized_keys)
       end
 
       def clear_truncate
@@ -52,7 +50,7 @@ module SolidCache
       def increment(key, amount)
         transaction do
           uncached do
-            result = lock.where(lookup_column => lookup_value(key)).pick(:key, :value)
+            result = lock.where(key_hash: key_hash_for(key)).pick(:key, :value)
             amount += result[1].to_i if result&.first == key
             write(key, amount)
             amount
@@ -64,6 +62,12 @@ module SolidCache
         increment(key, -amount)
       end
 
+      def id_range
+        uncached do
+          pick(Arel.sql("max(id) - min(id) + 1")) || 0
+        end
+      end
+
       private
         def upsert_all_no_query_cache(payloads)
           insert_all = ActiveRecord::InsertAll.new(
@@ -85,65 +89,34 @@ module SolidCache
         def add_key_hash_and_byte_size(payloads)
           payloads.map do |payload|
             payload.dup.tap do |payload|
-              if key_hash?
-                payload[:key_hash] = key_hash_for(payload[:key])
-                payload[:byte_size] = byte_size_for(payload)
-              end
+              payload[:key_hash] = key_hash_for(payload[:key])
+              payload[:byte_size] = byte_size_for(payload)
             end
           end
         end
 
-        def key_hash?
-          @key_hash ||= [ :indexed, :unindexed ].include?(SolidCache.key_hash_stage) &&
-            connection.column_exists?(table_name, :key_hash)
-        end
-
-        def key_hash_indexed?
-          key_hash? && SolidCache.key_hash_stage == :indexed
-        end
-
-        def lookup_column
-          key_hash_indexed? ? :key_hash : :key
-        end
-
-        def lookup_value(key)
-          key_hash_indexed? ? key_hash_for(key) : to_binary(key)
-        end
-
-        def lookup_placeholder
-          key_hash_indexed? ? 1 : "placeholder"
-        end
-
         def exec_query_method
           connection.respond_to?(:internal_exec_query) ? :internal_exec_query : :exec_query
         end
 
         def upsert_unique_by
-          connection.supports_insert_conflict_target? ? lookup_column : nil
+          connection.supports_insert_conflict_target? ? :key_hash : nil
         end
 
         def upsert_update_only
-          if key_hash_indexed?
-            [ :key, :value, :byte_size ]
-          elsif key_hash?
-            [ :value, :key_hash, :byte_size ]
-          else
-            [ :value ]
-          end
+          [ :key, :value, :byte_size ]
         end
 
         def get_sql
-          @get_sql ||= {}
-          @get_sql[lookup_column] ||= build_sql(where(lookup_column => lookup_placeholder).select(:key, :value))
+          @get_sql ||= build_sql(where(key_hash: 1).select(:key, :value))
         end
 
         def get_all_sql(key_hashes)
           if connection.prepared_statements?
             @get_all_sql_binds ||= {}
-            @get_all_sql_binds[[key_hashes.count, lookup_column]] ||= build_sql(where(lookup_column => key_hashes).select(:key, :value))
+            @get_all_sql_binds[key_hashes.count] ||= build_sql(where(key_hash: key_hashes).select(:key, :value))
           else
-            @get_all_sql_no_binds ||= {}
-            @get_all_sql_no_binds[lookup_column] ||= build_sql(where(lookup_column => [ lookup_placeholder, lookup_placeholder ]).select(:key, :value)).gsub("?, ?", "?")
+            @get_all_sql_no_binds ||= build_sql(where(key_hash: [ 1, 2 ]).select(:key, :value)).gsub("?, ?", "?")
           end
         end
 
@@ -192,7 +165,7 @@ module SolidCache
         end
 
         def byte_size_for(payload)
-          payload[:key].to_s.bytesize + payload[:value].to_s.bytesize + FIXED_SIZE_COLUMNS_BYTE_SIZE
+          payload[:key].to_s.bytesize + payload[:value].to_s.bytesize + ESTIMATED_ROW_OVERHEAD
         end
     end
   end

data/app/models/solid_cache/record.rb

@@ -6,7 +6,7 @@ module SolidCache
 
     self.abstract_class = true
 
-    connects_to(**SolidCache.connects_to) if SolidCache.connects_to
+    connects_to(**SolidCache.configuration.connects_to) if SolidCache.configuration.connects_to
 
     class << self
       def disable_instrumentation(&block)
@@ -14,12 +14,24 @@ module SolidCache
       end
 
       def with_shard(shard, &block)
-        if shard && SolidCache.connects_to
+        if shard && SolidCache.configuration.sharded?
           connected_to(shard: shard, role: default_role, prevent_writes: false, &block)
         else
           block.call
         end
       end
+
+      def each_shard(&block)
+        return to_enum(:each_shard) unless block_given?
+
+        if SolidCache.configuration.sharded?
+          SolidCache.configuration.shard_keys.each do |shard|
+            Record.with_shard(shard, &block)
+          end
+        else
+          yield
+        end
+      end
     end
   end
 end

data/lib/solid_cache/cluster/connections.rb

@@ -3,6 +3,8 @@
 module SolidCache
   class Cluster
     module Connections
+      attr_reader :shard_options
+
       def initialize(options = {})
         super(options)
         @shard_options = options.fetch(:shards, nil)
@@ -40,14 +42,14 @@ module SolidCache
         connections.names
       end
 
+      def connections
+        @connections ||= SolidCache::Connections.from_config(@shard_options)
+      end
+
       private
         def setup!
           connections
         end
-
-        def connections
-          @connections ||= SolidCache::Connections.from_config(@shard_options)
-        end
     end
   end
 end

data/lib/solid_cache/cluster/execution.rb

@@ -19,6 +19,8 @@ module SolidCache
                 instrument(&block)
               end
             end
+          rescue Exception => exception
+            error_handler&.call(method: :async, exception: exception, returning: nil)
           end
         end
 

data/lib/solid_cache/cluster/expiry.rb

@@ -7,9 +7,9 @@ module SolidCache
     module Expiry
       # For every write that we do, we attempt to delete EXPIRY_MULTIPLIER times as many records.
       # This ensures there is downward pressure on the cache size while there is valid data to delete
-      EXPIRY_MULTIPLIER = 1.25
+      EXPIRY_MULTIPLIER = 2
 
-      attr_reader :expiry_batch_size, :expiry_method, :expiry_queue, :expires_per_write, :max_age, :max_entries
+      attr_reader :expiry_batch_size, :expiry_method, :expiry_queue, :expires_per_write, :max_age, :max_entries, :max_size
 
       def initialize(options = {})
         super(options)
@@ -19,6 +19,7 @@ module SolidCache
         @expires_per_write = (1 / expiry_batch_size.to_f) * EXPIRY_MULTIPLIER
         @max_age = options.fetch(:max_age, 2.weeks.to_i)
         @max_entries = options.fetch(:max_entries, nil)
+        @max_size = options.fetch(:max_size, nil)
 
         raise ArgumentError, "Expiry method must be one of `:thread` or `:job`" unless [ :thread, :job ].include?(expiry_method)
       end
@@ -36,12 +37,13 @@ module SolidCache
         end
 
         def expire_later
+          max_options = { max_age: max_age, max_entries: max_entries, max_size: max_size }
           if expiry_method == :job
             ExpiryJob
               .set(queue: expiry_queue)
-              .perform_later(expiry_batch_size, shard: Entry.current_shard, max_age: max_age, max_entries: max_entries)
+              .perform_later(expiry_batch_size, shard: Entry.current_shard, **max_options)
           else
-            async { Entry.expire(expiry_batch_size, max_age: max_age, max_entries: max_entries) }
+            async { Entry.expire(expiry_batch_size, **max_options) }
           end
         end
     end

data/lib/solid_cache/cluster.rb

@@ -4,7 +4,10 @@ module SolidCache
   class Cluster
     include Connections, Execution, Expiry, Stats
 
+    attr_reader :error_handler
+
     def initialize(options = {})
+      @error_handler = options[:error_handler]
       super(options)
     end
 

data/lib/solid_cache/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SolidCache
+  class Configuration
+    attr_reader :store_options, :connects_to, :executor, :size_estimate_samples
+
+    def initialize(store_options: {}, database: nil, databases: nil, connects_to: nil, executor: nil, size_estimate_samples: 10_000)
+      @store_options = store_options
+      @size_estimate_samples = size_estimate_samples
+      @executor = executor
+      set_connects_to(database: database, databases: databases, connects_to: connects_to)
+    end
+
+    def sharded?
+      connects_to && connects_to[:shards]
+    end
+
+    def shard_keys
+      sharded? ? connects_to[:shards].keys : []
+    end
+
+    private
+      def set_connects_to(database:, databases:, connects_to:)
+        if [database, databases, connects_to].compact.size > 1
+          raise ArgumentError, "You can only specify one of :database, :databases, or :connects_to"
+        end
+
+        @connects_to =
+          case
+          when database
+            { database: { writing: database.to_sym } }
+          when databases
+            { shards: databases.map(&:to_sym).index_with { |database| { writing: database } } }
+          when connects_to
+            connects_to
+          else
+            nil
+          end
+      end
+  end
+end

data/lib/solid_cache/connections.rb

@@ -3,20 +3,20 @@
 module SolidCache
   module Connections
     def self.from_config(options)
-      if options.present? || SolidCache.all_shards_config.present?
+      if options.present? || SolidCache.configuration.sharded?
         case options
         when NilClass
-          names = SolidCache.all_shard_keys
+          names = SolidCache.configuration.shard_keys
           nodes = names.to_h { |name| [ name, name ] }
         when Array
-          names = options
+          names = options.map(&:to_sym)
           nodes = names.to_h { |name| [ name, name ] }
         when Hash
-          names = options.keys
-          nodes = options.invert
+          names = options.keys.map(&:to_sym)
+          nodes = options.to_h { |names, nodes| [ nodes.to_sym, names.to_sym ] }
         end
 
-        if (unknown_shards = names - SolidCache.all_shard_keys).any?
+        if (unknown_shards = names - SolidCache.configuration.shard_keys).any?
           raise ArgumentError, "Unknown #{"shard".pluralize(unknown_shards)}: #{unknown_shards.join(", ")}"
         end
 

data/lib/solid_cache/engine.rb

@@ -8,19 +8,28 @@ module SolidCache
 
     config.solid_cache = ActiveSupport::OrderedOptions.new
 
-    initializer "solid_cache", before: :run_prepare_callbacks do |app|
-      config.solid_cache.executor ||= app.executor
+    initializer "solid_cache.config", before: :initialize_cache do |app|
+      app.paths.add "config/solid_cache", with: ENV["SOLID_CACHE_CONFIG"] || "config/solid_cache.yml"
+
+      options = {}
+      if (config_path = Pathname.new(app.config.paths["config/solid_cache"].first)).exist?
+        options = app.config_for(config_path).to_h.deep_symbolize_keys
+      end
+
+      options[:connects_to] = config.solid_cache.connects_to if config.solid_cache.connects_to
+      options[:size_estimate_samples] = config.solid_cache.size_estimate_samples if config.solid_cache.size_estimate_samples
+
+      SolidCache.configuration = SolidCache::Configuration.new(**options)
 
-      SolidCache.executor = config.solid_cache.executor
-      SolidCache.connects_to = config.solid_cache.connects_to
       if config.solid_cache.key_hash_stage
-        unless [:ignored, :unindexed, :indexed].include?(config.solid_cache.key_hash_stage)
-          raise "ArgumentError, :key_hash_stage must be :ignored, :unindexed or :indexed"
-        end
-        SolidCache.key_hash_stage = config.solid_cache.key_hash_stage
+        ActiveSupport.deprecator.warn("config.solid_cache.key_hash_stage is deprecated and has no effect.")
       end
     end
 
+    initializer "solid_cache.app_executor", before: :run_prepare_callbacks do |app|
+      SolidCache.executor = config.solid_cache.executor || app.executor
+    end
+
     config.after_initialize do
       Rails.cache.setup! if Rails.cache.is_a?(Store)
     end

data/lib/solid_cache/store/clusters.rb

@@ -11,7 +11,7 @@ module SolidCache
         clusters_options = options.fetch(:clusters) { [ options.fetch(:cluster, {}) ] }
 
         @clusters = clusters_options.map.with_index do |cluster_options, index|
-          Cluster.new(options.merge(cluster_options).merge(async_writes: index != 0))
+          Cluster.new(options.merge(cluster_options).merge(async_writes: index != 0, error_handler: error_handler))
         end
 
         @primary_cluster = clusters.first

data/lib/solid_cache/store.rb

@@ -5,6 +5,10 @@ module SolidCache
     include Api, Clusters, Entries, Failsafe
     prepend ActiveSupport::Cache::Strategy::LocalCache
 
+    def initialize(options = {})
+      super(SolidCache.configuration.store_options.merge(options))
+    end
+
     def self.supports_cache_versioning?
       true
     end

data/lib/solid_cache/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidCache
-  VERSION = "0.4.2"
+  VERSION = "0.5.1"
 end

data/lib/solid_cache.rb

@@ -9,28 +9,8 @@ loader.ignore("#{__dir__}/generators")
 loader.setup
 
 module SolidCache
-  mattr_accessor :executor, :connects_to
-  mattr_accessor :key_hash_stage, default: :indexed
-
-  def self.all_shard_keys
-    all_shards_config&.keys || []
-  end
-
-  def self.all_shards_config
-    connects_to && connects_to[:shards]
-  end
-
-  def self.each_shard(&block)
-    return to_enum(:each_shard) unless block_given?
-
-    if (shards = all_shards_config&.keys)
-      shards.each do |shard|
-        Record.with_shard(shard, &block)
-      end
-    else
-      yield
-    end
-  end
+  mattr_accessor :executor
+  mattr_accessor :configuration, default: Configuration.new
 end
 
 loader.eager_load

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_cache
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.1
 platform: ruby
 authors:
 - Donal McBreen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-29 00:00:00.000000000 Z
+date: 2024-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -93,6 +93,9 @@ files:
 - app/jobs/solid_cache/expiry_job.rb
 - app/models/solid_cache/entry.rb
 - app/models/solid_cache/entry/expiration.rb
+- app/models/solid_cache/entry/size.rb
+- app/models/solid_cache/entry/size/estimate.rb
+- app/models/solid_cache/entry/size/moving_average_estimate.rb
 - app/models/solid_cache/record.rb
 - db/migrate/20230724121448_create_solid_cache_entries.rb
 - db/migrate/20240108155507_add_key_hash_and_byte_size_to_solid_cache_entries.rb
@@ -107,6 +110,7 @@ files:
 - lib/solid_cache/cluster/execution.rb
 - lib/solid_cache/cluster/expiry.rb
 - lib/solid_cache/cluster/stats.rb
+- lib/solid_cache/configuration.rb
 - lib/solid_cache/connections.rb
 - lib/solid_cache/connections/sharded.rb
 - lib/solid_cache/connections/single.rb
@@ -127,7 +131,7 @@ metadata:
   homepage_uri: http://github.com/rails/solid_cache
   source_code_uri: http://github.com/rails/solid_cache
 post_install_message: |
-  Solid Cache v0.4 contains new database migrations.
+  Upgrading from Solid Cache v0.3 or earlier? There are new database migrations in v0.4.
   See https://github.com/rails/solid_cache/blob/main/upgrading_to_version_0.4.x.md for upgrade instructions.
 rdoc_options: []
 require_paths:
@@ -143,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.4
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: A database backed ActiveSupport::Cache::Store