logidze 0.8.1 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 571e06644d88083ccf41f25a69c13530436055233406337c7458f8cdbb6d86f0
-  data.tar.gz: f7301fee68a37cfb436a2b3f1ad80ebb8e375b8bc936ee39894f036273edbf35
+  metadata.gz: 747454e7c38a1969f39ed1f4b9d9142b2afc48d7ed7c34534b82abcac88dc4d7
+  data.tar.gz: 2522172435f01b7d4441479f5f0c3e1bf08cde1f36e6ac9c745c8c8a20bd1d6f
 SHA512:
-  metadata.gz: 4430563010f78a5f467fad89a260ba0a299d5ac892d4ca63728f4a0dd1ff2e7cb210fa05c2aba513298fd069fbd951c930aeedfd2f401e9e15af1cde6081a302
-  data.tar.gz: 336576627fc5c4b54fadcc531406579328497bff61b4db47973a442b6b7ae0710d7f0f953da360dbe0f4e22abfeeadfe411c342919d0ab212a73bfae7a2731b5
+  metadata.gz: cbbcbe791ca4f682f75c188c0b65db6f8244dea84a6cb5390a85c980921f1f84bf3676962dbb5792cf5ac2d7a24f0dbf1ac6b916f7bf03a1a13a1820ebc89507
+  data.tar.gz: 4514014a739bc452aa7ad8fb26495a96aa651bfa3c8c4784021c1e2d13874c003c57e24b28ac6397f5ca5239e4e65dd76f0565df7af69ad29bbc8dd63630cc8b

data/CHANGELOG.md

@@ -1,6 +1,123 @@
 # Change log
 
