Class: ActiveSupport::Cache::RedisCacheStore
- Defined in:
- activesupport/lib/active_support/cache/redis_cache_store.rb
Overview
Redis cache store.
Deployment note: Take care to use a *dedicated Redis cache* rather than pointing this at your existing Redis server. It won’t cope well with mixed usage patterns and it won’t expire cache entries by default.
Redis cache server setup guide: redis.io/topics/lru-cache
-
Supports vanilla Redis, hiredis, and Redis::Distributed.
-
Supports Memcached-like sharding across Redises with Redis::Distributed.
-
Fault tolerant. If the Redis server is unavailable, no exceptions are raised. Cache fetches are all misses and writes are dropped.
-
Local cache. Hot in-memory primary cache within block/middleware scope.
-
read_multi
andwrite_multi
support for Redis mget/mset. Use Redis::Distributed 4.0.1+ for distributed mget support. -
delete_matched
support for Redis KEYS globs.
Constant Summary collapse
- MAX_KEY_BYTESIZE =
Keys are truncated with the ActiveSupport digest if they exceed 1kB
1024
- DEFAULT_REDIS_OPTIONS =
{ connect_timeout: 1, read_timeout: 1, write_timeout: 1, }
- DEFAULT_ERROR_HANDLER =
-> (method:, returning:, exception:) do if logger logger.error { "RedisCacheStore: #{method} failed, returned #{returning.inspect}: #{exception.class}: #{exception.message}" } end ActiveSupport.error_reporter&.report( exception, severity: :warning, source: "redis_cache_store.active_support", ) end
Instance Attribute Summary collapse
-
#max_key_bytesize ⇒ Object
readonly
Returns the value of attribute max_key_bytesize.
-
#redis_options ⇒ Object
readonly
Returns the value of attribute redis_options.
Attributes inherited from Store
Class Method Summary collapse
-
.build_redis(redis: nil, url: nil, **redis_options) ⇒ Object
Factory method to create a new Redis instance.
-
.supports_cache_versioning? ⇒ Boolean
Advertise cache versioning support.
Instance Method Summary collapse
-
#cleanup(options = nil) ⇒ Object
Cache Store API implementation.
-
#clear(options = nil) ⇒ Object
Clear the entire cache on all Redis servers.
-
#decrement(name, amount = 1, options = nil) ⇒ Object
Decrement a cached integer value using the Redis decrby atomic operator.
-
#delete_matched(matcher, options = nil) ⇒ Object
Cache Store API implementation.
-
#increment(name, amount = 1, options = nil) ⇒ Object
Increment a cached integer value using the Redis incrby atomic operator.
-
#initialize(namespace: nil, compress: true, compress_threshold: 1.kilobyte, coder: default_coder, expires_in: nil, race_condition_ttl: nil, error_handler: DEFAULT_ERROR_HANDLER, skip_nil: false, **redis_options) ⇒ RedisCacheStore
constructor
Creates a new Redis cache store.
- #inspect ⇒ Object
-
#read_multi(*names) ⇒ Object
Cache Store API implementation.
- #redis ⇒ Object
-
#stats ⇒ Object
Get info from redis servers.
Methods inherited from Store
#delete, #delete_multi, #exist?, #fetch, #fetch_multi, #mute, #new_entry, #read, #silence!, #write, #write_multi
Constructor Details
#initialize(namespace: nil, compress: true, compress_threshold: 1.kilobyte, coder: default_coder, expires_in: nil, race_condition_ttl: nil, error_handler: DEFAULT_ERROR_HANDLER, skip_nil: false, **redis_options) ⇒ RedisCacheStore
Creates a new Redis cache store.
Handles four options: :redis block, :redis instance, single :url string, and multiple :url strings.
Option Class Result
:redis Proc -> [:redis].call
:redis Object -> [:redis]
:url String -> Redis.new(url:
No namespace is set by default. Provide one if the Redis cache server is shared with other apps: namespace: 'myapp-cache'
.
Compression is enabled by default with a 1kB threshold, so cached values larger than 1kB are automatically compressed. Disable by passing compress: false
or change the threshold by passing compress_threshold: 4.kilobytes
.
No expiry is set on cache entries by default. Redis is expected to be configured with an eviction policy that automatically deletes least-recently or -frequently used keys when it reaches max memory. See redis.io/topics/lru-cache for cache server setup.
Race condition TTL is not set by default. This can be used to avoid “thundering herd” cache writes when hot cache entries are expired. See ActiveSupport::Cache::Store#fetch
for more.
Setting skip_nil: true
will not cache nil results:
cache.fetch('foo') { nil }
cache.fetch('bar', skip_nil: true) { nil }
cache.exist?('foo') # => true
cache.exist?('bar') # => false
143 144 145 146 147 148 149 150 151 152 153 154 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 143 def initialize(namespace: nil, compress: true, compress_threshold: 1.kilobyte, coder: default_coder, expires_in: nil, race_condition_ttl: nil, error_handler: DEFAULT_ERROR_HANDLER, skip_nil: false, **) = @max_key_bytesize = MAX_KEY_BYTESIZE @error_handler = error_handler @supports_pipelining = true super namespace: namespace, compress: compress, compress_threshold: compress_threshold, expires_in: expires_in, race_condition_ttl: race_condition_ttl, coder: coder, skip_nil: skip_nil end |
Instance Attribute Details
#max_key_bytesize ⇒ Object (readonly)
Returns the value of attribute max_key_bytesize
107 108 109 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 107 def max_key_bytesize @max_key_bytesize end |
#redis_options ⇒ Object (readonly)
Returns the value of attribute redis_options
106 107 108 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 106 def end |
Class Method Details
.build_redis(redis: nil, url: nil, **redis_options) ⇒ Object
Factory method to create a new Redis instance.
Handles four options: :redis block, :redis instance, single :url string, and multiple :url strings.
Option Class Result
:redis Proc -> [:redis].call
:redis Object -> [:redis]
:url String -> Redis.new(url:
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 78 def build_redis(redis: nil, url: nil, **) # :nodoc: urls = Array(url) if redis.is_a?(Proc) redis.call elsif redis redis elsif urls.size > 1 build_redis_distributed_client(urls: urls, **) elsif urls.empty? build_redis_client(**) else build_redis_client(url: urls.first, **) end end |
.supports_cache_versioning? ⇒ Boolean
Advertise cache versioning support.
60 61 62 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 60 def self.supports_cache_versioning? true end |
Instance Method Details
#cleanup(options = nil) ⇒ Object
Cache Store API implementation.
Removes expired entries. Handled natively by Redis least-recently-/ least-frequently-used expiry, so manual cleanup is not supported.
279 280 281 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 279 def cleanup( = nil) super end |
#clear(options = nil) ⇒ Object
Clear the entire cache on all Redis servers. Safe to use on shared servers if the cache is namespaced.
Failsafe: Raises errors.
287 288 289 290 291 292 293 294 295 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 287 def clear( = nil) failsafe :clear do if namespace = ()[:namespace] delete_matched "*", namespace: namespace else redis.then { |c| c.flushdb } end end end |
#decrement(name, amount = 1, options = nil) ⇒ Object
Decrement a cached integer value using the Redis decrby atomic operator. Returns the updated value.
If the key is unset or has expired, it will be set to -amount:
cache.decrement("foo") # => -1
To set a specific value, call #write passing raw: true
:
cache.write("baz", 5, raw: true)
cache.decrement("baz") # => 4
Decrementing a non-numeric value, or a value written without raw: true
, will fail and return nil
.
Failsafe: Raises errors.
265 266 267 268 269 270 271 272 273 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 265 def decrement(name, amount = 1, = nil) instrument :decrement, name, amount: amount do failsafe :decrement do = () key = normalize_key(name, ) change_counter(key, -amount, ) end end end |
#delete_matched(matcher, options = nil) ⇒ Object
Cache Store API implementation.
Supports Redis KEYS glob patterns:
h?llo matches hello, hallo and hxllo
h*llo matches hllo and heeeello
h[ae]llo matches hello and hallo, but not hillo
h[^e]llo matches hallo, hbllo, ... but not hello
h[a-b]llo matches hallo and hbllo
Use \ to escape special characters if you want to match them verbatim.
See redis.io/commands/KEYS for more.
Failsafe: Raises errors.
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 201 def delete_matched(matcher, = nil) instrument :delete_matched, matcher do unless String === matcher raise ArgumentError, "Only Redis glob strings are supported: #{matcher.inspect}" end redis.then do |c| pattern = namespace_key(matcher, ) cursor = "0" # Fetch keys in batches using SCAN to avoid blocking the Redis server. nodes = c.respond_to?(:nodes) ? c.nodes : [c] nodes.each do |node| begin cursor, keys = node.scan(cursor, match: pattern, count: SCAN_BATCH_SIZE) node.del(*keys) unless keys.empty? end until cursor == "0" end end end end |
#increment(name, amount = 1, options = nil) ⇒ Object
Increment a cached integer value using the Redis incrby atomic operator. Returns the updated value.
If the key is unset or has expired, it will be set to amount
:
cache.increment("foo") # => 1
cache.increment("bar", 100) # => 100
To set a specific value, call #write passing raw: true
:
cache.write("baz", 5, raw: true)
cache.increment("baz") # => 6
Incrementing a non-numeric value, or a value written without raw: true
, will fail and return nil
.
Failsafe: Raises errors.
239 240 241 242 243 244 245 246 247 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 239 def increment(name, amount = 1, = nil) instrument :increment, name, amount: amount do failsafe :increment do = () key = normalize_key(name, ) change_counter(key, amount, ) end end end |
#inspect ⇒ Object
168 169 170 171 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 168 def inspect instance = @redis || "#<#{self.class} options=#{options.inspect} redis=#{instance.inspect}>" end |
#read_multi(*names) ⇒ Object
Cache Store API implementation.
Read multiple values at once. Returns a hash of requested keys -> fetched values.
177 178 179 180 181 182 183 184 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 177 def read_multi(*names) = names. instrument(:read_multi, names, ) do |payload| read_multi_entries(names, **).tap do |results| payload[:hits] = results.keys end end end |
#redis ⇒ Object
156 157 158 159 160 161 162 163 164 165 166 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 156 def redis @redis ||= begin = self.class.send(:retrieve_pool_options, ) if .any? ::ConnectionPool.new() { self.class.build_redis(**) } else self.class.build_redis(**) end end end |
#stats ⇒ Object
Get info from redis servers.
298 299 300 |
# File 'activesupport/lib/active_support/cache/redis_cache_store.rb', line 298 def stats redis.then { |c| c.info } end |