ar_cache 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09eeda930c7263476f3b09e53747f9ec87ac070e65f18031856cdb05ad57a083'
-  data.tar.gz: 425c321debdcc05d81d4c0815abecb0d9e19fa417bb251265ba6dab420dd03e1
+  metadata.gz: d4d25cbd1abb845a90dbd29d50d1dfb5b622e454e6c0bfe4a1ae65b4eddb818f
+  data.tar.gz: 821f3036d2df0db1f143a3212cffacf306ac30aa2335385defde6b41edf5f46d
 SHA512:
-  metadata.gz: 827f0ecdf9e583870a454c16cfaa44c95b9d7b0ba4f3942097daf1c76fed218adfdafcd5733b68fa6476297c8b6d35c728e1a1b6f66db615d9fde834183ea4e8
-  data.tar.gz: 273bef3daea68391d681045c384488bf9266a1f75cd5ea7057b6aaf70928ebe97934cb65daadf3f6a3442177d948923116867be503f479c6ac8ab06ac23bb286
+  metadata.gz: a0a9706501fa606ee7cf02931bdbfc5efd3e2668fb5b51c55b971d616233b43595363b30ccf279d500df64789268398c140870c8683b7e79e8b70717ebd2983a
+  data.tar.gz: 46e0a6c9a76401dec6d2f3c11f52e4e9a3e0d1b975c827df7eca05f0068612d78755238db00c5f170ab30523c5aee15eb6556b3956599490d0a812d4f8d917d5

data/CHANGELOG.md

@@ -1,13 +1,3 @@
 # Change log
 
 ## main
-
-## 1.0.0 (2021-03-02)
-
-- Initial version.
-
-## 1.1.0 (2021-03-11)
-
-- Fully automatic delete cache when call delete_all/update_all method.
-- Optimize has_one(through:) cache implementation.
-- ActiveRecord::Relation#reload and ActiveRecord::Associations::Association#reload should skip read cache if associated target is already loaded.

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.1.0)
+    ar_cache (2.0.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,17 +55,31 @@ rake db:migrate
 
 Skip cache:
 
+- `ArCache#skip_cache`, eg:
+
+```ruby
+# All queries in the block will not use the cache.
+ArCache.skip_cache { User.find(1) }
+```
+
 - `ActiveRecord::Persistence#reload`, eg:
 
 ```ruby
 User.find(1).reload
 ```
 
-- `ActiveRecord::Relation#skip_ar_cache`, eg:
+- `ActiveRecord::Relation#reload`, eg:
+
+```ruby
+# When reload is called after the associated target has been loaded, the cache will be skipped.
+User.where(id: 1).load.reload
+```
+
+- `ActiveRecord::Associations::Association#reload`, eg:
 
 ```ruby
-User.skip_ar_cache.find(1)
-User.where(id: [1, 2]).skip_ar_cache.load
+# When reload is called after the associated target has been loaded, the cache will be skipped.
+user.association(:account).load_target.reload
 ```
 
 Delete cache:
@@ -91,7 +105,7 @@ If all the following conditions are met, ArCache will try to read the cache:
 - No call `#select` or select value is table column.
 - No call `#order` or order value is table column and only one.
 - No call `#limit` or value of the unique index isn't array.
-- No call `#joins`, `#left_joins`, `#skip_query_cache!`, `#skip_ar_cache`, `#explain`, `#from`, `#group`, `#offset`, `#lock`
+- No call `#joins`, `#left_joins`, `#skip_query_cache!`, `#explain`, `#from`, `#group`, `#offset`, `#lock`
 - ...
 
 **Cacheable example:**

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` 不会热更新缓存，因此数据被更新后，缓存就没有了。
+- ...