historiographer 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cceab0e39bc86b8e410a55d5c5b23556ad8ecf543fae2720d0761cbfc9070b1d
-  data.tar.gz: 70fd87e0ecf2fbf6829a50ac315746bced3e2533e0a3664ce005c237557265bd
+  metadata.gz: f2d85a348f2e7196cccef533c9562b53c9449df6a0dde03509a1d48a5d66c490
+  data.tar.gz: f3b9f822e53fdadc04d20a0f4066b8b47e019c11333d9dccc0140ea1e9f12991
 SHA512:
-  metadata.gz: e77e1c8d9dc96c8d6db182b568529fc1d16e1947dc6e16a1234109a90ad3f02229ec9532ba560ea56246fa79d9ccc928801a885a9a6b5a14d2d132202d3cb220
-  data.tar.gz: 9e94ed498ca13062259f8031bfbd529ae516261e7a08e46a32e73bec86a066df4d9d83e1ea70754a7260c0f5fa38a933bcc4ce1431cffbd0a2944fbd3f21c686
+  metadata.gz: 5011fe73d7a09abd888f362b1e3923436c5f29068f9b46650ac4e39f09ab3226d7f2d66072293d9908dc37693a7afc5b73f73c2db2c1f6f1b0e9119c153c511b
+  data.tar.gz: ccca124547a124739d68183b9374ddd1b8fc452ed29b568da485981abb37cab8f055384065b00016981ea3844177c5e7e050d0fb6e5f8faef7844e5835387591

data/README.md

@@ -1,40 +1,99 @@
-# historiographer
+# Historiographer
 
-Losing data sucks. Every time you update a record in Rails, by default, you lose the old data.
+Losing data sucks. Every time you update or destroy a record in Rails, you lose the old data.
 
-Supported for PostgreSQL and MySQL. If you need other adapters, help us make one!
+Historiographer fixes this problem in a better way than existing auditing gems.
 
 ## Existing auditing gems for Rails suck
 
 The Audited gem has some serious flaws.
 
-First, it only tracks a record of what changed, so there's no way to "go back in time" and see what the data looked like back when a problem occurred without replaying every single audit.
+🤚Hands up if your `versions` table has gotten too big to query 🤚
+
+🤚Hands up if your `versions` table doesn't have the indexes you need 🤚
+
+🤚Hands up if you've ever iterated over `versions` records in Ruby to recreate a snapshot of what data looked like at a point in time. 🤚
+
+Why does this happen?
+
+First, `audited` only tracks a record of what changed, so there's no way to "go back in time" and see what the data looked like back when a problem occurred without replaying every single audit.
 
 Second, it tracks changes as JSON. While some data stores have JSON querying semantics, not all do, making it very hard to ask complex questions of your historical data -- that's the whole reason you're keeping it around.
 
-Third, it doesn't maintain efficient indexes on your data. If you maintain an index on the primary records, wouldn't you also want to look up historical records using the same columns? Historical data is MUCH larger than "latest snapshot" data, so, duh, of course you do.
+Third, it doesn't maintain indexes on your data. If you maintain an index on the primary table, wouldn't you also want to look up historical records using the same columns? Historical data is MUCH larger than "latest snapshot" data, so, duh, of course you do.
+
+Finally, Audited creates just one table for all audits. Historical data is big. It's not unusual for an audited gem table to get into the many millions of rows, and need to be constantly partitioned to maintain any kind of efficiency.
+
+## How does Historiographer solve these problems?
+
+Historiographer introduces the concept of _history tables:_ append-only tables that have the same structure and indexes as your primary table.
+
+If you have a `posts` table:
+
+| id | title |
+| :----------- | :----------- |
+| 1      | My Great Post       |
+| 2 | My Second Post |
 
-Finally, Audited creates one table for every audit. As mentioned before, historical data is big. It's not unusual for an audited gem table to get into the many millions of rows, and need to be constnatly partitioned to maintain any kind of efficiency.
+You'll also have a `post_histories_table`:
 
-## How does Historiographer solve the problem?
+| id | post_id | title | history_started_at | history_ended_at | history_user_id |
+| :----------- | :----------- | :----------- | :----------- | :----------- | :----------- |
+| 1      | 1 | My Great Post | '2019-11-08' | NULL | 1 |
+| 2 | 2| My Second Post | '2019-11-08' | NULL | 1 |
 
-You have existing code written in Rails, so our existing queries need to Just Work.
+If you change the title of the 1st post:
 
-Moreover, there are benefits to the Active Record model of updating records in place: the latest snapshot is cached, and accessing it is efficient.
+```Post.find(1).update(title: "Title With Better SEO", history_user_id: current_user.id)```
 
-So how can we get the benefits of caching but NOT losing data, and continue to create, update, and destroy like we normally would in Rails?
+You'll expect your `posts` table to be updated directly:
 
-Historiographer introduces the concept of _history tables:_ tables that have the exact same structure as tables storing the latest snapshots of data. So if you have a `posts` table, you'll also have a `post_histories` table with all the same columns and indexes.
+| id | title |
+| :----------- | :----------- |
+| 1      | Title With Better SEO |
+| 2 | My Second Post |
 
-Whenever you include the `Historiographer` gem in your ActiveRecord model, it allows you to insert, update, or delete data as you normally would. If the changes are successful, it also inserts a new history snapshot in the histories table--an exact snapshot of the data at that point in time.
+But also, your `histories` table will be updated:
 
