cold_storage 0.1.0

data/lib/cold_storage/tasks/cold_storage.rake

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+namespace :cold_storage do
+  desc 'List the archivable models, their rule, pending/archived counts and last run'
+  task status: :environment do
+    puts ColdStorage.report
+  end
+
+  namespace :db do
+    # ActiveRecord's database tasks leave ActiveRecord::Base connected to the
+    # database they just touched, which would send the rest of the process to
+    # the archive. Put the primary connection back.
+    def with_primary_connection_restored
+      yield
+    ensure
+      ActiveRecord::Base.establish_connection(Rails.env.to_sym)
+    end
+
+    desc 'Create the archive database'
+    task create: :environment do
+      config = ColdStorage::ArchiveRecord.database_config
+      abort('No archive database configured (see config/database.yml)') if config.nil?
+
+      with_primary_connection_restored { ActiveRecord::Tasks::DatabaseTasks.create(config) }
+      puts "Created #{config.database}"
+    end
+
+    desc 'Drop the archive database (asks for DISPOSABLE=1)'
+    task drop: :environment do
+      abort('Refusing to drop the archive database without DISPOSABLE=1') unless ENV['DISPOSABLE'] == '1'
+
+      config = ColdStorage::ArchiveRecord.database_config
+      abort('No archive database configured (see config/database.yml)') if config.nil?
+
+      with_primary_connection_restored { ActiveRecord::Tasks::DatabaseTasks.drop(config) }
+      puts "Dropped #{config.database}"
+    end
+  end
+
+  namespace :schema do
+    desc 'Copy/update the archive database schema for the archivable models'
+    task sync: :environment do
+      changes = ColdStorage.sync_schema!
+      puts changes.empty? ? 'Archive schema already up to date.' : "Applied #{changes.size} change(s)."
+    end
+
+    desc 'Show what cold_storage:schema:sync would change'
+    task plan: :environment do
+      changes = ColdStorage.schema_drift
+      if changes.empty?
+        puts 'Archive schema is up to date.'
+      else
+        changes.each { |change| puts "  #{change}" }
+      end
+    end
+
+    desc 'Exit non-zero when the archive schema drifted from the primary one (for CI)'
+    task check: :environment do
+      changes = ColdStorage.schema_drift.reject { |change| change.type == :extra_column }
+      next puts('Archive schema is up to date.') if changes.empty?
+
+      changes.each { |change| warn "  #{change}" }
+      abort("Archive schema is #{changes.size} change(s) behind. Run rails cold_storage:schema:sync")
+    end
+  end
+
+  desc 'Archive one model: rake cold_storage:archive[Payroll]'
+  task :archive, %i[model] => :environment do |_task, args|
+    abort('Usage: rake cold_storage:archive[ModelName]') if args[:model].blank?
+
+    result = ColdStorage.archive(
+      args[:model].constantize,
+      force: ENV['FORCE'] != 'false',
+      dry_run: ENV['DRY_RUN'] == 'true',
+      limit: ENV['LIMIT']&.to_i
+    )
+    puts result
+  end
+
+  desc 'Archive every archivable model whose schedule is due'
+  task archive_all: :environment do
+    results = ColdStorage.archive_all(
+      force: ENV['FORCE'] == 'true',
+      dry_run: ENV['DRY_RUN'] == 'true'
+    )
+    results.each { |result| puts result }
+  end
+
+  desc 'Restore archived rows: rake cold_storage:restore[Payroll,1 2 3] (WITH=all|assoc,assoc)'
+  task :restore, %i[model ids] => :environment do |_task, args|
+    abort('Usage: rake cold_storage:restore[ModelName,"1 2 3"]') if args[:model].blank? || args[:ids].blank?
+
+    with = case ENV['WITH']
+           when nil, '' then nil
+           when 'all' then :all
+           else ENV['WITH'].split(',').map { |name| name.strip.to_sym }
+           end
+
+    count = ColdStorage.restore(args[:model].constantize, args[:ids].split.map(&:strip), with: with)
+    puts "Restored #{count} row(s)."
+  end
+end

data/lib/cold_storage/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ColdStorage
+  VERSION = '0.1.0'
+end

data/lib/cold_storage.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_support'
+require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/time'
+require 'active_support/concern'
+
+require 'cold_storage/version'
+require 'cold_storage/configuration'
+require 'cold_storage/logging'
+require 'cold_storage/row_reader'
+require 'cold_storage/association_tree'
+require 'cold_storage/registry'
+require 'cold_storage/policy'
+require 'cold_storage/archive_record'
+require 'cold_storage/archive_model'
+require 'cold_storage/internal_schema'
+require 'cold_storage/run'
+require 'cold_storage/metadata'
+require 'cold_storage/archivable'
+require 'cold_storage/model'
+require 'cold_storage/schema_mirror'
+require 'cold_storage/archiver'
+require 'cold_storage/restorer'
+require 'cold_storage/report'
+require 'cold_storage/jobs'
+require 'cold_storage/railtie' if defined?(Rails::Railtie)
+
+# Moves rows that are past their retention window (or soft-deleted) out of the
+# primary database and into a mirrored archive database.
+#
+#   class Payroll < ApplicationRecord
+#     archivable after: 18.months, every: 1.month
+#   end
+#
+# See README.md for the full option list.
+module ColdStorage
+  # Base class for every error raised by the gem.
+  Error = Class.new(StandardError)
+  # Raised when the archive database is missing or misconfigured.
+  ConfigurationError = Class.new(Error)
+  # Raised when a model was never declared `archivable`.
+  NotArchivableError = Class.new(Error)
+  # Raised when the archive database has no table for a model yet.
+  SchemaMissingError = Class.new(Error)
+  # Raised when an `archivable` declaration is not usable.
+  InvalidPolicyError = Class.new(ArgumentError)
+
+  class << self
+    # @return [ColdStorage::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # @yieldparam config [ColdStorage::Configuration]
+    def configure
+      yield config
+      config
+    end
+
+    # Every model that called `archivable`, in declaration-independent order.
+    #
+    # @param eager_load [Boolean] load the app's classes first so models that
+    #   were never referenced in this process are still discovered.
+    # @return [Array<Class>]
+    def models(eager_load: true)
+      Registry.models(eager_load: eager_load)
+    end
+
+    # @return [Logger]
+    def logger
+      config.logger ||= Logger.new($stdout)
+    end
+
+    # Archives one model according to its policy.
+    #
+    # @return [ColdStorage::Archiver::Result]
+    def archive(model, **options)
+      Archiver.new(model, **options).call
+    end
+
+    # Archives every registered model. Models whose `every:` window has not
+    # elapsed are skipped unless `force: true`.
+    #
+    # @return [Array<ColdStorage::Archiver::Result>]
+    def archive_all(**options)
+      models.map { |model| archive(model, **options) }
+    end
+
+    # Moves rows back from the archive database into the primary one.
+    #
+    #   ColdStorage.restore(Invoice, [1, 2])
+    #   ColdStorage.restore(Invoice, [1, 2], with: :all)
+    #   ColdStorage.restore(Invoice, Invoice.archived.where(year: 2019),
+    #                          with: [:invoice_lines])
+    #
+    # @param ids [Array, ActiveRecord::Relation]
+    # @return [Integer] number of restored rows, children included
+    def restore(model, ids, **options)
+      Restorer.new(model, **options).call(ids)
+    end
+
+    # The archive-database counterpart of a model, for models that are not
+    # archivable themselves (a cascade child, say).
+    #
+    # @return [Class]
+    def archived_model(model)
+      ArchiveModel.for(model)
+    end
+
+    # Creates/updates the archive database tables for the archivable models.
+    #
+    # @return [Array<ColdStorage::SchemaMirror::Change>]
+    def sync_schema!(**options)
+      SchemaMirror.new(**options).sync!
+    end
+
+    # The changes `sync_schema!` would apply. Empty means the archive database
+    # is up to date.
+    #
+    # @return [Array<ColdStorage::SchemaMirror::Change>]
+    def schema_drift(**options)
+      SchemaMirror.new(**options).plan
+    end
+
+    # @return [String] human readable status of every archivable model
+    def report(**options)
+      Report.new(**options).to_s
+    end
+
+    # @api private
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/generators/cold_storage/install/install_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module ColdStorage
+  module Generators
+    # rails generate cold_storage:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates the ColdStorage initializer and prints the database.yml snippet.'
+
+      def create_initializer
+        template 'initializer.rb.tt', 'config/initializers/cold_storage.rb'
+      end
+
+      def show_database_instructions
+        say <<~MESSAGE
+
+          Add the archive database to config/database.yml, in every environment
+          that should archive (note `database_tasks: false`, it keeps `rails
+          db:migrate` from applying your migrations to the archive database):
+
+            #{ColdStorage.config.archive_database}:
+              <<: *default
+              database: <%= ENV.fetch('ARCHIVE_POSTGRES_DB') %>
+              database_tasks: false
+
+          Then:
+
+            rails cold_storage:db:create
+            rails cold_storage:schema:sync
+            rails cold_storage:status
+
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/generators/cold_storage/install/templates/initializer.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+ColdStorage.configure do |config|
+  # Master switch. The test environment has no archive database, and specs
+  # destroy records all the time.
+  config.enabled = !Rails.env.test?
+
+  # database.yml entry holding the archive database.
+  config.archive_database = :archive
+
+  # Rows moved per round trip.
+  config.batch_size = 1_000
+
+  # Defaults used by `archivable` when a model does not say otherwise.
+  config.timestamp_column = :created_at
+  config.deleted_column   = :deleted_at
+
+  # Extra column stamped on every archived row (set to nil to disable).
+  config.archived_at_column = :archived_at
+
+  # Delete the rows from the primary database once they are safely copied.
+  config.delete_after_archive = true
+
+  # Mirror the schema right after db:migrate / db:schema:load.
+  config.sync_schema_after_migrate = Rails.env.local?
+
+  # :warn, :raise, :change or :ignore when a column type differs.
+  config.on_type_mismatch = :warn
+
+  # `on_destroy: true` models: :raise blocks the delete when the archive cannot
+  # be reached, :log lets it through.
+  config.on_destroy_error = :raise
+
+  # Queue used by ColdStorage::ArchiveAllJob / ArchiveModelJob.
+  config.job_queue = :default
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: cold_storage
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Afshin Amini
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: |
+  Add `archivable` to any model to move old or soft-deleted rows into a separate
+  archive database. The archive database schema is mirrored from the primary one
+  and kept in sync on every migration, for the archivable models only.
+email:
+- afshmini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/cold_storage.rb
+- lib/cold_storage/archivable.rb
+- lib/cold_storage/archive_model.rb
+- lib/cold_storage/archive_record.rb
+- lib/cold_storage/archiver.rb
+- lib/cold_storage/association_tree.rb
+- lib/cold_storage/configuration.rb
+- lib/cold_storage/internal_schema.rb
+- lib/cold_storage/jobs.rb
+- lib/cold_storage/logging.rb
+- lib/cold_storage/metadata.rb
+- lib/cold_storage/model.rb
+- lib/cold_storage/policy.rb
+- lib/cold_storage/railtie.rb
+- lib/cold_storage/registry.rb
+- lib/cold_storage/report.rb
+- lib/cold_storage/restorer.rb
+- lib/cold_storage/row_reader.rb
+- lib/cold_storage/run.rb
+- lib/cold_storage/schema_mirror.rb
+- lib/cold_storage/tasks/cold_storage.rake
+- lib/cold_storage/version.rb
+- lib/generators/cold_storage/install/install_generator.rb
+- lib/generators/cold_storage/install/templates/initializer.rb.tt
+homepage: https://github.com/afshmini/cold_storage
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/afshmini/cold_storage
+  changelog_uri: https://github.com/afshmini/cold_storage/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/afshmini/cold_storage/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Declarative auto-archiving of ActiveRecord rows into a mirrored archive database.
+test_files: []