logidze 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 662f0ec1e4b6945cffe599484e53691651d70599
-  data.tar.gz: 6e82b77620011fa0b758376d810cf7faa5bf305e
+  metadata.gz: 8df5f1ac5aa84c04a0874f222011418bb4ef0fb7
+  data.tar.gz: f354e24b771387fddfc094dd5ea902827d1f4deb
 SHA512:
-  metadata.gz: dd2b1e23e0ce3bef64d331cdb9e2ad19eb18ab7c0ca39264813ef75167fc6c4a2848dfc136ed1bd50f0bb85ad92e7e19d2894a8ed37dc767c15570c24e59c259
-  data.tar.gz: 99597d63737e5cd7d35e88e5466a26a286895a3dac5252805d038c15c651ac375f67785303beee55585198836a543b74fcd207182d9179acd6e5818e48405242
+  metadata.gz: 971a0acde6848091d4944632b579a37ab71335a9d7cab813aa43eae054fa4ae5359b8d654403d1ed8d7145c53afb87917366404a616f73fc71bb6af84536e0e4
+  data.tar.gz: 61d8ad229bb3d56bb5468b005e7e4907af9195bae3d187934a2acb7906b381628fd188ce99d2fb0af013bff8e22f750ae3c00f3fb7496725605b754ef9bad5bb

data/.gitignore

@@ -1,9 +1,40 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
+# Numerous always-ignore extensions
+*.diff
+*.err
+*.orig
+*.log
+*.rej
+*.swo
+*.swp
+*.vi
+*~
+*.sass-cache
+*.iml
+.idea/
+
+# Sublime
+*.sublime-project
+*.sublime-workspace
+
+# OS or Editor folders
+.DS_Store
+.cache
+.project
+.settings
+.tmproj
+Thumbs.db
+
+.bundle/
+log/*.log
+*.gz
+pkg/
+spec/dummy/db/*.sqlite3
+spec/dummy/db/*.sqlite3-journal
+spec/dummy/tmp/
+
+Gemfile.lock
+Gemfile.local
+.rspec
+*.gem
+tmp/
+coverage/

data/.rubocop.yml

@@ -7,9 +7,11 @@ AllCops:
   Exclude:
     - 'bin/**/*'
     - 'spec/dummy/**/*'
-  RunRailsCops: true
+    - 'tmp/**/*'
+    - 'bench/**/*'
   DisplayCopNames: true
   StyleGuideCopsOnly: false
+  TargetRubyVersion: 2.3
 
 Style/AccessorMethodName:
   Enabled: false

data/.travis.yml

@@ -1,4 +1,37 @@
 language: ruby
-rvm:
-  - 2.3.0
-before_install: gem install bundler -v 1.11.2
+cache: bundler
+
+env:
+  global:
+    - LOGIDZE_DB_USER=postgres
+    - LOGIDZE_DB_NAME=logidze
+
+before_install:
+  - sudo /etc/init.d/postgresql stop
+  - sudo apt-get -y remove --purge postgresql-9.1
+  - sudo apt-get -y remove --purge postgresql-9.2
+  - sudo apt-get -y remove --purge postgresql-9.3
+  - sudo apt-get -y remove --purge postgresql-9.4
+  - sudo apt-get -y autoremove
+  - sudo apt-key adv --keyserver keys.gnupg.net --recv-keys 7FCC7D46ACCC4CF8
+  - sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main 9.5" >> /etc/apt/sources.list.d/postgresql.list'
+  - sudo apt-get update
+  - sudo apt-get -y install postgresql-9.5
+  - sudo sh -c 'echo "local all postgres trust" > /etc/postgresql/9.5/main/pg_hba.conf'
+  - sudo sh -c 'echo -n "host all all 127.0.0.1/32 trust" >> /etc/postgresql/9.5/main/pg_hba.conf'
+  - sudo /etc/init.d/postgresql restart
+  - psql --version
+
+before_script:
+  - 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
+
+matrix:
+  include:
+    - rvm: 2.3.0
+      gemfile: gemfiles/rails5.gemfile
+    - rvm: 2.3.0
+      gemfile: gemfiles/rails42.gemfile
+  allow_failures:
+    - gemfile: gemfiles/rails5.gemfile

data/Gemfile

@@ -1,6 +1,5 @@
 source 'https://rubygems.org'
 
-gem 'pry'
 # Specify your gem's dependencies in logidze.gemspec
 gemspec
 

data/README.md

