historiographer 4.1.0 → 4.1.2

data/Users/brettshollenberger/programming/historiographer/README.md

@@ -1,298 +0,0 @@
-# Historiographer
-
-Losing data sucks. Every time you update or destroy a record in Rails, you lose the old data.
-
-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.
-
-1. The `versions` table quickly grows too large to query
-
-2. It doesn't provide the indexes you need from your primary tables
-
-3. It doesn't provdie out-of-the-box snapshots
-
-## 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 |
-
-You'll also have a `post_histories_table`:
-
-| 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               |
-
-If you change the title of the 1st post:
-
-`Post.find(1).update(title: "Title With Better SEO", history_user_id: current_user.id)`
-
-You'll expect your `posts` table to be updated directly:
-
-| id  | title                 |
-| :-- | :-------------------- |
-| 1   | Title With Better SEO |
-| 2   | My Second Post        |
-
-But also, your `histories` table will be updated:
-
-| 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               |
-
-A few things have happened here:
-
-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.
-
-## Snapshots
-
-Snapshots are particularly useful for two key use cases:
-
-### 1. Time Travel & Auditing
-
-When you need to see exactly what your data looked like at a specific point in time - not just individual records, but entire object graphs with all their associations. This is invaluable for:
-
-- Debugging production issues ("What did the entire order look like when this happened?")
-- Compliance requirements ("Show me the exact state of this patient's record on January 1st")
-- Auditing complex workflows ("What was the state of this loan application when it was approved?")
-
-### 2. Machine Learning & Analytics
-
-When you need immutable snapshots of data for:
-
-- Training data versioning
-- Feature engineering
-- Model validation
-- A/B test analysis
-- Ensuring reproducibility of results
-
-### Taking Snapshots
-
-You can take a snapshot of a record and all its associated records:
-
-```ruby
-post = Post.find(1)
-post.snapshot(history_user_id: current_user.id)
-```
-
-This will:
-
-1. Create a history record for the post
-2. Create history records for all associated records (comments, author, etc.)
-3. Link these history records together with a shared `snapshot_id`
-
-You can retrieve the latest snapshot using:
-
-```ruby
-post = Post.find(1)
-snapshot = post.latest_snapshot
-
-# Access associated records from the snapshot
-snapshot.comments # Returns CommentHistory records
-snapshot.author   # Returns AuthorHistory record
-```
-
-Snapshots are immutable - you cannot modify history records that are part of a snapshot. This guarantees that your historical data remains unchanged, which is crucial for both auditing and machine learning applications.
-
-### Snapshot-Only Mode
-
-If you want to only track snapshots and not record every individual change, you can configure Historiographer to operate in snapshot-only mode:
-
-```ruby
-Historiographer::Configuration.mode = :snapshot_only
-```
-
-In this mode:
-
-- Regular updates/changes will not create history records
-- Only explicit calls to `snapshot` will create history records
-- Each snapshot still captures the complete state of the record and its associations
-
-This can be useful when:
-
-- You only care about specific points in time rather than every change
-- You want to reduce the number of history records created
-- You need to capture the state of complex object graphs at specific moments
-- You're versioning training data for machine learning models
-- You need to maintain immutable audit trails at specific checkpoints
-
-# 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
-```
-
-### History Modes
-
-Historiographer supports two modes of operation:
-
-1. **:histories mode** (default) - Records history for every change to a record
-2. **:snapshot_only mode** - Only records history when explicitly taking snapshots
-
-You can configure the mode globally:
-
-```ruby
-# In an initializer
-Historiographer::Configuration.mode = :histories  # Default mode
-# or
-Historiographer::Configuration.mode = :snapshot_only
-```
-
-Or per model using `historiographer_mode`:
-
-```ruby
-class Post < ActiveRecord::Base
-  include Historiographer
-  historiographer_mode :snapshot_only  # Only record history when .snapshot is called
-end
-
-class Comment < ActiveRecord::Base
-  include Historiographer
-  historiographer_mode :histories  # Record history for every change (default)
-end
-```
-
-## Create A Migration
-
-You need a separate table to store histories for each model.
-
-So if you have a Posts model:
-
-```ruby
-class CreatePosts < ActiveRecord::Migration
-  def change
-    create_table :posts do |t|
-      t.string :title, null: false
-      t.boolean :enabled
-    end
-    add_index :posts, :enabled
-  end
-end
-```
-
-You should create a model named _posts_histories_:
-
-```ruby
-require "historiographer/postgres_migration"
-class CreatePostHistories < ActiveRecord::Migration
-  def change
-    create_table :post_histories do |t|
-      t.histories
-    end
-  end
-end
-```
-
-The `t.histories` method will automatically create a table with the following columns:
-
-- `id` (because every model has a primary key)
-- `post_id` (because this is the foreign key)
-- `title` (because it was on the original model)
-- `enabled` (because it was on the original model)
-- `history_started_at` (to denote when this history became the canonical version)
-- `history_ended_at` (to denote when this history was no longer the canonical version, if it has stopped being the canonical version)
-- `history_user_id` (to denote the user that made this change, if one is known)
-
-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`
-
-## Models
-
-The primary model should include `Historiographer`:
-
-```ruby
-class Post < ActiveRecord::Base
-  include Historiographer
-end
-```
-
-You should also make a `PostHistory` class if you're going to query `PostHistory` from Rails:
-
-```ruby
-class PostHistory < ActiveRecord::Base
-end
-```
-
-The `Posts` class will acquire a `histories` method, and the `PostHistory` model will gain a `post` method:
-
-```ruby
-p = Post.first
-p.histories.first.class
-
-# => "PostHistory"
-
-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
-p = Post.first
-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
-```
-
-== Mysql Install
-
-For contributors on OSX, you may have difficulty installing mysql:
-
-```
-gem install mysql2 -v '0.4.10' --source 'https://rubygems.org/' -- --with-ldflags=-L/usr/local/opt/openssl/lib --with-cppflags=-I/usr/local/opt/openssl/include
-```
-
-== Copyright
-
-Copyright (c) 2016-2020 brettshollenberger. See LICENSE.txt for
-further details.

data/Users/brettshollenberger/programming/historiographer/Rakefile

@@ -1,54 +0,0 @@
-# encoding: utf-8
-
-require 'rubygems'
-require 'bundler'
-require 'pry'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
-require 'jeweler'
-
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
-  gem.name = "historiographer"
-  gem.homepage = "http://github.com/brettshollenberger/historiographer"
-  gem.license = "MIT"
-  gem.summary = %Q{Create histories of your ActiveRecord tables}
-  gem.description = %Q{Creates separate tables for each history table}
-  gem.email = "brett.shollenberger@gmail.com"
-  gem.authors = ["brettshollenberger"]
-end
-Jeweler::RubygemsDotOrgTasks.new
-
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'spec'
-  test.pattern = 'rspec/**/*_spec.rb'
-  test.verbose = true
-end
-
-desc "Code coverage detail"
-task :simplecov do
-  ENV['COVERAGE'] = "true"
-  Rake::Task['test'].execute
-end
-
-task :default => :test
-
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "historiographer #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-require 'standalone_migrations'
-StandaloneMigrations::Tasks.load_tasks

data/Users/brettshollenberger/programming/historiographer/historiographer.gemspec

@@ -1,65 +0,0 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
-# -*- encoding: utf-8 -*-
-# stub: historiographer 4.0.0 ruby lib
-
-Gem::Specification.new do |s|
-  s.name = "historiographer".freeze
-  s.version = "4.1.0"
-
-  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 = "2023-08-22"
-  s.description = "Creates separate tables for each history table".freeze
-  s.email = "brett.shollenberger@gmail.com".freeze
-  s.extra_rdoc_files = [
-    "LICENSE.txt",
-    "README.md"
-  ]
-  s.files = Dir[File.expand_path("**/*")]
-  s.homepage = "http://github.com/brettshollenberger/historiographer".freeze
-  s.licenses = ["MIT".freeze]
-  s.rubygems_version = "3.2.22".freeze
-  s.summary = "Create histories of your ActiveRecord tables".freeze
-
-  if s.respond_to? :specification_version then
-    s.specification_version = 4
-  end
-
-  if s.respond_to? :add_runtime_dependency then
-    s.add_runtime_dependency(%q<activerecord>.freeze, [">= 6"])
-    s.add_runtime_dependency(%q<activerecord-import>.freeze, [">= 0"])
-    s.add_runtime_dependency(%q<activesupport>.freeze, [">= 0"])
-    s.add_runtime_dependency(%q<rails>.freeze, [">= 6"])
-    s.add_runtime_dependency(%q<rollbar>.freeze, [">= 0"])
-    s.add_development_dependency(%q<mysql2>.freeze, ["= 0.5"])
-    s.add_development_dependency(%q<paranoia>.freeze, [">= 0"])
-    s.add_development_dependency(%q<pg>.freeze, [">= 0"])
-    s.add_development_dependency(%q<pry>.freeze, [">= 0"])
-    s.add_development_dependency(%q<standalone_migrations>.freeze, [">= 0"])
-    s.add_development_dependency(%q<timecop>.freeze, [">= 0"])
-    s.add_development_dependency(%q<bundler>.freeze, ["~> 1.0"])
-    s.add_development_dependency(%q<jeweler>.freeze, [">= 0"])
-    s.add_development_dependency(%q<rdoc>.freeze, ["~> 3.12"])
-    s.add_development_dependency(%q<simplecov>.freeze, [">= 0"])
-  else
-    s.add_dependency(%q<activerecord>.freeze, [">= 6"])
-    s.add_dependency(%q<activerecord-import>.freeze, [">= 0"])
-    s.add_dependency(%q<activesupport>.freeze, [">= 0"])
-    s.add_dependency(%q<rails>.freeze, [">= 6"])
-    s.add_dependency(%q<rollbar>.freeze, [">= 0"])
-    s.add_dependency(%q<mysql2>.freeze, ["= 0.5"])
-    s.add_dependency(%q<paranoia>.freeze, [">= 0"])
-    s.add_dependency(%q<pg>.freeze, [">= 0"])
-    s.add_dependency(%q<pry>.freeze, [">= 0"])
-    s.add_dependency(%q<standalone_migrations>.freeze, [">= 0"])
-    s.add_dependency(%q<timecop>.freeze, [">= 0"])
-    s.add_dependency(%q<bundler>.freeze, ["~> 1.0"])
-    s.add_dependency(%q<jeweler>.freeze, [">= 0"])
-    s.add_dependency(%q<rdoc>.freeze, ["~> 3.12"])
-    s.add_dependency(%q<simplecov>.freeze, [">= 0"])
-  end
-end
-

data/Users/brettshollenberger/programming/historiographer/init.rb

@@ -1,18 +0,0 @@
-require "yaml"
-
-Bundler.require(:default, :development, :test)
-
-Dir.glob(File.expand_path("lib/**/*.rb")).each do |file|
-  require file
-end
-
-database_config = YAML.load(File.open(File.expand_path("spec/db/database.yml")).read)
-
-env = ENV["HISTORIOGRAPHER_ENV"] || "development"
-
-db_env_config = database_config[env]
-
-if defined?(ActiveRecord::Base)
-  # new settings as specified here: https://devcenter.heroku.com/articles/concurrency-and-database-connections
-  ActiveRecord::Base.establish_connection(db_env_config)
-end

data/Users/brettshollenberger/programming/historiographer/lib/historiographer/version.rb

@@ -1,3 +0,0 @@
-module Historiographer
-  VERSION = "4.1.0"
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/database.yml

@@ -1,27 +0,0 @@
-development:
-  adapter: postgresql
-  encoding: unicode
-  database: historiographer_development
-  pool: 5
-
-test:
-  adapter: postgresql
-  encoding: unicode
-  database: historiographer_test
-  pool: 5
-
-# mysql_default: &mysql_default
-#   adapter: mysql2
-#   encoding: utf8
-#   username: root
-#   password:
-#   host: 127.0.0.1
-#   port: 3306
-
-# development:
-#   <<: *mysql_default
-#   database: historiographer_development
-
-# test:
-#   <<: *mysql_default
-#   database: historiographer_test

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20161121212228_create_posts.rb

@@ -1,19 +0,0 @@
-class CreatePosts < ActiveRecord::Migration[5.1]
-  def change
-    create_table :posts do |t|
-      t.string :title, null: false
-      t.text :body, null: false
-      t.integer :author_id, null: false
-      t.boolean :enabled, default: false
-      t.datetime :live_at
-      t.datetime :deleted_at
-
-      t.timestamps
-    end
-
-    add_index :posts, :author_id
-    add_index :posts, :enabled
-    add_index :posts, :live_at
-    add_index :posts, :deleted_at
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20161121212229_create_post_histories.rb

@@ -1,10 +0,0 @@
-require "historiographer/postgres_migration"
-require "historiographer/mysql_migration"
-
-class CreatePostHistories < ActiveRecord::Migration[5.1]
-  def change
-    create_table :post_histories do |t|
-      t.histories
-    end
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20161121212230_create_authors.rb