-These tables feature two useful indexes: `history_started_at` and `history_ended_at`, which allow you to see what the data looked like and when. You can easily create views which show the total lifecycle of a piece of data, or restore earlier versions directly from these snapshots.
+| id | post_id | title | history_started_at | history_ended_at | history_user_id |
+| :----------- | :----------- | :----------- | :----------- | :----------- | :----------- |
+| 1      | 1 | My Great Post | '2019-11-08' | '2019-11-09' | 1 |
+| 2 | 2| My Second Post | '2019-11-08' | NULL | 1 |
+| 1      | 1 | Title With Better SEO | '2019-11-09' | NULL | 1 |
 
-And of course, it contains a migrations tool to help you write the same migrations you normally would without having to worry about also synchronizing histories tables.
+A few things have happened here:
 
-# basic use
+1. The primary table (`posts`) is updated directly
+2. The existing history for `post_id=1` is timestamped when its `history_ended_at`, so that we can see when the post had the title "My Great Post"
+3. A new history record is appended to the table containing a complete snapshot of the record, and a `NULL` `history_ended_at`. That's because this is the current history. 
+4. A record of _who_ made the change is saved (`history_user_id`). You can join to your users table to see more data.
+
+# Getting Started
+
+Whenever you include the `Historiographer` gem in your ActiveRecord model, it allows you to insert, update, or delete data as you normally would.
+
+```ruby
+class Post < ActiveRecord::Base
+  include Historiographer
+end
+```
 
-## migrations
+By default, Historiographer will require all SQL-backed methods to provide a `history_user_id` to track who made the changes.
+
+```ruby
+Post.create(title: "My Post", history_user_id: current_user.id) # => OK
+Post.create(title: "My Post") # => Error!
+```
+
+Many existing models will be better off using `Historiographer::Safe` when getting started, which will not raise an error, but will alert you of locations where your app is missing `history_user_id`. 
+
+```ruby
+class Post < ActiveRecord::Base
+  include Historiographer::Safe
+end
+```
+
+## Create A Migration
 
 You need a separate table to store histories for each model.
 
@@ -80,25 +139,7 @@ Additionally it will add indices on:
 - The same columns that had indices on the original model (e.g. `enabled`)
 - `history_started_at`, `history_ended_at`, and `history_user_id`
 
-### what to do when generated index names are too long
-
-Sometimes the generated index names are too long. Just like with standard Rails migrations, you can override the name of the index to fix this problem. To do so, use the `index_names` argument to override individual index names:
-
-```ruby
-require "historiographer/postgres_migration"
-class CreatePostHistories < ActiveRecord::Migration
-  def change
-    create_table :post_histories do |t|
-      t.histories, index_names: {
-        title: "my_index_name",
-        [:compound, :index] => "my_compound_index_name"
-      }
-    end
-  end
-end
-```
-
-## models
+## Models
 
 The primary model should include `Historiographer`:
 
@@ -127,6 +168,18 @@ p.histories.first.post == p
 # => true
 ```
 
+## Creating, Updating, and Destroying Data:
+
+You can just use normal ActiveRecord methods, and all will record histories:
+
+```ruby
+Post.create(title: "My Great Title", history_user_id: current_user.id)
+Post.find_by(title: "My Great Title").update(title: "A New Title", history_user_id: current_user.id)
+Post.update_all(title: "They're all the same!", history_user_id: current_user.id)
+Post.last.destroy!(history_user_id: current_user.id)
+Post.destroy_all(history_user_id: current_user.id)
+```
+
 The `histories` classes have a `current` method, which only finds current history records. These records will also be the same as the data in the primary table.
 
 ```ruby
@@ -136,7 +189,25 @@ p.current_history
 PostHistory.current
 ```
 
+### What to do when generated index names are too long
+
+Sometimes the generated index names are too long. Just like with standard Rails migrations, you can override the name of the index to fix this problem. To do so, use the `index_names` argument to override individual index names:
+
+```ruby
+require "historiographer/postgres_migration"
+class CreatePostHistories < ActiveRecord::Migration
+  def change
+    create_table :post_histories do |t|
+      t.histories, index_names: {
+        title: "my_index_name",
+        [:compound, :index] => "my_compound_index_name"
+      }
+    end
+  end
+end
+```
+
 == Copyright
 
-Copyright (c) 2016-2018 brettshollenberger. See LICENSE.txt for
+Copyright (c) 2016-2020 brettshollenberger. See LICENSE.txt for
 further details.

data/VERSION

@@ -1 +1 @@
-1.3.0
+1.3.1

data/historiographer.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: historiographer 1.3.0 ruby lib
+# stub: historiographer 1.3.1 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "historiographer".freeze
-  s.version = "1.3.0"
+  s.version = "1.3.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["brettshollenberger".freeze]
-  s.date = "2019-11-08"
+  s.date = "2019-11-11"
   s.description = "Creates separate tables for each history table".freeze
   s.email = "brett.shollenberger@gmail.com".freeze
   s.extra_rdoc_files = [

data/lib/historiographer.rb

@@ -2,6 +2,7 @@ require "active_support/all"
 require_relative "./historiographer/history"
 require_relative "./historiographer/postgres_migration"
 require_relative "./historiographer/safe"
+require_relative "./historiographer/relation"
 
 # Historiographer takes "histories" (think audits or snapshots) of your model whenever you make changes.
 #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: historiographer
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors:
 - brettshollenberger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-08 00:00:00.000000000 Z
+date: 2019-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord