ar_cache 1.2.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a01b3342ccad3bf06ce4438f714f00ffc467efc32f58809ab940163ebaf440d7
-  data.tar.gz: 453c9232cbc03dee8572b1133972f01d6dd1c2501df0c9279a32a5e4243ebeb0
+  metadata.gz: 2d9f5ff76912fe1e2276c795f619cf2e1e88780e7592e7fcb659e55a75bd8aff
+  data.tar.gz: 51ccc09d008c7d345dc9901c2898463ef5d2ebd40649b829b63ba801b13948da
 SHA512:
-  metadata.gz: 7d6a3bb90d4ac0eb3384650fd17fbed43be74da2ca0a57b55c9d19b9c68722b2d23785fd42e00cbdec8a4563cc10c6c44ac7609a8b4a09d9b4a813f47c3f2ae1
-  data.tar.gz: 2105bf0e6e89c3d438f30b43bef1dd64b66b511968fec5c393068043ddb52ee833762f0508a4a84d25940ddac36c686c8b5fd4e6ef73d75802de878645ac265b
+  metadata.gz: f8422672824015d7496620282919ff08b380066c8e05d8bde53bd8ef732f6b3a1c475f86bdd258f188be151fd78734b79bddbfa00bb20ce9b78be4443e96a168
+  data.tar.gz: 3059b104bf49417391e3edb84c5005822ba652b8c29bf8fd0de7c23080444fbd8345da5776a8bd0ba81b515845e567776c22b0a925c0235042c7383f4610cbc6

data/CHANGELOG.md

@@ -2,20 +2,8 @@
 
 ## main
 
-## 1.2.0 (2021-03-12)
+## 2.1.0 (2018-06-29 UTC)
 