-## master
+## master (unreleased)
+
+## 1.0.0.rc1 (2020-09-01)
+
+- Add `.with_full_snapshot` to add full snapshots to the log instead of diffs. ([@palkan][])
+
+Useful in combination with `.without_logging`: first, you perform multiple updates without logging, then
+you do something like `with_full_snapshot { record.touch }` to create a log entry with the current state.
+
+- Add `#create_logidze_snapshot!` and `.create_logidze_snapshot` methods. ([@palkan][])
+
+- Add integration with `fx` gem. ([@palkan][])
+
+Now it's possible to use Logidze with `schema.rb`. Add `fx` gem to the project, and new migrations will be
+using Fx `create_function` / `create_trigger` functions.
+
+- Refactored columns filtering. ([@palkan][])
+
+Renamed `--whitelist/--blacklist` to `--only/--except` correspondingly.
+
+The _only_-logic has been changed: previously we collected the list of columns to ignore at the migration generation time,
+now we filter the columns within the trigger function (thus, schema changes do not affect the columns being tracked).
+
+- **Dropped support for Rails 4.2, Ruby 2.4 and PostgreSQL 9.5**. ([@palkan][])
+
+## 0.12.0 (2020-01-02)
+
+- PR [#143](https://github.com/palkan/logidze/pull/143) Add `:transactional` option to `#with_meta` and `#with_responsible` ([@oleg-kiviljov][])
+
+Now it's possible to set meta and responsible without wrapping the block into a DB transaction. For backward compatibility  `:transactional` option by default is set to `true`.
+
+Usage:
+
+```ruby
+Logidze.with_meta({ip: request.ip}, transactional: false) do
+  post.save!
+end
+```
+
+or
+
+```ruby
+Logidze.with_responsible(user.id, transactional: false) do
+  post.save!
+end
+```
+
+## 0.11.0 (2019-08-15)
+
+- **Breaking** Return `nil` when `log_data` is not loaded instead of raising an exception. ([@palkan][])
+
+We cannot distinguish between not loaded `log_data` and not-yet-created (i.e. for new records).
+The latter could be used in frameworks/gems ([example](https://github.com/palkan/logidze/issues/127#issuecomment-518798640)).
+
+- **Breaking** Only allow specifying `ignore_log_data` at boot time without runtime modifications. ([@palkan][])
+
+Playing with ActiveRecord default scopes wasn't a good idea. We fallback to a more explicit way of _telling_ AR
+when to load or ignore the `log_data` column.
+
+This change removes `Logidze.with_log_data` method.
+
+## 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)
+
+- PR [#98](https://github.com/palkan/logidze/pull/98) Add `:ignore_log_data` option to `#has_logidze` ([@dmitrytsepelev][])
+
+Usage:
+
+```ruby
+class User < ActiveRecord::Base
+  has_logidze ignore_log_data: true
+end
+
+User.all #=> SELECT id, name FROM users
+
+User.with_log_data #=> SELECT id, name, log_data FROM users
+
+user = User.find(params[:id])
+user.log_data #=> ActiveModel::MissingAttributeError
+user.reload_log_data #=> Logidze::History
+```
+
+## 0.8.1 (2018-10-22)
+
+- [PR #93](https://github.com/palkan/logidze/pull/93)] Return 0 for log size when log_data is nil ([@duderman][])
 
 ## 0.8.0 (2018-10-01)
 
@@ -29,7 +146,7 @@ Please run `rails generate logidze:install --update` to regenerate stored functi
 This feature checks if several logs came in within a debounce time period then only keep the latest one
 by merging the latest in previous others.
 
-The concept is similar to https://underscorejs.org/#debounce
+The concept is similar to [https://underscorejs.org/#debounce](https://underscorejs.org/#debounce).
 
 without `debounce_time`
 
@@ -90,7 +207,7 @@ with `debounce_time` of `10ms`
 
 ## 0.7.0 (2018-08-29)
 
-- [Fixes [#75](https://github.com/palkan/logidze/issues/70)] Fix association versioning with an optional belongs to ([@ankursethi-uscis][])
+- [Fixes [#75](https://github.com/palkan/logidze/issues/70)] Fix association versioning with an optional belongs to ([@amalagaura][])
 
 - [PR [#79](https://github.com/palkan/logidze/pull/13)] Allow adding meta information to versions using `with_meta` (addressed [Issue [#60]](https://github.com/palkan/logidze/issues/60)). ([@DmitryTsepelev][])
 
@@ -158,7 +275,7 @@ This is a quick fix for a more general problem (see [#59](https://github.com/pal
 
 ## 0.5.1 (2017-06-15)
 
-- _(Fix)_ Drop _all_ created functions upon rolling back (https://github.com/palkan/logidze/commit/b8e150cc18b3316a8cf0c78f7117339481fb49c6). ([@vassilevsky][])
+- _(Fix)_ Drop _all_ created functions upon rolling back ([commit](https://github.com/palkan/logidze/commit/b8e150cc18b3316a8cf0c78f7117339481fb49c6)). ([@vassilevsky][])
 
 ## 0.5.0 (2017-03-28)
 
@@ -208,6 +325,8 @@ This is a quick fix for a more general problem (see [#59](https://github.com/pal
 [@charlie-wasp]: https://github.com/charlie-wasp
 [@akxcv]: https://github.com/akxcv
 [@vassilevsky]: https://github.com/vassilevsky
-[@ankursethi-uscis]: https://github.com/ankursethi-uscis
+[@amalagaura]: https://github.com/amalagaura
 [@dmitrytsepelev]: https://github.com/DmitryTsepelev
 [@zocoi]: https://github.com/zocoi
+[@duderman]: https://github.com/duderman
+[@oleg-kiviljov]: https://github.com/oleg-kiviljov

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 palkan
+Copyright (c) 2016-2020 Vladimir Dementyev
 
 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

@@ -1,134 +1,189 @@
-[![Cult Of Martians](http://cultofmartians.com/assets/badges/badge.svg)](http://cultofmartians.com) [![Gem Version](https://badge.fury.io/rb/logidze.svg)](https://rubygems.org/gems/logidze) [![Build Status](https://travis-ci.org/palkan/logidze.svg?branch=master)](https://travis-ci.org/palkan/logidze) [![Open Source Helpers](https://www.codetriage.com/palkan/logidze/badges/users.svg)](https://www.codetriage.com/palkan/logidze)
+[![Cult Of Martians](http://cultofmartians.com/assets/badges/badge.svg)](http://cultofmartians.com)
+[![Gem Version](https://badge.fury.io/rb/logidze.svg)](https://rubygems.org/gems/logidze)
+![Build](https://github.com/palkan/logidze/workflows/Build/badge.svg)
+[![Open Source Helpers](https://www.codetriage.com/palkan/logidze/badges/users.svg)](https://www.codetriage.com/palkan/logidze)
 
 # Logidze
 
-Logidze provides tools for logging DB records changes. Just like [audited](https://github.com/collectiveidea/audited) and [paper_trail](https://github.com/airblade/paper_trail) do (but [faster](bench/performance)).
+Logidze provides tools for logging DB records changes when using PostgreSQL (>=9.6). Just like [audited](https://github.com/collectiveidea/audited) and [paper_trail](https://github.com/airblade/paper_trail) do (but [faster](bench/performance)).
 
 Logidze allows you to create a DB-level log (using triggers) and gives you an API to browse this log.
 The log is stored with the record itself in JSONB column. No additional tables required.
-Currently, only PostgreSQL 9.5+ is supported (for PostgreSQL 9.4 try [jsonbx](http://www.pgxn.org/dist/jsonbx/1.0.0/) extension).
 
-[Read the story behind Logidze](https://evilmartians.com/chronicles/introducing-logidze?utm_source=logidze)
+**❗️ IMPORTANT:** This page contains documentation for the upcoming v1.0. For the latest release documentation see the [0-stable branch](https://github.com/palkan/logidze/tree/0-stable). If you're just starting with Logidze, we recommend using the latest release candidate (`1.0.0.rc1`).
 
-[How is Logidze pronounced?](https://github.com/palkan/logidze/issues/73)
+🤔 [How is Logidze pronounced?](https://github.com/palkan/logidze/issues/73)
 
 Other requirements:
-- Ruby ~> 2.1
-- Rails >= 4.2
+
+- Ruby ~> 2.5
+- Rails >= 5.0 (for Rails 4.2 use version <=0.12.0)
 
 <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>
 
+## Links
+
+- [Logidze: for all those tired of versioning data](https://evilmartians.com/chronicles/introducing-logidze?utm_source=logidze)
+
+## Table of contents
+
+- [Main concepts](#main-concepts)
+- [Installation & Configuration](#installation)
+  - [Using with schema.rb](#using-with-schemarb)
+  - [Configuration models](#configuration-models)
+  - [Backfill data](#backfill-data)
+  - [Log size limit](#log-size-limit)
+  - [Tracking only selected columns](#tracking-only-selected-columns)
+  - [Logs timestamps](#logs-timestamps)
+- [Usage](#usage)
+  - [Basic API](#basic-api)
+  - [Track meta information](#track-meta-information)
+  - [Track responsibility](#track-responsibility)
+  - [Disable logging temporary](#disable-logging-temporary)
+  - [Reset log](#reset-log)
+  - [Creating full snapshot instead of diffs](#full-snapshots)
+  - [Associations versioning](#associations-versioning)
+- [Dealing with large logs](#dealing-with-large-logs)
+- [Handling records deletion](#handling-records-deletion)
+- [Upgrading](#upgrading)
+- [Log format](#log-format)
+- [Troubleshooting 🚨](#troubleshooting)
+- [Development](#development)
+
 ## Installation
 
 Add Logidze to your application's Gemfile:
 
 ```ruby
-gem 'logidze'
+gem "logidze", "1.0.0.rc1"
 ```
 
 Install required DB extensions and create trigger function:
 
 ```sh
-rails generate logidze:install
+bundle exec 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:
 
 ```sh
-rake db:migrate
+bundle exec rails db:migrate
 ```
 
-**NOTE:** you **must** use SQL schema format since Logidze uses DB functions and triggers:
+**NOTE:** Logidze uses DB functions and triggers, hence you need to use SQL format for a schema dump:
 
 ```ruby
 # application.rb
 config.active_record.schema_format = :sql
 ```
 
-3. Add log column and triggers to the model:
+### Using with schema.rb
+
+Logidze seamlessly integrates with [fx][] gem to make it possible to continue using `schema.rb` for the database schema dump.
+
+Add `fx` gem to your Gemfile and run the same Logidze generators: `rails g logidze:install` or `rails g logidze:model`.
+
+If for some reason Logidze couldn't detect the presence of Fx in your bundle, you can enforce it by passing `--fx` option to generators.
+
+On the other hand, if you have `fx` gem but don't want Logidze to use it—pass `--no-fx` option.
+
+### Configuring models
+
+Run the following migration to enable changes tracking for an Active Record model and adding a `log_data::jsonb` column to the table:
 
 ```sh
-rails generate logidze:model Post
-rake db:migrate
+bundle exec rails generate logidze:model Post
+bundle exec rails 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):
+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 --limit=10
+bundle exec rails generate logidze:model Post --path "app/models/custom/post.rb"
 ```
 
-To backfill table data (i.e. create initial snapshots) add `backfill` option:
+### Backfill data
+
+To backfill table data (i.e., create initial snapshots) add `backfill` option to the generator:
 
 ```sh
-rails generate logidze:model Post --backfill
+bundle exec rails generate logidze:model Post --backfill
 ```
 
-You can log only particular columns changes. There are mutually exclusive `blacklist` and `whitelist` options for this:
+Now your migration should contain and `UPDATE ...` statement to populate the `log_data` column with the current state.
 
-```sh
-# track all columns, except `created_at` and `active`
-rails generate logidze:model Post --blacklist=created_at active
-# track only `title` and `body` columns
-rails generate logidze:model Post --whitelist=title body
-```
+Otherwise a full snapshot will be created the first time the record is updated.
 
-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:
+You can create a snapshot manually by performing the following query:
 
-```sh
-rails generate logidze:model Post --path "app/models/custom/post.rb"
+```sql
+UPDATE <my_table> as t
+SET log_data = logidze_snapshot(to_jsonb(t))
 ```
 
-By default, Logidze tries to get a timestamp for a version from record's `updated_at` field whenever appropriate. If
-your model does not have that column, Logidze will gracefully fall back to `statement_timestamp()`.
-To change the column name or disable this feature completely, you can use the `timestamp_column` option:
+Or by using the following methods:
 
-```sh
-# will try to get the timestamp value from `time` column
-rails generate logidze:model Post --timestamp_column time
-# will always set version timestamp to `statement_timestamp()`
-rails generate logidze:model Post --timestamp_column nil # "null" and "false" will also work
-```
+```ruby
+Model.create_logidze_snapshot
 
-If you want to update Logidze settings for the model, run migration with `--update` flag:
+# specify the timestamp column to use for the initial version (by default the current time is used)
+Model.create_logidze_snapshot(timestamp: :created_at)
 
-```sh
-rails generate logidze:model Post --update --whitelist=title body rating
+# filter columns
+Model.create_logidze_snapshot(only: %(name))
+Model.create_logidze_snapshot(except: %(password))
+
+# or call a similar method (but with !) on a record
+
+my_model = Model.find(params[:id])
+my_model.create_logidze_snapshot!(timestamp: :created_at)
 ```
 
-Logidze also supports associations versioning. It is experimental feature, and disabled by default. You can learn more
-in the [wiki](https://github.com/palkan/logidze/wiki/Associations-versioning).
+A snapshot is only created if `log_data` is null.
 
-## Troubleshooting
+### Log size limits
 
-The most common problem is `"permission denied to set parameter "logidze.xxx"` caused by `ALTER DATABASE ...` query.
-Logidze requires at least database owner privileges (which is not always possible).
+You can provide the `limit` option to `generate` to limit the size of the log (by default it's unlimited):
 
-Here is a quick and straightforward [workaround](https://github.com/palkan/logidze/issues/11#issuecomment-260703464) by [@nobodyzzz](https://github.com/nobodyzzz).
+```sh
+bundle exec rails generate logidze:model Post --limit=10
+```
 
-**NOTE**: if you're using PostgreSQL >= 9.6 you need neither the workaround nor owner privileges because Logidze (>= 0.3.1) can work without `ALTER DATABASE ...`.
+### Tracking only selected columns
 
-Nevertheless, you still need super-user privileges to enable `hstore` extension (or you can use [PostgreSQL Extension Whitelisting](https://github.com/dimitri/pgextwlist)).
+You can log only particular columns changes. There are mutually exclusive `except` and `only` options for this:
 
+```sh
+# track all columns, except `created_at` and `active`
+bundle exec  rails generate logidze:model Post --except=created_at,active
+# track only `title` and `body` columns
+bundle exec rails generate logidze:model Post --only=title,body
+```
+
+### Logs timestamps
 
-## Upgrade from previous versions
+By default, Logidze tries to get a timestamp for a version from record's `updated_at` field whenever appropriate. If
+your model does not have that column, Logidze will gracefully fall back to `statement_timestamp()`.
 
-We try to make upgrade process as simple as possible. For now, the only required action is to create and run a migration:
+To change the column name or disable this feature completely, you can use the `timestamp_column` option:
 
 ```sh
-rails generate logidze:install --update
+# will try to get the timestamp value from `time` column
+bundle exec rails generate logidze:model Post --timestamp_column time
+# will always set version timestamp to `statement_timestamp()`
+bundle exec rails generate logidze:model Post --timestamp_column nil # "null" and "false" will also work
 ```
 
-This updates core `logdize_logger` DB function. No need to update tables or triggers.
-
 ## Usage
 
-Your model now has `log_data` column which stores changes log.
+### Basic API
+
+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 +197,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:
@@ -157,6 +212,9 @@ You can also get revision by version number:
 post.at(version: 2)
 ```
 
+**NOTE:** If `log_data` is nil, `#at(time:)` returns self and `#at(version:)` returns `nil`.
+You can opt-in to return `nil` for time-based `#at` as well by setting `Logidze.return_self_if_log_data_is_empty = false`.
+
 It is also possible to get version for relations:
 
 ```ruby
@@ -173,6 +231,8 @@ post.diff_from(time: 1.hour.ago)
 Post.where(created_at: Time.zone.today.all_day).diff_from(time: 1.hour.ago)
 ```
 
+**NOTE:** If `log_data` is nil, `#diff_from` returns an empty Hash as `"changes"`.
+
 There are also `#undo!` and `#redo!` options (and more general `#switch_to!`):
 
 ```ruby
@@ -186,28 +246,33 @@ post.redo!
 post.switch_to!(2)
 ```
 
-Normally, if you update record after `#undo!` or `#switch_to!` you lose all "future" versions and `#redo!` is no
+You can initiate reloading of `log_data` from the DB:
+
+```ruby
+post.reload_log_data # => returns the latest log data value
+```
+
+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.undo!(append: true)                 # v3 (with same attributes as v1)
+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
 ```
 
+### Track meta information
 
-## 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
@@ -217,7 +282,15 @@ end
 
 Meta expects a hash to be passed so you won't need to encode and decode JSON manually.
 
-## Track responsibility (aka _whodunnit_)
+By default `.with_meta` wraps the block into a DB transaction. That could lead to an unexpected behavior, especially, when using `.with_meta` within an around_action. To avoid wrapping the block into a DB transaction use `transactional: false` option.
+
+```ruby
+Logidze.with_meta({ip: request.ip}, transactional: false) do
+  post.save!
+end
+```
+
+### Track responsibility
 
 A special application of meta information is storing the author of the change, which is called _Responsible ID_. There is more likely that you would like to store the `current_user.id` that way.
 
@@ -235,7 +308,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
@@ -252,17 +325,25 @@ 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
 ```
 
-## Disable logging temporary
+By default `.with_responsible` wraps the block into a DB transaction. That could lead to an unexpected behavior, especially, when using `.with_responsible` within an around_action. To avoid wrapping the block into a DB transaction use `transactional: false` option.
 
-If you want to make update without logging (e.g. mass update), you can turn it off the following way:
+```ruby
+Logidze.with_responsible(user.id, transactional: false) do
+  post.save!
+end
+```
+
+### Disable logging temporary
+
+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) }
@@ -272,6 +353,126 @@ 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
+```
+
+### Full snapshots
+
+You can instruct Logidze to create a full snapshot instead of a diff for a particular log entry.
+
+It could be useful in combination with `.without_logging`: first, you perform multiple updates without logging, then
+you want to create a log entry with the current state. To do that, you should use the `Logidze.with_full_snapshot` method:
+
+```ruby
+record = Model.find(params[:id])
+
+Logidze.without_logging do
+  # perform multiple write operations with record
+end
+
+Logidze.with_full_snapshot do
+  record.touch
+end
+```
+
+### Associations versioning
+
+Logidze also supports associations versioning. This feature is disabled by default (due to the number of edge cases). You can learn more
+in the [wiki](https://github.com/palkan/logidze/wiki/Associations-versioning).
+
+## 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
+```
+
+If you want Logidze to behave this way by default, configure the global option:
+
+```ruby
+# config/initializers/logidze.rb
+Logidze.ignore_log_data_by_default = true
+
+# or
+
+# config/application.rb
+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`.
+You can also enforce loading `log_data` in-place by using the `.with_log_data` scope, e.g. `User.all.with_log_data` loads all
+the _users_ with `log_data` included.
+
+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 `nil`. If you want to fetch log data (e.g., during the console debugging)–use **`user.reload_log_data`**, which forces loading this column from the DB.
+
+## Handling records deletion
+
+Unlike, for example, PaperTrail, Logidze is designed to **only track changes**. If the record has been deleted, **everything is lost**.
+
+If you want to keep changes history after records deletion as well, consider using specialized tools for soft-delete, such as, [Discard](https://github.com/jhawthorn/discard) or [Paranoia](https://github.com/rubysherpas/paranoia).
+
+See also the discussion: [#61](https://github.com/palkan/logidze/issues/61).
+
+## Upgrading
+
+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
+```
+
+This updates core `logdize_logger` DB function. No need to update tables or triggers.
+
+**NOTE:** When using `fx`, you can omit the `--update` flag. The migration containing only the updated functions would be created.
+
+If you want to update Logidze settings for the model, run migration with `--update` flag:
+
+```sh
+rails generate logidze:model Post --update --only=title,body,rating
+```
+
+### Upgrading from 0.x to 1.0 (edge)
+
+#### Schema and migrations
+
+Most SQL functions definitions has changed without backward compatibility.
+Perform the following steps to upgrade:
+
+1. Re-install Logidze: `rails generate logidze:install --update`.
+
+1. Re-install Logidze triggers **for all models**: `rails generate logidze:model <model> --update`.
+
+1. Remove the `include Logidze::Migration` line from the old migration files (if any)—this module has been removed.
+
+Rewrite the migrations to not use the `#current_setting(name)` and `#current_setting_missing_supported?` methods or copy them from the latest [0.x release](https://github.com/palkan/logidze/blob/0-stable/lib/logidze/migration.rb).
+
+#### API changes
+
+The deprecated `time` positional argument has been removed from `#at` and `#diff_from` methods. Now you need to use keyword arguments, i.e., `model.at(some_tome) -> model.at(time: some_time)`.
+
 ## Log format
 
 The `log_data` column has the following format:
@@ -298,22 +499,51 @@ 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
+## Troubleshooting
 
-For development setup run `./bin/setup`. This runs `bundle install` and creates test DB.
+### `log_data` is nil when using Rails fixtures
 
-## Contributing
+Rails fixtures are populated with triggers disabled. Thus, `log_data` is null initially for all records.
+You can use `#create_logidze_snapshot` manually to build initial snapshots.
+
+### How to make this work with Apartment 🤔
+
+First, read [Apartment docs](https://github.com/influitive/apartment#installing-extensions-into-persistent-schemas) on installing PostgreSQL extensions. You need to use the described approach to install Hstore (and drop the migration provided by Logidze during installation).
+
+Secondly, set `config.use_sql = true` in the Apartment configuration.
+
+Finally, when using `fx` along with `schema.rb`, you might face a problem with duplicate trigger definitions (for different schemas).
+Here is a patch to fix this: [dump_triggers.rake](etc/dump_triggers.rake).
+
+Related issues: [#50](https://github.com/palkan/logidze/issues/50).
+
+### `PG::UntranslatableCharacter: ERROR`
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/logidze.
+That could happen when your row data contain null bytes. You should sanitize the data before writing to the database.
+From the [PostgreSQL docs](https://www.postgresql.org/docs/current/datatype-json.html): `jsonb type also rejects \u0000 (because that cannot be represented in PostgreSQL's text type)`.
 
+Related issues: [#155](https://github.com/palkan/logidze/issues/155).
 
-## TODO
+### `pg_restore` fails to restore a dump
 
-- Enhance update_all to support mass-logging.
-- Other DB adapters.
+First, when restoring data dumps you should consider using `--disable-triggers` option (unless you have a strong reason to invoke the triggers).
+
+When restoring data dumps for a particular PostgreSQL schema (e.g., when using Apartment), you may encounter the issue with non-existent Logidze functions. That happens because `pg_dump` adds `SELECT pg_catalog.set_config('search_path', '', false);`, and, thus, breaks our existing triggers/functions, because they live either in "public" or in a tenant's namespace (see [this thread](https://postgrespro.com/list/thread-id/2448092)).
+
+## Development
+
+We use [Dip](https://github.com/bibendi/dip) for development. Provision the project by running `dip provision` and then use `dip bundle`, `dip rspec` or `dip bash` to interact with a Docker development environment.
+
+If you prefer developing on your local machine, make user you have Postgres installed and run `./bin/setup`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/logidze](https://github.com/palkan/logidze).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[fx]: https://github.com/teoljungberg/fx