@@ -1,35 +1,170 @@
-[![Gem Version](https://badge.fury.io/rb/logidze.svg)](https://rubygems.org/gems/logidze) [![Vexor Status](https://ci.vexor.io/projects/163dc587-613e-4643-a071-a56edbe12f34/status.svg)](https://ci.vexor.io/ui/projects/163dc587-613e-4643-a071-a56edbe12f34/builds)
+[![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) [![Circle CI](https://circleci.com/gh/palkan/logidze/tree/master.svg?style=svg)](https://circleci.com/gh/palkan/logidze/tree/master)
 
 # Logidze
 
-TBD
+Logidze provides tools for logging DB records changes.
+**This is not [audited](https://github.com/collectiveidea/audited) or [paper_trail](https://github.com/airblade/paper_trail) alternative!**
+
+Logidze allows you to create DB-level log (using triggers) and gives you an API to browse this log.
+Log is stored with the record itself in JSONB column. No additional tables required.
+Currently, only PostgreSQL 9.5+ is supported.
+
+Other requirements:
+- Ruby ~>2.3;
+- Rails ~>4.2;
+
+<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>
 
 ## Installation
 
-Add this line to your application's Gemfile:
+1. Add Logidze your application's Gemfile:
 
 ```ruby
 gem 'logidze'
 ```
 
-And then execute:
+2. Install required DB extensions and create trigger function:
+
+```ruby
+rails generate logidze:install
+```
+
+This creates migration for adding trigger function and enabling hstore extension.
+
+Run migrations:
+
+```ruby
+rake db:migrate
+```
+
+3. Add log column and triggers to the model:
 
-    $ bundle
+```ruby
+rails generate logidze:model Post
+rake db:migrate
+```
 
-Or install it yourself as:
+You can provide `limit` option to `generate` to limit the size of the log (by default it's unlimited):
 
-    $ gem install logidze
+```ruby
+rails generate logidze:mode Post --limit=10
+```
+
+This also adds `has_logidze` line to your model, which adds methods for working with logs.
 
 ## Usage
 
-TBD
+Your model now has `log_data` column which stores changes log.
+
+To retrieve record version at a given time use `#at` or `#at!` methods:
+
+```ruby
+post = Post.find(27)
+
+# Show current version
+post.log_version #=> 3
+
+# Show log size (number of versions)
+post.log_size #=> 3
+
+# Get copy of a record at a given time 
+old_post = post.at(2.days.ago)
+
+# or revert the record itself to the previous state (without committing to DB)
+post.at!('201-04-15 12:00:00')
+
+# If no version found
+post.at('1945-05-09 09:00:00') #=> nil
+```
+
+You can also get revision by version number:
+
+```ruby
+post.at_version(2)
+```
+
+It is also possible to get version for relations:
+
+```ruby
+Post.where(active: true).at(1.month.ago)
+```
+
+You can also get diff from specified time:
+
+```ruby
+post.diff_from(1.hour.ago)
+#=> { "id" => 27, "changes" => { "title" => { "old" => "Logidze sucks!", "new" => "Logidze rulz!" } } }
+
+# the same for relations
+Post.where(created_at: Time.zone.today.all_day).diff_from(1.hour.ago)
+```
+
+There are also `#undo!` and `#redo!` options (and more general `#switch_to!`):
+
+```ruby
+# Revert record to the previous state (and stores this state in DB)
+post.undo!
+
+# You can now user redo! to revert back
+post.redo!
+
+# More generally you can revert record to arbitrary version
+post.switch_to!(2)
+```
+
+If you update record after `#undo!` or `#switch_to!` you lose all "future" versions and `#redo!` is no longer possible.
+
+## 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) }
+
+# or
+
+Post.without_logging { Post.update_all(seen: true) }
+```
+
+## Log format
+
+The `log_data` column has the following format:
+
+```js
+{
+  "v": 2, // current record version,
+  "h": // list of changes 
+    [
+      {
+        "v": 1,  // change number
+        "ts": 1460805759352, // change timestamp in milliseconds
+        "c": { 
+            "attr": "new value",  // updated fields with new values
+            "attr2": "new value"
+            }
+        }
+    ]
+}
+```
+
+If you specified the limit in you trigger definition then log size would not exceed the specified size. When a new change occurs, and there is no more room for it, the two oldest changes get merged.
+
+## Development
+
+For development setup run `./bin/setup`. This runs `bundle install` and creates test DB.
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/logidze.
 
 
+## TODO
+
+- Exclude columns from log
+- Enhance `update_all` to support mass-logging
+- Other DB adapters
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/Rakefile

@@ -3,4 +3,23 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+namespace :dummy do
+  require_relative "spec/dummy/config/application"
+  Dummy::Application.load_tasks
+end
+
+task(:spec).clear
+desc "Run specs other than spec/acceptance"
+RSpec::Core::RakeTask.new("spec") do |task|
+  task.exclude_pattern = "spec/acceptance/**/*_spec.rb"
+  task.verbose = false
+end
+
+desc "Run acceptance specs in spec/acceptance"
+RSpec::Core::RakeTask.new("spec:acceptance") do |task|
+  task.pattern = "spec/acceptance/**/*_spec.rb"
+  task.verbose = false
+end
+
+desc "Run the specs and acceptance tests"
+task default: %w(spec spec:acceptance)

data/bench/Makefile

@@ -8,21 +8,49 @@ ifndef T
 	T = 10000
 endif
 
-all:
-	make plain
-	make hstore
-	make keys
+all: plain hstore jsonb jsonb2 keys keys2
 
 setup:
-	pgbench -i -q $(DB)
+	createdb $(DB) -w
+	psql -q -d $(DB) -c 'CREATE EXTENSION IF NOT EXISTS hstore;'
 
-plain: setup
+plain:
+	$(info )
+	$(info ======  [START] Update without triggers ======)
+	pgbench -i -q $(DB)
 	pgbench -f bench.sql -t $(T) -r $(DB)
 
-hstore: setup
+hstore:
+	$(info )
+	$(info ======  [START] Update with hstore-based triggers ======)
+	pgbench -i -q $(DB)
 	psql -q -d $(DB) -f hstore_trigger_setup.sql 
-	pgbench -f bench.sql -t $(T) -r $(DB)     
+	pgbench -f bench.sql -t $(T) -r $(DB)
+
+jsonb:
+	$(info )
+	$(info ======  [START] Update with jsonb-minus triggers ======)
+	pgbench -i -q $(DB)
+	psql -q -d $(DB) -f jsonb_minus_setup.sql 
+	pgbench -f bench.sql -t $(T) -r $(DB)
 
-keys: setup
+jsonb2:
+	$(info )
+	$(info ======  [START] Update with jsonb-minus triggers ======)
+	pgbench -i -q $(DB)
+	psql -q -d $(DB) -f jsonb_minus_2_setup.sql 
+	pgbench -f bench.sql -t $(T) -r $(DB)
+
+keys:
+	$(info )
+	$(info ======  [START] Update with loop thru keys triggers (v1) ======)
+	pgbench -i -q $(DB)
 	psql -q -d $(DB) -f keys_trigger_setup.sql
+	pgbench -f bench.sql -t $(T) -r $(DB) 
+
+keys2:
+	$(info )
+	$(info ======  [START] Update with loop thru keys triggers (v2) ======)
+	pgbench -i -q $(DB)
+	psql -q -d $(DB) -f keys2_trigger_setup.sql
 	pgbench -f bench.sql -t $(T) -r $(DB)  

data/bench/Readme.md

@@ -0,0 +1,58 @@
+# Triggers benchmarks
+
+This benchmark uses standard _pg\_bench_ table `pgbench_accounts`.
+We consider several approaches for calculating records diff: one uses _hstore_ extension, two uses jsonb functions and two others iterate through record fields.
+
+# Usage
+
+Create database:
+
+```sh
+make setup
+```
+
+You can provide database name through `DB` variable (by default "logidze_bench").
+
+Run all benchmarks:
+
+```sh
+make
+```
+
+or separate benchmark:
+
+```sh
+make hstore
+
+make jsonb
+
+make jsonb2
+
+make keys
+
+make keys2
+
+# raw update, no triggers
+make plain
+```
+
+You can specify the number of transactions by `T` variable (defaults to 10000):
+
+```sh
+make T=1000000
+```
+
+# Results
+
+The benchmark shows that hstore and jsonb variants are of the same efficiency (running on MacPro 2013, 2.4 GHz Core i5, 4GB, SSD, 1 million transactions per test):
+
+|Mode    | TPS  | Statement latency (ms) |
+|--------|------|------------------------|
+| plain  | 3805 | 0.106                  |
+| hstore | 3061 | 0.165                  |
+| jsonb  | 3079 | 0.165                  |
+| jsonb2 | 3057 | 0.166                  |
+| keys   | 2606 | 0.209                  |
+| keys2  | 2610 | 0.216                  |
+
+_Logidze_ uses jsonb variant.