-[Commit [#c830907](https://github.com/OuYangJinTing/ar_cache/commit/c830907595b7d1d46a2f29204ee6051ecc3ff30c)]:
-
-- Remove methods: `ArCache::MockTable#enabled?`, `ArCache::MockTable#select_enabled?`, `ArCache::Table.enabled?`, `ArCache::Table.select_enabled?`, `ActiveRecord::Relation#skip_ar_cache`.
-- Rename methods: `ArCache#skip_cache? => ArCache#skip?`, `ArCache#skip_cache => ArCache#skip`, `ArCache#pre_expire? => ArCache#expire?`, `ArCache#pre_expire => ArCache#expire`.
-- Now, `ArCache#skip` method only skip read cache, but still try delete cache.
-
-## 1.1.0 (2021-03-11)
-
-- [Commit [#92965d2](https://github.com/OuYangJinTing/ar_cache/commit/92965d26e130da9a13bd52ea31f3f668851f6f12)] Fully automatic delete cache when call delete_all/update_all method.
-- [Commit [#231cfd3](https://github.com/OuYangJinTing/ar_cache/commit/231cfd35c2c197bf41628f4f914ba39fb8debd81)] Optimize has_one(through:) cache implementation.
-- [Commit [#ce5444c](https://github.com/OuYangJinTing/ar_cache/commit/ce5444c8c4ec0a61bec5e07d694295d3cc5decf8)]  ActiveRecord::Relation#reload and ActiveRecord::Associations::Association#reload should skip read cache if associated target is already loaded.
-
-## 1.0.0 (2021-03-02)
-
-- Initial version.
+- [PR [#4](https://github.com/OuYangJinTing/ar_cache/pull/4)] Fix high concurrency causes write dirty cache ([@OuYangJinTing](https://github.com/OuYangJinTing))
+- [PR [#3](https://github.com/OuYangJinTing/ar_cache/pull/3)] Shouldn't open database transaction when use cache lock ([@OuYangJinTing](https://github.com/OuYangJinTing))
+- [PR [#2](https://github.com/OuYangJinTing/ar_cache/pull/2)] Use configuration template as default values ([@OuYangJinTing](https://github.com/OuYangJinTing))

data/Gemfile.common

@@ -5,6 +5,8 @@ gemspec
 
 gem 'rake'
 
+gem 'redis'
+gem 'dalli'
 gem 'sqlite3'
 gem 'database_cleaner'
 

data/Gemfile.lock

@@ -1,66 +1,67 @@
 PATH
   remote: .
   specs:
-    ar_cache (1.2.0)
+    ar_cache (2.1.0)
       activerecord (>= 6.1, < 7)
+      oj (>= 3, < 4)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (6.1.1)
-      actionpack (= 6.1.1)
-      activesupport (= 6.1.1)
+    actioncable (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
       nio4r (~> 2.0)
       websocket-driver (>= 0.6.1)
-    actionmailbox (6.1.1)
-      actionpack (= 6.1.1)
-      activejob (= 6.1.1)
-      activerecord (= 6.1.1)
-      activestorage (= 6.1.1)
-      activesupport (= 6.1.1)
+    actionmailbox (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activejob (= 6.1.3.2)
+      activerecord (= 6.1.3.2)
+      activestorage (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
       mail (>= 2.7.1)
-    actionmailer (6.1.1)
-      actionpack (= 6.1.1)
-      actionview (= 6.1.1)
-      activejob (= 6.1.1)
-      activesupport (= 6.1.1)
+    actionmailer (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      actionview (= 6.1.3.2)
+      activejob (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
       mail (~> 2.5, >= 2.5.4)
       rails-dom-testing (~> 2.0)
-    actionpack (6.1.1)
-      actionview (= 6.1.1)
-      activesupport (= 6.1.1)
+    actionpack (6.1.3.2)
+      actionview (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
       rack (~> 2.0, >= 2.0.9)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actiontext (6.1.1)
-      actionpack (= 6.1.1)
-      activerecord (= 6.1.1)
-      activestorage (= 6.1.1)
-      activesupport (= 6.1.1)
+    actiontext (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activerecord (= 6.1.3.2)
+      activestorage (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
       nokogiri (>= 1.8.5)
-    actionview (6.1.1)
-      activesupport (= 6.1.1)
+    actionview (6.1.3.2)
+      activesupport (= 6.1.3.2)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activejob (6.1.1)
-      activesupport (= 6.1.1)
+    activejob (6.1.3.2)
+      activesupport (= 6.1.3.2)
       globalid (>= 0.3.6)
-    activemodel (6.1.1)
-      activesupport (= 6.1.1)
-    activerecord (6.1.1)
-      activemodel (= 6.1.1)
-      activesupport (= 6.1.1)
-    activestorage (6.1.1)
-      actionpack (= 6.1.1)
-      activejob (= 6.1.1)
-      activerecord (= 6.1.1)
-      activesupport (= 6.1.1)
-      marcel (~> 0.3.1)
-      mimemagic (~> 0.3.2)
-    activesupport (6.1.1)
+    activemodel (6.1.3.2)
+      activesupport (= 6.1.3.2)
+    activerecord (6.1.3.2)
+      activemodel (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+    activestorage (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activejob (= 6.1.3.2)
+      activerecord (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      marcel (~> 1.0.0)
+      mini_mime (~> 1.0.2)
+    activesupport (6.1.3.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -71,86 +72,92 @@ GEM
     coderay (1.1.3)
     concurrent-ruby (1.1.8)
     crass (1.0.6)
-    database_cleaner (1.8.5)
+    dalli (2.7.11)
+    database_cleaner (2.0.1)
+      database_cleaner-active_record (~> 2.0.0)
+    database_cleaner-active_record (2.0.1)
+      activerecord (>= 5.a)
+      database_cleaner-core (~> 2.0.0)
+    database_cleaner-core (2.0.1)
     erubi (1.10.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
-    i18n (1.8.7)
+    i18n (1.8.10)
       concurrent-ruby (~> 1.0)
-    loofah (2.9.0)
+    loofah (2.9.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
       mini_mime (>= 0.1.1)
-    marcel (0.3.3)
-      mimemagic (~> 0.3.2)
+    marcel (1.0.1)
     method_source (1.0.0)
-    mimemagic (0.3.5)
-    mini_mime (1.0.2)
-    minitest (5.14.3)
-    nio4r (2.5.4)
-    nokogiri (1.11.1-x86_64-linux)
+    mini_mime (1.0.3)
+    minitest (5.14.4)
+    nio4r (2.5.7)
+    nokogiri (1.11.6-x86_64-linux)
       racc (~> 1.4)
+    oj (3.11.5)
     parallel (1.20.1)
-    parser (3.0.0.0)
+    parser (3.0.1.1)
       ast (~> 2.4.1)
-    pry (0.13.1)
+    pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
     racc (1.5.2)
     rack (2.2.3)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
-    rails (6.1.1)
-      actioncable (= 6.1.1)
-      actionmailbox (= 6.1.1)
-      actionmailer (= 6.1.1)
-      actionpack (= 6.1.1)
-      actiontext (= 6.1.1)
-      actionview (= 6.1.1)
-      activejob (= 6.1.1)
-      activemodel (= 6.1.1)
-      activerecord (= 6.1.1)
-      activestorage (= 6.1.1)
-      activesupport (= 6.1.1)
+    rails (6.1.3.2)
+      actioncable (= 6.1.3.2)
+      actionmailbox (= 6.1.3.2)
+      actionmailer (= 6.1.3.2)
+      actionpack (= 6.1.3.2)
+      actiontext (= 6.1.3.2)
+      actionview (= 6.1.3.2)
+      activejob (= 6.1.3.2)
+      activemodel (= 6.1.3.2)
+      activerecord (= 6.1.3.2)
+      activestorage (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
       bundler (>= 1.15.0)
-      railties (= 6.1.1)
+      railties (= 6.1.3.2)
       sprockets-rails (>= 2.0.0)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
     rails-html-sanitizer (1.3.0)
       loofah (~> 2.3)
-    railties (6.1.1)
-      actionpack (= 6.1.1)
-      activesupport (= 6.1.1)
+    railties (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
       method_source
       rake (>= 0.8.7)
       thor (~> 1.0)
     rainbow (3.0.0)
     rake (13.0.3)
+    redis (4.2.5)
     regexp_parser (2.1.1)
-    rexml (3.2.4)
-    rubocop (1.11.0)
+    rexml (3.2.5)
+    rubocop (1.15.0)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.2.0, < 2.0)
+      rubocop-ast (>= 1.5.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.4.1)
-      parser (>= 2.7.1.5)
-    rubocop-minitest (0.10.3)
-      rubocop (>= 0.87, < 2.0)
-    rubocop-performance (1.9.2)
-      rubocop (>= 0.90.0, < 2.0)
+    rubocop-ast (1.6.0)
+      parser (>= 3.0.1.1)
+    rubocop-minitest (0.12.1)
+      rubocop (>= 0.90, < 2.0)
+    rubocop-performance (1.11.3)
+      rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
-    rubocop-rails (2.9.1)
+    rubocop-rails (2.10.1)
       activesupport (>= 4.2.0)
       rack (>= 1.1)
-      rubocop (>= 0.90.0, < 2.0)
+      rubocop (>= 1.7.0, < 2.0)
     rubocop-rake (0.5.1)
       rubocop
     ruby-progressbar (1.11.0)
@@ -166,7 +173,7 @@ GEM
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.0.0)
-    websocket-driver (0.7.3)
+    websocket-driver (0.7.4)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
     zeitwerk (2.4.2)
@@ -176,11 +183,13 @@ PLATFORMS
 
 DEPENDENCIES
   ar_cache!
+  dalli
   database_cleaner
   minitest
   pry
   rails
   rake
+  redis
   rubocop
   rubocop-minitest
   rubocop-performance

data/README.md

@@ -1,4 +1,4 @@
-# ArCache
+# ArCache (This is outdated, please see [中文文档](README.zh-CN.md))
 
 ![Test Status](https://github.com/OuYangJinTing/ar_cache/workflows/CI/badge.svg)
 [![Gem Version](https://badge.fury.io/rb/ar_cache.svg)](https://badge.fury.io/rb/ar_cache)
@@ -16,7 +16,7 @@ then query the database and write the result to the cache.
 - `Read cache`: Automatically intercept ActiveRecord queries, then try to fetch data from cache.
 - `Write cache`: If the query is cacheable and the cached data is not exists, it will be automatically written to the cache after the query.
 - `Expire cache`: Automatically expire cache after updated/modified data.
-- `Iterative cache`: The cache version will be updated after table fields, `ArCache` switch or `ArCache` coder changed.
+- `Iterative cache`: The cache version will be updated after table fields or `ArCache` switch changed.
 - `Shared cache`: The cache is not only used with ActiveRecord, you can easily use it in other places.([see examples](examples))
 
 ## Installation
@@ -55,11 +55,11 @@ rake db:migrate
 
 Skip cache:
 
-- `ArCache#skip`, eg:
+- `ArCache#skip_cache`, eg:
 
 ```ruby
 # All queries in the block will not use the cache.
-ArCache.skip { User.find(1) }
+ArCache.skip_cache { User.find(1) }
 ```
 
 - `ActiveRecord::Persistence#reload`, eg:

data/README.zh-CN.md

@@ -0,0 +1,165 @@
+# ArCache
+
+![Test Status](https://github.com/OuYangJinTing/ar_cache/workflows/CI/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/ar_cache.svg)](https://badge.fury.io/rb/ar_cache)
+
+`ArCache` 是一个现代的 `ActiveRecord` 查询缓存库，它受 [`cache-money`](https://github.com/ngmoco/cache-money) 和 [`second_level_cache`](https://github.com/hooopo/second_level_cache) 的启发而创作。  
+当 `ActiveRecord` 实例化查询条件命中唯一索引时，`ArCache` 会拦截此次查询，尝试从缓存中获取结果；如果缓存缺失，
+将在 `ActiveRecord` 查询完成后自动填充缓存。  
+`ArCache` 会自动维护缓存的正确性。
+
+## 特点
+
+- **低影响**：如果项目里数据库操作的相关代码符合 `ActiveRecord` 风格的话，那么你可以直接引入 `ArCache`，无需修改任何代码。（[详细](#警告)）
+- **读缓存**：当实例化查询的条件命中唯一索引时，`ArCache` 会尝试从缓存中获取结果返回。
+- **写缓存**：当读缓存操作没有获取到结果时，`ArCache` 会在 `ActiveRecord` 查询操作结束后，写入缓存。
+- **删缓存**：在更新或删除数据后，`ArCache` 会自动移除对应的缓存。
+- **迭代缓存**：当表结构发生改变后，`ArCache` 会更新这个表对应的缓存版本。
+- **共享缓存**：`ArCache` 里面缓存是完整表字段与数据的哈希结果的 `json` 序列化字符串（仅当使用 `redis/memcached` 作为存储器时），因此缓存的使用是没有局限的。（[实例](examples)）
+
+## 安装
+
+向项目的 `Gemfile` 文件里增加一行内容：
+
+```ruby
+gem 'ar_cache'
+```
+
+之后，执行：
+
+```shell
+bundle install
+```
+
+## 初始化配置文件
+
+如果是 `rails` 项目，直接执行命令：
+
+```shell
+rails generate ar_cache:install
+```
+
+不是，则将 [configuration.rb](lib/generators/ar_cache/templates/configuration.rb) 文件手动复制到项目对应的目录。
+
+## 配置项
+
+关于配置项的说明，请直接查看 [configuration.rb](lib/generators/ar_cache/templates/configuration.rb) 文件.
+
+## 用法
+
+只需要了解如何删除缓存和跳过缓存即可。
+
+删除缓存：
+
+- `ArCache::Table#delete`, 例如：
+
+```ruby
+User.ar_cache_table.delete(id...)
+User.first.ar_cache_table.delete(id...)
+```
+
+跳过缓存：
+
+- `ArCache#skip_cache`, 例如：
+
+```ruby
+ArCache.skip_cache do
+  # 块里面的全部查询将跳过缓存
+end
+```
+
+- `ActiveRecord::Persistence#reload`, 例如：
+
+```ruby
+User.find(1).reload
+```
+
+- `ActiveRecord::Relation#reload`, 例如：
+
+```ruby
+# 当 relation 已加载查询后，再调用 reload 方法时，将跳过缓存 
+User.where(id: 1).load.reload
+```
+
+- `ActiveRecord::Associations::Association#reload`, 例如：
+
+```ruby
+# 当关联对象已加载查询后，再调用 reload 方法时，将跳过缓存 
+user.association(:account).load_target.reload
+```
+
+## 可读缓存的查询
+
+必须满足下列全部条件:
+
+- 使用哈希作为查询条件
+- 查询条件包含唯一索引
+- 没有事务存在，或者事务里面没有查询表的更新或删除操作（后续会尝试解除这个限制）
+- 没有调用过 `select` 方法，或者 `select` 字段都是表字段
+- 没有调用过 `order/order!` 方法，或者 `order` 字段只有一个，并且该字段是表字段
+- 没有调用过 `limit/limit!` 方法，或者查询条件只能命中一个结果
+- 没有调用过 `skip_query_cache!` 方法
+- 没有调用过 `lock/lock!` 方法
+- 没有调用过 `distinct/distinct!` 方法
+- 没有调用过 `group/group!` 方法
+- 没有调用过 `joins/joins!` 方法
+- 没有调用过 `left_outer_joins/left_outer_joins!` 方法
+- 没有调用过 `offset/offset!` 方法
+- 没有调用过 `eager_load/eager_load!` 方法
+- 没有调用过 `references/references!` 方法
+- 没有调用过 `from/from!` 方法
+- ...
+
+```ruby
+User.find(1) # 主键查询是可读缓存的
+User.where(email: 'foobar@gmail.com') # 唯一索引查询是可读缓存的
+User.where(id: [1, 2]) # 唯一索引有多个值的情况，依然是可读缓存的
+User.where(name: 'foobar', status: :active) # 联合字段的唯一索引查询是可读缓存的
+User.includes(:account).where(id: [1, 2]) # ActiveRecord 的预加载是可读缓存的（仅当为 has_one 关联时）
+User.first.account # ActiveRecord 的关联对象是可读缓存的（仅当为 has_one 关联时）
+```
+
+注意: `has_many` 的关联缓存，目前是不支持的，后续会尝试支持，但希望不大。
+
+## 缓存迭代
+
+`ArCache` 的缓存是以表为层级的，当触发缓存迭代后，这个表的全部缓存都会失效，导致一种类似缓存雪崩的情况，请特别注意。
+下述的这些情况会导致缓存迭代：
+
+- 表结构发生变化
+- 激活/禁用 `ArCache`
+- 使用 `ActiveRecord::Persistence::ClassMethods#upsert_all` 方法
+
+## 注意事项
+
+- `ArCache` 的缓存清除操作，是在事务提交或 `sql` 操作结束后开始的，这意味是可能出现脏读的（后续会尝试解决）。
+- `ArCache` 缓存数据是完整的表行数据，因此当 `sql` 包含 `select` 字段，并且缓存缺失时，`ArCache` 会将其改成 `select *`，但最终实例化的对象依旧符合预期。
+- 当使用跳过 `ActiveReord` 的回调方法，更新/删除数据时，`ArCache` 可能会多执行一条 `select primary_key` 的 `sql`，因为清除缓存需要 `primary_key` 数据。
+
+## 警告
+
+下述的这些情况都是严禁发生的行为，这些行为会导致 `ArCache` 的缓存正确性。  
+PS：`ActiveRecord` 使用者，不应该写出这些代码。
+
+- 直接使用 `execute` 方法 更新/删除 数据。
+- 直接使用比 `execute` 更底层方式，更新/删除 数据。
+- 跳过 `ActiveRecord` 直接 更新/删除 数据。（后续会提供数据库触发器来解除这个限制）
+
+如果这些行为无法避免的话，请按照上述[删除缓存](#用法)的方法，手动删除受影响的缓存数据，或者干脆直接禁止对应表的 `ArCache` 功能。
+
+## 其它类似的库
+
+这里还有一些其它的 `gem`，也提供了 `ActiveRecord` 的查询缓存功能。
+
+- [identity_cache](https://github.com/Shopify/identity_cache)
+- [second_level_cache](https://github.com/hooopo/second_level_cache)
+- [cache-money](https://github.com/ngmoco/cache-money)
+
+`ArCache` 跟他们存在一些下述的差异：
+
+- `ArCache` 不依赖 `ActiveRecord` 的 `commit` 回调，所以你可以无所顾虑的直接使用跳过回调的方法。
+- `ArCache` 的缓存是 `json` 序列化，不是 `Marshal` 序列化，所以缓存的使用是没有局限的。（仅当使用 `redis/memcached` 作为存储器时）
+- `ArCache` 自动代理了标准的 `ActiveRecord` 实例化查询请求，所以不需要额外学习怎么使用缓存。
+- `ArCache` 缓存是懒写入的，因此新创建的数据，不会直接写入缓存。
+- `ArCache` 不会热更新缓存，因此数据被更新后，缓存就没有了。
+- ...