logidze 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f853c7aed1f6d284150d85530b3fdc0fb8f59b856a4d962e35004507cb8c7f7
-  data.tar.gz: 513c193a93b6ff059a27463ee96ab754cb88d995b74a8c73b2abf16441aad346
+  metadata.gz: 56aa14f81cc160897376ed2b226664fc3a93c5f4becedb7d5a45abd197d03388
+  data.tar.gz: 5e196a2ef847e0e1d6069e793fb726f35166f05be007d9c4e4cfde2318b2cd3a
 SHA512:
-  metadata.gz: 54443a9ddd4b9bea05a9f6e8acd5f0549c359f2476e93d6cb11452597ba8d0b2580b4ac3db78a0bc78e0ec01f368e9e8c6c0de08868e4d6e7679641515c22329
-  data.tar.gz: 27f28a1e2b8be8b9eb8095ef8ffd192e4397ff3389298cf290991fc76de7998f9c512fe1d153505dfdd6a69186b06365d5085c71d03472b573ec3c6cb3f523b3
+  metadata.gz: f8871956c3f1439fdd5cc3bb810e612a75145a49cf7f43a039b92915a2edc2ab57bb49a7bd5a4a14a48863696f37d8afcce4f052b2c620b01ffd5a179398fc30
+  data.tar.gz: 15440ace63434523644340155bd26bdb55acb906993b4b6014d1dd8d0f0e498d4e34709bc144bb3da260c8e509f336dc68c9100cc37568d3354d025a9d88cf39

data/.gitattributes

@@ -0,0 +1,3 @@
+assets/**/* linguist-vendored
+bench/**/* linguist-vendored
+.github/**/* linguist-vendored

data/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,20 @@
+<!--
+  This template is for bug reports. If you are reporting a bug, please continue on. If you are here for another reason, 
+  feel free to skip the rest of this template.
+-->
+
+### Tell us about your environment
+
+**Ruby Version:**
+
+**Rails Version:**
+
+**PostgreSQL Version:**
+
+**Logidze Version:**
+
+### What did you do?
+
+### What did you expect to happen?
+
+### What actually happened?

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+<!--
+  First of all, thanks for contributing!
+
+  If it's a typo fix or minor documentation update feel free to skip the rest of this template!
+-->
+
+<!--
+  If it's a bug fix, then link it to the issue, for example:
+
+  Fixes #xxx
+-->
+
+
+<!--
+  Otherwise, describe the changes: 
+
+### What is the purpose of this pull request?
+
+### What changes did you make? (overview)
+
+### Is there anything you'd like reviewers to focus on?
+
+### Checklist
+
+- [ ] I've added tests for this change
+- [ ] I've added a Changelog entry
+- [ ] I've updated a documentation (Readme)
+
+-->

data/.rubocop.yml

@@ -1,94 +1,55 @@
 require:
+  - standard/cop/semantic_blocks
   - rubocop-md
 
+inherit_gem:
+  standard: config/base.yml
+
 AllCops:
-  # Include gemspec and Rakefile
-  Include:
-    - 'lib/**/*.rb'
-    - 'lib/**/*.rake'
-    - 'spec/**/*.rb'
   Exclude:
-    - 'bin/**/*'
-    - 'spec/dummy/**/*'
-    - 'vendor/**/*'
-    - 'gemfiles/**/*'
+    - 'bin/*'
     - 'tmp/**/*'
-    - 'bench/**/*'
-    - 'Rakefile'
+    - 'docs/**/*'
     - 'Gemfile'
-    - '*.gemspec'
+    - 'vendor/**/*'
+    - 'gemfiles/**/*'
   DisplayCopNames: true
-  StyleGuideCopsOnly: false
-  TargetRubyVersion: 2.3
-
-Naming/AccessorMethodName:
-  Enabled: false
-
-Naming/UncommunicativeMethodParamName:
-  Enabled: false
+  TargetRubyVersion: 2.4
 
-Style/TrivialAccessors:
+Standard/SemanticBlocks:
   Enabled: false
 
-Style/Documentation:
-  Exclude:
-    - 'spec/**/*.rb'
-
-Style/StringLiterals:
-  Enabled: false
-
-Layout/SpaceInsideStringInterpolation:
-  EnforcedStyle: no_space
-
-Style/BlockDelimiters:
-  Exclude:
-    - 'spec/**/*.rb'
+Style/FrozenStringLiteralComment:
+  Enabled: true
 
-Style/PercentLiteralDelimiters:
-  Enabled: false
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: no_comma
 
-Lint/AmbiguousRegexpLiteral:
-  Enabled: false
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: no_comma
 
-Lint/MissingCopEnableDirective:
-  Enabled: false
+Layout/AlignParameters:
+  EnforcedStyle: with_first_parameter
 