@@ -1,13 +0,0 @@
-class CreateAuthors < ActiveRecord::Migration[5.1]
-  def change
-    create_table :authors do |t|
-      t.string :full_name, null: false
-      t.text :bio
-      t.datetime :deleted_at
-
-      t.timestamps
-    end
-
-    add_index :authors, :deleted_at
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20161121212231_create_author_histories.rb

@@ -1,10 +0,0 @@
-require "historiographer/postgres_migration"
-require "historiographer/mysql_migration"
-
-class CreateAuthorHistories < ActiveRecord::Migration[5.1]
-  def change
-    create_table :author_histories do |t|
-      t.histories
-    end
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20161121212232_create_users.rb

@@ -1,9 +0,0 @@
-require "historiographer/postgres_migration"
-
-class CreateUsers < ActiveRecord::Migration[5.1]
-  def change
-    create_table :users do |t|
-      t.string :name
-    end
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20171011194624_create_safe_posts.rb

@@ -1,19 +0,0 @@
-class CreateSafePosts < ActiveRecord::Migration[5.1]
-  def change
-    create_table :safe_posts do |t|
-      t.string :title, null: false
-      t.text :body, null: false
-      t.integer :author_id, null: false
-      t.boolean :enabled, default: false
-      t.datetime :live_at
-      t.datetime :deleted_at
-
-      t.timestamps
-    end
-
-    add_index :safe_posts, :author_id
-    add_index :safe_posts, :enabled
-    add_index :safe_posts, :live_at
-    add_index :safe_posts, :deleted_at
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20171011194715_create_safe_post_histories.rb

@@ -1,9 +0,0 @@
-require "historiographer/postgres_migration"
-
-class CreateSafePostHistories < ActiveRecord::Migration[5.1]
-  def change
-    create_table :safe_post_histories do |t|
-      t.histories
-    end
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20191024142304_create_thing_with_compound_index.rb

@@ -1,10 +0,0 @@
-class CreateThingWithCompoundIndex < ActiveRecord::Migration[5.2]
-  def change
-    create_table :thing_with_compound_indices do |t|
-      t.string :key
-      t.string :value
-
-      t.index [:key, :value], name: "idx_key_value"
-    end
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20191024142352_create_thing_with_compound_index_history.rb

@@ -1,11 +0,0 @@
-require "historiographer/postgres_migration"
-class CreateThingWithCompoundIndexHistory < ActiveRecord::Migration[5.2]
-  def change
-    create_table :thing_with_compound_index_histories do |t|
-      t.histories index_names: {
-        [:key, :value] => "idx_history_k_v",
-        :thing_with_compound_index_id => "idx_k_v_histories"
-      }
-    end
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20191024203106_create_thing_without_history.rb

@@ -1,7 +0,0 @@
-class CreateThingWithoutHistory < ActiveRecord::Migration[5.2]
-  def change
-    create_table :thing_without_histories do |t|
-      t.string :name
-    end
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20221018204220_create_silent_posts.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-class CreateSilentPosts < ActiveRecord::Migration[5.1]
-  def change
-    create_table :silent_posts do |t|
-      t.string :title, null: false
-      t.text :body, null: false
-      t.integer :author_id, null: false
-      t.boolean :enabled, default: false
-      t.datetime :live_at
-      t.datetime :deleted_at
-
-      t.timestamps
-    end
-
-    add_index :silent_posts, :author_id
-    add_index :silent_posts, :enabled
-    add_index :silent_posts, :live_at
-    add_index :silent_posts, :deleted_at
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20221018204255_create_silent_post_histories.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-require 'historiographer/postgres_migration'
-
-class CreateSilentPostHistories < ActiveRecord::Migration[5.1]
-  def change
-    create_table :silent_post_histories, &:histories
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20241109182017_create_comments.rb

@@ -1,13 +0,0 @@
-class CreateComments < ActiveRecord::Migration[7.1]
-  def change
-    create_table :comments do |t|
-      t.bigint :post_id
-      t.bigint :author_id
-      t.text :body
-      t.timestamps
-
-      t.index :post_id
-      t.index :author_id
-    end
-  end
-end

data/Users/brettshollenberger/programming/historiographer/spec/db/migrate/20241109182020_create_comment_histories.rb

@@ -1,9 +0,0 @@
-require 'historiographer/postgres_migration'
-
-class CreateCommentHistories < ActiveRecord::Migration[7.1]
-  def change
-    create_table :comment_histories do |t|
-      t.histories
-    end
-  end
-end