-Lint/UselessAssignment:
+Lint/Void:
   Exclude:
     - '**/*.md'
 
-Metrics/MethodLength:
+# See https://github.com/rubocop-hq/rubocop/issues/4222
+Lint/AmbiguousBlockAssociation:
   Exclude:
-    - 'spec/**/*.rb'
+    - 'spec/**/*'
+    - '**/*.md'
 
-Metrics/BlockLength:
+Lint/DuplicateMethods:
   Exclude:
-    - 'spec/**/*.rb'
+    - '**/*.md'
 
-Metrics/LineLength:
-  Max: 100
+Naming/FileName:
   Exclude:
-    - 'spec/**/*.rb'
-
-Rails/Date:
-  Enabled: false
-
-Rails/TimeZone:
-  Enabled: false
-
-Style/NumericLiteralPrefix:
-  Enabled: false
+    - 'lib/test-prof.rb'
+    - '**/*.md'
 
-Lint/HandleExceptions:
-  Enabled: true
+Layout/InitialIndentation:
   Exclude:
-    - 'spec/**/*.rb'
-
-Layout/DotPosition:
-  EnforcedStyle: leading
-
-Layout/IndentHeredoc:
-  Enabled: false
-
-Layout/EmptyLineAfterMagicComment:
-  Enabled: false
+    - 'CHANGELOG.md'

data/.travis.yml

@@ -4,6 +4,9 @@ cache: bundler
 dist: trusty
 sudo: false
 
+notifications:
+  email: false
+
 addons:
   postgresql: "9.6"
 
@@ -16,21 +19,21 @@ before_script:
   - gem update --system
   - bundle exec rake dummy:db:create
   - psql -U postgres -d logidze -c 'CREATE EXTENSION IF NOT EXISTS hstore;'
-  - bundle exec rake dummy:db:test:prepare
+  - RAILS_ENV=test bundle exec rake dummy:db:create dummy:db:migrate
 
 matrix:
   include:
     - rvm: ruby-head
       gemfile: gemfiles/railsmaster.gemfile
-    - rvm: 2.5.0
-      gemfile: gemfiles/railsmaster.gemfile
-    - rvm: 2.5.0
+    - rvm: 2.6.2
+      gemfile: gemfiles/rails6.gemfile
+    - rvm: 2.6.2
       gemfile: gemfiles/rails5.gemfile
     - rvm: 2.5.1
       gemfile: gemfiles/rails52.gemfile
     - rvm: 2.4.1
       gemfile: gemfiles/rails5.gemfile
-    - rvm: 2.3.1
+    - rvm: 2.4.1
       gemfile: gemfiles/rails42.gemfile
   allow_failures:
     - rvm: ruby-head

data/CHANGELOG.md

@@ -1,6 +1,40 @@
 # Change log
 
-## master
+## master (unreleased)
+
+## 0.10.0 (2019-05-15)
+
+- **Ruby >= 2.4 is required**
+
+- PR [#111](https://github.com/palkan/logidze/pull/111) Global configuration for `:ignore_log_data` option ([@dmitrytsepelev][])
+
+Now it's possible to avoid loading `log_data` from the DB by default with
+
+```ruby
+Logidze.ignore_log_data_by_default = true
+```
+
+In cases when `ignore_log_data: false` is explicitly passed to the `ignore_log_data` the default setting is being overriden. Also, it's possible to change it inside the block:
+
+```ruby
+Logidze.with_log_data do
+  Post.find(params[:id]).log_data
+end
+```
+
+- PR [#110](https://github.com/palkan/logidze/pull/110) Add `reset_log_data` API to nullify log_data column ([@Arkweid][])
+
+Usage:
+
+Reset the history for a record (or records):
+
+```ruby
+# for single record
+record.reset_log_data
+
+# for relation
+User.where(active: true).reset_log_data
+```
 
 ## 0.9.0 (2018-11-28)
 

data/Gemfile

@@ -4,6 +4,8 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in logidze.gemspec
 gemspec
 
+gem "pry-byebug", platform: :mri
+
 local_gemfile = "#{File.dirname(__FILE__)}/Gemfile.local"
 
 if File.exist?(local_gemfile)

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 palkan
+Copyright (c) 2016-2019 palkan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -14,7 +14,7 @@ Currently, only PostgreSQL 9.5+ is supported (for PostgreSQL 9.4 try [jsonbx](ht
 
 Other requirements:
 - Ruby ~> 2.1
-- Rails >= 4.2
+- Rails >= 4.2 (**Rails 6 is supported**)
 
 <a href="https://evilmartians.com/">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
@@ -24,7 +24,7 @@ Other requirements:
 Add Logidze to your application's Gemfile:
 
 ```ruby
-gem 'logidze'
+gem "logidze"
 ```
 
 Install required DB extensions and create trigger function:
@@ -33,7 +33,7 @@ Install required DB extensions and create trigger function:
 rails generate logidze:install
 ```
 
-This creates migration for adding trigger function and enabling hstore extension.
+This creates a migration for adding trigger function and enabling the hstore extension.
 
 Run migrations:
 
@@ -57,13 +57,13 @@ rake db:migrate
 
 This also adds `has_logidze` line to your model, which adds methods for working with logs.
 
-You can provide `limit` option to `generate` to limit the size of the log (by default it's unlimited):
+You can provide the `limit` option to `generate` to limit the size of the log (by default it's unlimited):
 
 ```sh
 rails generate logidze:model Post --limit=10
 ```
 
-To backfill table data (i.e. create initial snapshots) add `backfill` option:
+To backfill table data (i.e., create initial snapshots) add `backfill` option:
 
 ```sh
 rails generate logidze:model Post --backfill
@@ -78,7 +78,7 @@ rails generate logidze:model Post --blacklist=created_at active
 rails generate logidze:model Post --whitelist=title body
 ```
 
-By default, Logidze tries to infer the path to the model file from the model name and may fail, for example, if you have unconventional project structure. In that case you should specify the path explicitly:
+By default, Logidze tries to infer the path to the model file from the model name and may fail, for example, if you have unconventional project structure. In that case, you should specify the path explicitly:
 
 ```sh
 rails generate logidze:model Post --path "app/models/custom/post.rb"
@@ -101,7 +101,7 @@ If you want to update Logidze settings for the model, run migration with `--upda
 rails generate logidze:model Post --update --whitelist=title body rating
 ```
 
-Logidze also supports associations versioning. It is experimental feature, and disabled by default. You can learn more
+Logidze also supports associations versioning. It is an experimental feature and disabled by default. You can learn more
 in the [wiki](https://github.com/palkan/logidze/wiki/Associations-versioning).
 
 ## Troubleshooting
@@ -118,7 +118,7 @@ Nevertheless, you still need super-user privileges to enable `hstore` extension
 
 ## Upgrade from previous versions
 
-We try to make upgrade process as simple as possible. For now, the only required action is to create and run a migration:
+We try to make an upgrade process as simple as possible. For now, the only required action is to create and run a migration:
 
 ```sh
 rails generate logidze:install --update
@@ -128,7 +128,7 @@ This updates core `logdize_logger` DB function. No need to update tables or trig
 
 ## Usage
 
-Your model now has `log_data` column which stores changes log.
+Your model now has `log_data` column, which stores changes log.
 
 To retrieve record version at a given time use `#at` or `#at!` methods:
 
@@ -142,13 +142,13 @@ post.log_version #=> 3
 post.log_size #=> 3
 
 # Get copy of a record at a given time
-old_post = post.at(time: 2.days.ago)
+post.at(time: 2.days.ago)
 
 # or revert the record itself to the previous state (without committing to DB)
-post.at!(time: '201-04-15 12:00:00')
+post.at!(time: "2018-04-15 12:00:00")
 
 # If no version found
-post.at(time: '1945-05-09 09:00:00') #=> nil
+post.at(time: "1945-05-09 09:00:00") #=> nil
 ```
 
 You can also get revision by version number:
@@ -192,38 +192,68 @@ You can initiate reloading of `log_data` from the DB:
 post.reload_log_data # => returns the latest log data value
 ```
 
-Normally, if you update record after `#undo!` or `#switch_to!` you lose all "future" versions and `#redo!` is no
+Typically, if you update record after `#undo!` or `#switch_to!` you lose all "future" versions and `#redo!` is no
 longer possible. However, you can provide an `append: true` option to `#undo!` or `#switch_to!`, which will
 create a new version with old data. Caveat: when switching to a newer version, `append` will have no effect.
 
 ```ruby
-post = Post.create!(title: 'first post') # v1
-post.update!(title: 'new title')         # v2
+post = Post.create!(title: "first post") # v1
+post.update!(title: "new title")         # v2
 post.undo!(append: true)                 # v3 (with same attributes as v1)
 ```
 
 Note that `redo!` will not work after `undo!(append: true)` because the latter will create a new version
 instead of rolling back to an old one.
-Alternatively, you can configure Logidze to always default to `append: true`.
+Alternatively, you can configure Logidze always to default to `append: true`.
 
 ```ruby
 Logidze.append_on_undo = true
 ```
 
-If you want to reduce the data loaded from the DB, you can turn off automatic loading of `log_data` column in the following way:
+### How to not load log data by default, or dealing with large logs
+
+By default, Active Record _selects_ all the table columns when no explicit `select` statement specified.
+
+That could slow down queries execution if you have field values which exceed the size of the data block (typically 8KB). PostgreSQL turns on its [TOAST](https://wiki.postgresql.org/wiki/TOAST) mechanism), which requires reading from multiple physical locations for fetching the row's data.
+
+If you do not use compaction (`generate logidze:model ... --limit N`) for `log_data`, you're likely to face this problem.
+
+Logidze provides a way to avoid loading `log_data` by default (and load it on demand):
 
 ```ruby
 class User < ActiveRecord::Base
+  # Add `ignore_log_data` option to macros
   has_logidze ignore_log_data: true
 end
 ```
 
-After that, each time you use `User.all` (or any other relation method) `log_data` won't be loaded from the DB. If you try to call `#log_data` on the model loaded in a such way, you'll get `ActiveModel::MissingAttributeError`, but if you really need it (e.g. during the console debugging) - use `user.reload_log_data`, which forces loading the column from the DB. If you need to select `log_data` during the initial load - use a special scope `User.with_log_data`.
+If you want Logidze always to behave this way - you can set up a global configuration option:
+
+```ruby
+Rails.application.config.logidze.ignore_log_data_by_default = true
+```
+
+However, you can override it by explicitly passing `ignore_log_data: false` to the `ignore_log_data`. Also, it's possible to change it temporary inside the block:
+
+```ruby
+Logidze.with_log_data do
+  Post.find(params[:id]).log_data
+end
+```
 
+When `ignore_log_data` is turned on, each time you use `User.all` (or any other Relation method) `log_data` won't be loaded from the DB.
+
+The chart below shows the difference in PG query time before and after turning `ignore_log_data` on. (Special thanks to [@aderyabin](https://github.com/aderyabin) for sharing it.)
+
+![](./assets/pg_log_data_chart.png)
+
+If you try to call `#log_data` on the model loaded in such way, you'll get `ActiveModel::MissingAttributeError`, but if you really need it (e.g., during the console debugging) - use **`user.reload_log_data`**, which forces loading the column from the DB.
+
+If you need to select `log_data` during the initial load-use a special scope `User.with_log_data`.
 
 ## Track meta information
 
-You can store any meta information you want inside your version (it could be IP address, user agent etc). In order to add it you should wrap your code with a block:
+You can store any meta information you want inside your version (it could be IP address, user agent, etc.). To add it you should wrap your code with a block:
 
 ```ruby
 Logidze.with_meta(ip: request.ip) do
@@ -251,7 +281,7 @@ And then to retrieve `responsible_id`:
 post.log_data.responsible_id
 ```
 
-Logidze does not require `responsible_id` to be `SomeModel` ID. It can be anything. Thus Logidze does not provide methods for retrieving the corresponding object. However, you can easy write it yourself:
+Logidze does not require `responsible_id` to be `SomeModel` ID. It can be anything. Thus Logidze does not provide methods for retrieving the corresponding object. However, you can easily write it yourself:
 
 ```ruby
 class Post < ActiveRecord::Base
@@ -268,9 +298,9 @@ And in your controller:
 
 ```ruby
 class ApplicationController < ActionController::Base
-  around_action :set_logidze_responsible, only: %i[create update]
+  around_action :use_logidze_responsible, only: %i[create update]
 
-  def set_logidze_responsible(&block)
+  def use_logidze_responsible(&block)
     Logidze.with_responsible(current_user&.id, &block)
   end
 end
@@ -278,7 +308,7 @@ end
 
 ## Disable logging temporary
 
-If you want to make update without logging (e.g. mass update), you can turn it off the following way:
+If you want to make update without logging (e.g., mass update), you can turn it off the following way:
 
 ```ruby
 Logidze.without_logging { Post.update_all(seen: true) }
@@ -288,6 +318,18 @@ Logidze.without_logging { Post.update_all(seen: true) }
 Post.without_logging { Post.update_all(seen: true) }
 ```
 
+## Reset log
+
+Reset the history for a record (or records):
+
+```ruby
+# for a single record
+record.reset_log_data
+
+# for relation
+User.where(active: true).reset_log_data
+```
+
 ## Log format
 
 The `log_data` column has the following format:
@@ -314,7 +356,7 @@ The `log_data` column has the following format:
 }
 ```
 
-If you specify the limit in the trigger definition then log size will not exceed the specified size. When a new change occurs, and there is no more room for it, the two oldest changes will be merged.
+If you specify the limit in the trigger definition, then log size will not exceed the specified size. When a new change occurs, and there is no more room for it, the two oldest changes will be merged.
 
 ## Development
 
@@ -324,8 +366,7 @@ For development setup run `./bin/setup`. This runs `bundle install` and creates
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/logidze.
 
-
-## TODO
+## Future ideas
 
 - Enhance update_all to support mass-logging.
 - Other DB adapters.