active_retention 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c34ad200a2c7661837737e32419ab22ab39cb6952e4490a546bb46b7b4e7cb79
+  data.tar.gz: de5471837bdbc5f1288cd406cc7945622806d46ed2f6291715c9da39d69767ce
+SHA512:
+  metadata.gz: 54347af50f9f13332ea1188767915aa2acefc45729e3fb084d6236b504742f0e01e6488f4ec3e4e01ff8ad8121b604db7287e51ad107d38d1daafafa59ffcd3a
+  data.tar.gz: 74bf0c70bb22406d5e8350ba3953424d24d0fc2b786114325f9ca0fb612f62db7ae16cd529deaedf432b2eab53960b941363f28a9b55e5abc57023749d70fdcf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ray West
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,352 @@
+# ActiveRetention
+
+Automatic data retention and purging for ActiveRecord models. Define how long records should live, choose what happens when they expire, and let ActiveRetention handle the cleanup.
+
+Built for production use at any scale — includes batch limiting, advisory locking, transactional archiving, and automatic backlog processing.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'active_retention'
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+ActiveRetention automatically integrates with Rails via a Railtie. No additional setup is needed. See [Configuration](#configuration) if you prefer opt-in inclusion.
+
+## Quick Start
+
+```ruby
+class Notification < ApplicationRecord
+  has_retention_policy period: 30.days, strategy: :destroy
+end
+```
+
+```ruby
+# Remove all notifications older than 30 days
+Notification.cleanup_retention!
+# => { count: 42, failed: 0, remaining: false, dry_run: false }
+```
+
+## Defining a Retention Policy
+
+Call `has_retention_policy` in any ActiveRecord model to configure how expired records are handled.
+
+```ruby
+has_retention_policy(
+  period:,              # Required — how long records are kept (e.g. 30.days, 1.year)
+  strategy: :destroy,   # Optional — :destroy, :delete_all, or :archive
+  column: :created_at,  # Optional — timestamp column used to determine age
+  if: nil,              # Optional — lambda to further filter which records are eligible
+  batch_limit: 10_000   # Optional — max records processed per cleanup call
+)
+```
+
+### Options
+
+#### `period` (required)
+
+An `ActiveSupport::Duration` representing the maximum age of a record. Records whose timestamp column is older than `period.ago` are considered expired.
+
+The minimum allowed period is **1 hour** to prevent accidental mass deletion.
+
+```ruby
+has_retention_policy period: 90.days
+has_retention_policy period: 1.year
+has_retention_policy period: 6.hours
+```
+
+#### `strategy` (optional, default: `:destroy`)
+
+Determines how expired records are removed.
+
+| Strategy      | Behavior                                                                 | Callbacks | Speed  |
+|---------------|--------------------------------------------------------------------------|-----------|--------|
+| `:destroy`    | Loads each record and calls `destroy`, one at a time via `find_each`     | Yes       | Slow   |
+| `:delete_all` | Bulk deletes matching records by plucking IDs, then issuing `DELETE`      | No        | Fast   |
+| `:archive`    | Copies records to an archive table in batches, then deletes the originals| No        | Medium |
+
+```ruby
+# Triggers model callbacks and dependent: :destroy associations
+has_retention_policy period: 30.days, strategy: :destroy
+
+# Fast bulk delete, skips callbacks entirely
+has_retention_policy period: 30.days, strategy: :delete_all
+
+# Preserve historical data before removing from the primary table
+has_retention_policy period: 30.days, strategy: :archive
+```
+
+**Note on `:destroy`**: If a `before_destroy` callback throws `:abort`, the record is preserved and counted as a failure in the return value. This means records protected by callbacks will never be silently deleted.
+
+#### `column` (optional, default: `:created_at`)
+
+The timestamp column used to determine whether a record has expired. Must be a valid column on the model's table. An `ArgumentError` is raised at boot time if the column does not exist.
+
+```ruby
+class Event < ApplicationRecord
+  has_retention_policy period: 90.days, column: :occurred_at
+end
+```
+
+#### `if` (optional)
+
+A lambda that returns an ActiveRecord scope. When provided, only expired records that also match this scope are eligible for cleanup.
+
+The lambda is evaluated in the context of the model's scope, so you can call query methods like `where` directly.
+
+```ruby
+class Notification < ApplicationRecord
+  has_retention_policy period: 30.days, strategy: :destroy, if: -> { where(read: true) }
+end
+```
+
+This will only clean up notifications that are both older than 30 days **and** marked as read.
+
+#### `batch_limit` (optional, default: `10_000`)
+
+The maximum number of records that will be processed in a single `cleanup_retention!` call. This prevents any single cleanup run from consuming unbounded time, memory, or database resources.
+
+```ruby
+# Process at most 5,000 records per run
+has_retention_policy period: 30.days, strategy: :destroy, batch_limit: 5_000
+
+# Large batch for fast delete_all on tables with many expired records
+has_retention_policy period: 7.days, strategy: :delete_all, batch_limit: 50_000
+```
+
+When the limit is reached, the return value includes `remaining: true` so callers know there are more records to process. The `PurgeJob` automatically re-enqueues itself to handle this (see [Background Job](#background-job)).
+
+## Running Cleanup
+
+### Manual Cleanup
+
+Call `cleanup_retention!` on any model with a retention policy:
+
+```ruby
+Notification.cleanup_retention!
+# => { count: 42, failed: 0, remaining: false, dry_run: false }
+```
+
+The method returns a hash with:
+
+| Key         | Type    | Description |
+|-------------|---------|-------------|
+| `count`     | Integer | Records actually removed |
+| `failed`    | Integer | Records where `destroy` returned false (`:destroy` strategy only) |
+| `remaining` | Boolean | `true` if more expired records exist beyond the `batch_limit` |
+| `dry_run`   | Boolean | Whether this was a dry run |
+| `skipped`   | Boolean | Present and `true` only if another process holds the cleanup lock |
+| `reason`    | Symbol  | `:locked` when `skipped` is true |
+
+### Dry Run
+
+Preview how many expired records exist without deleting anything:
+
+```ruby
+Notification.cleanup_retention!(dry_run: true)
+# => { count: 42, dry_run: true }
+```
+
+The `count` in dry run mode reflects the **total** number of expired records, regardless of `batch_limit`.
+
+### Background Job
+
+ActiveRetention ships with `ActiveRetention::PurgeJob`, an ActiveJob class that finds and cleans up all models with retention policies.
+
+```ruby
+ActiveRetention::PurgeJob.perform_later
+```
+
+The job:
+- **Eager-loads** all application models (if not already loaded) to discover every class with a retention policy
+- **Iterates** through each configured model and calls `cleanup_retention!`
+- **Logs** progress, record counts, and any errors to `Rails.logger`
+- **Rescues** errors per-model so that a failure in one model does not halt cleanup of others
+- **Skips** models that are already locked by another process (see [Concurrency Safety](#concurrency-safety))
+- **Auto-re-enqueues** when any model still has remaining expired records, up to 10 rounds per invocation
+
+The re-enqueue behavior ensures that large backlogs are fully cleared without waiting for the next scheduled run. The 10-round cap prevents infinite loops if records are being created faster than they can be purged.
+
+The job is queued as `:maintenance`. To run it on a recurring schedule, use a scheduler like [sidekiq-cron](https://github.com/sidekiq-cron/sidekiq-cron), [solid_queue](https://github.com/rails/solid_queue), or [whenever](https://github.com/javan/whenever):
+
+```ruby
+# Example with sidekiq-cron
+Sidekiq::Cron::Job.create(
+  name: 'ActiveRetention purge - daily',
+  cron: '0 3 * * *',
+  class: 'ActiveRetention::PurgeJob'
+)
+```
+
+## Concurrency Safety
+
+ActiveRetention uses **database-level advisory locks** to prevent concurrent cleanup of the same model. This protects against:
+- Duplicate archive rows from two processes archiving the same records
+- Attempting to destroy already-deleted records
+- Wasted work from overlapping cleanup runs
+
+| Database   | Lock Mechanism                           |
+|------------|------------------------------------------|
+| PostgreSQL | `pg_try_advisory_lock` / `pg_advisory_unlock` |
+| MySQL      | `GET_LOCK` / `RELEASE_LOCK`              |
+| SQLite     | Ruby `Mutex` (in-process only)           |
+
+Locks are **non-blocking**: if a lock is already held, `cleanup_retention!` returns immediately with `{ skipped: true, reason: :locked }` instead of waiting. This means the `PurgeJob` never stalls — it simply skips the locked model and moves on.
+
+## Scopes
+
+Declaring a retention policy adds an `expired_records` scope to the model. You can use this scope independently of cleanup:
+
+```ruby
+Notification.expired_records
+# => ActiveRecord::Relation of all notifications older than 30 days
+
+Notification.expired_records.count
+# => 42
+```
+
+## Archive Strategy
+
+The `:archive` strategy copies expired records into a separate archive table before deleting the originals. This is useful when you need to enforce retention limits on your primary table but want to preserve historical data for auditing or analytics.
+
+### How It Works
+
+1. Before archiving begins, ActiveRetention verifies the archive table exists. If it doesn't, an `ActiveRetention::ArchiveTableMissing` error is raised with instructions to generate it — no records are touched.
+2. Expired records are loaded in batches (up to 500 records or the `batch_limit`, whichever is smaller).
+3. Within a database transaction for each batch:
+   - Record attributes (except `id`) are inserted into the archive table in sub-batches of 50 rows to avoid oversized SQL statements
+   - The original records are deleted from the primary table
+   - If either the insert or delete fails, the **entire batch is rolled back** — originals are never lost
+4. The archive table automatically receives an `archived_at` timestamp.
+
+### Generating the Archive Table
+
+Use the built-in Rails generator to create a migration for the archive table:
+
+```sh
+rails generate active_retention:archive Notification
+```
+
+This generates a migration that creates a `notifications_archive` table mirroring all columns from `notifications` (except `id`), plus an `archived_at` timestamp column. The table uses `bigserial` for its own primary key and includes indexes on `created_at` and `archived_at`.
+
+Then run the migration:
+
+```sh
+rails db:migrate
+```
+
+**Important**: You must run the generator and migration before using `strategy: :archive`. If the archive table is missing, `cleanup_retention!` will raise `ActiveRetention::ArchiveTableMissing` rather than silently failing.
+
+### Archive Table Naming
+
+The archive table name is derived automatically from the model's table name:
+
+| Model Table     | Archive Table            |
+|-----------------|--------------------------|
+| `notifications` | `notifications_archive`  |
+| `events`        | `events_archive`         |
+| `audit_logs`    | `audit_logs_archive`     |
+
+## Validation
+
+ActiveRetention validates all configuration at definition time (when your Rails app boots), not at cleanup time. Invalid configuration raises `ArgumentError` immediately:
+
+```ruby
+# Raises ArgumentError — column doesn't exist on the table
+has_retention_policy period: 30.days, column: :nonexistent
+
+# Raises ArgumentError — unknown strategy
+has_retention_policy period: 30.days, strategy: :soft_delete
+
+# Raises ArgumentError — period too short (minimum is 1 hour)
+has_retention_policy period: 30.seconds
+
+# Raises ArgumentError — batch_limit must be a positive integer
+has_retention_policy period: 30.days, batch_limit: -1
+```
+
+## STI Support
+
+Retention configs are defined using `class_attribute`, which means they are inherited by subclasses. If you use Single Table Inheritance, the parent's retention policy applies to all subclasses unless explicitly overridden:
+
+```ruby
+class Notification < ApplicationRecord
+  has_retention_policy period: 30.days, strategy: :destroy
+end
+
+class AdminNotification < Notification
+  # Inherits the 30-day destroy policy from Notification
+end
+
+class SystemAlert < Notification
+  # Override with a longer retention period
+  has_retention_policy period: 1.year, strategy: :archive
+end
+```
+
+## Configuration
+
+### Auto-Include (default: enabled)
+
+By default, ActiveRetention automatically includes itself into all ActiveRecord models via a Railtie. This adds a single `class_attribute` (`retention_config`, defaulting to `nil`) and makes `has_retention_policy` available everywhere. No cleanup runs unless you explicitly call `has_retention_policy` on a model.
+
+If you prefer to opt in per model, disable auto-include in an initializer:
+
+```ruby
+# config/initializers/active_retention.rb
+ActiveRetention.configure do |config|
+  config.auto_include = false
+end
+```
+
+Then include the module explicitly on each model that needs it:
+
+```ruby
+class Notification < ApplicationRecord
+  include ActiveRetention::ModelExtension
+  has_retention_policy period: 30.days, strategy: :destroy
+end
+```
+
+## Full Example
+
+```ruby
+class AuditLog < ApplicationRecord
+  has_retention_policy period: 1.year,
+                       strategy: :archive,
+                       column: :created_at,
+                       batch_limit: 25_000
+end
+
+class Session < ApplicationRecord
+  has_retention_policy period: 24.hours,
+                       strategy: :delete_all,
+                       batch_limit: 50_000
+end
+
+class Notification < ApplicationRecord
+  has_retention_policy period: 30.days,
+                       strategy: :destroy,
+                       if: -> { where(read: true) }
+end
+```
+
+```ruby
+# Preview what would be cleaned up (reports total, ignores batch_limit)
+AuditLog.cleanup_retention!(dry_run: true)
+# => { count: 150_204, dry_run: true }
+
+# Run cleanup (processes up to 25,000 per call)
+AuditLog.cleanup_retention!
+# => { count: 25_000, remaining: true, dry_run: false }
+
+# Or clean up everything via the background job (auto-re-enqueues until clear)
+ActiveRetention::PurgeJob.perform_later
+```

data/lib/active_retention/configuration.rb

@@ -0,0 +1,9 @@
+module ActiveRetention
+  class Configuration
+    attr_accessor :auto_include
+
+    def initialize
+      @auto_include = true
+    end
+  end
+end

data/lib/active_retention/errors.rb

@@ -0,0 +1,3 @@
+module ActiveRetention
+  class ArchiveTableMissing < StandardError; end
+end

data/lib/active_retention/model_extension.rb

@@ -0,0 +1,221 @@
+require 'active_support/concern'
+require 'active_support/core_ext/numeric/time'
+require 'zlib'
+require 'active_retention/errors'
+
+module ActiveRetention
+  module ModelExtension
+    extend ActiveSupport::Concern
+
+    MINIMUM_RETENTION_PERIOD = 1.hour
+    DEFAULT_BATCH_LIMIT = 10_000
+    ARCHIVE_INSERT_BATCH_SIZE = 50
+
+    class_methods do
+      def has_retention_policy(period:, strategy: :destroy, **options)
+        column = (options[:column] || :created_at).to_s
+        batch_limit = options.fetch(:batch_limit, DEFAULT_BATCH_LIMIT)
+
+        unless column_names.include?(column)
+          raise ArgumentError, "Unknown column '#{column}' for #{table_name}"
+        end
+
+        unless %i[destroy delete_all archive].include?(strategy)
+          raise ArgumentError, "Unknown strategy '#{strategy}'. Must be :destroy, :delete_all, or :archive"
+        end
+
+        if period < MINIMUM_RETENTION_PERIOD
+          raise ArgumentError,
+            "Retention period must be at least #{MINIMUM_RETENTION_PERIOD.inspect}. " \
+            "A very short period risks accidental mass deletion."
+        end
+
+        unless batch_limit.is_a?(Integer) && batch_limit > 0
+          raise ArgumentError, "batch_limit must be a positive integer, got #{batch_limit.inspect}"
+        end
+
+        self.retention_config = {
+          period: period,
+          strategy: strategy,
+          filter: options[:if],
+          column: column,
+          batch_limit: batch_limit
+        }
+
+        scope :expired_records, -> {
+          quoted_column = "#{connection.quote_table_name(table_name)}.#{connection.quote_column_name(retention_config[:column])}"
+          where("#{quoted_column} < ?", retention_config[:period].ago)
+        }
+      end
+
+      def cleanup_retention!(dry_run: false)
+        return unless retention_config
+
+        with_retention_lock do
+          perform_cleanup!(dry_run: dry_run)
+        end
+      end
+
+      private
+
+      def perform_cleanup!(dry_run:)
+        scope = expired_records
+        scope = scope.merge(scope.instance_exec(&retention_config[:filter])) if retention_config[:filter]
+
+        total_expired = scope.count
+        return { count: total_expired, dry_run: true } if dry_run
+
+        batch_limit = retention_config[:batch_limit]
+
+        result = case retention_config[:strategy]
+        when :destroy
+          perform_destroy_cleanup(scope, batch_limit)
+        when :delete_all
+          perform_delete_all_cleanup(scope, batch_limit)
+        when :archive
+          validate_archive_table!
+          perform_archive_cleanup(scope, batch_limit)
+        end
+
+        result.merge(remaining: total_expired > result[:count])
+      end
+
+      def perform_destroy_cleanup(scope, batch_limit)
+        destroyed = 0
+        failed = 0
+
+        scope.find_each do |record|
+          break if destroyed + failed >= batch_limit
+
+          if record.destroy
+            destroyed += 1
+          else
+            failed += 1
+          end
+        end
+
+        { count: destroyed, failed: failed, dry_run: false }
+      end
+
+      def perform_delete_all_cleanup(scope, batch_limit)
+        ids = scope.limit(batch_limit).pluck(:id)
+        deleted = ids.any? ? where(id: ids).delete_all : 0
+
+        { count: deleted, dry_run: false }
+      end
+
+      def perform_archive_cleanup(scope, batch_limit)
+        archived = archive_retention!(scope, batch_limit: batch_limit)
+
+        { count: archived, dry_run: false }
+      end
+
+      def validate_archive_table!
+        archive_table = "#{table_name}_archive"
+        unless connection.table_exists?(archive_table)
+          raise ActiveRetention::ArchiveTableMissing,
+            "Archive table '#{archive_table}' does not exist. " \
+            "Run `rails generate active_retention:archive #{name}` to create it."
+        end
+      end
+
+      def archive_retention!(scope, batch_limit:)
+        archive_table = "#{table_name}_archive"
+        total_archived = 0
+
+        scope.find_in_batches(batch_size: [500, batch_limit].min) do |batch|
+          remaining = batch_limit - total_archived
+          batch = batch.first(remaining) if batch.size > remaining
+
+          transaction do
+            data = batch.map { |r| r.attributes.except('id') }
+
+            if data.any?
+              columns = data.first.keys
+              quoted_columns = columns.map { |c| connection.quote_column_name(c) }.join(', ')
+
+              data.each_slice(ARCHIVE_INSERT_BATCH_SIZE) do |chunk|
+                values_sql = chunk.map do |row|
+                  "(#{columns.map { |c| connection.quote(row[c]) }.join(', ')})"
+                end.join(', ')
+
+                sql = "INSERT INTO #{connection.quote_table_name(archive_table)} (#{quoted_columns}) VALUES #{values_sql}"
+                connection.execute(sql)
+              end
+            end
+
+            where(id: batch.map(&:id)).delete_all
+            total_archived += batch.size
+          end
+
+          break if total_archived >= batch_limit
+        end
+
+        total_archived
+      end
+
+      # --- Advisory Locking ---
+
+      def with_retention_lock
+        adapter = connection.adapter_name.downcase
+
+        case adapter
+        when /postgres/
+          with_pg_advisory_lock { yield }
+        when /mysql/
+          with_mysql_lock { yield }
+        else
+          with_mutex_lock { yield }
+        end
+      end
+
+      def retention_lock_key
+        Zlib.crc32("active_retention:#{table_name}") & 0x7FFFFFFF
+      end
+
+      def with_pg_advisory_lock
+        locked = connection.select_value("SELECT pg_try_advisory_lock(#{retention_lock_key})")
+        return skipped_result unless locked
+
+        begin
+          yield
+        ensure
+          connection.execute("SELECT pg_advisory_unlock(#{retention_lock_key})")
+        end
+      end
+
+      def with_mysql_lock
+        result = connection.select_value("SELECT GET_LOCK('active_retention_#{table_name}', 0)")
+        return skipped_result unless result == 1
+
+        begin
+          yield
+        ensure
+          connection.execute("SELECT RELEASE_LOCK('active_retention_#{table_name}')")
+        end
+      end
+
+      def with_mutex_lock
+        @_retention_mutex ||= Mutex.new
+
+        if @_retention_mutex.try_lock
+          begin
+            yield
+          ensure
+            @_retention_mutex.unlock
+          end
+        else
+          skipped_result
+        end
+      end
+
+      def skipped_result
+        { count: 0, skipped: true, reason: :locked, dry_run: false }
+      end
+    end
+
+    included do
+      class_attribute :retention_config, instance_writer: false, default: nil
+    end
+  end
+end

data/lib/active_retention/purge_job.rb

@@ -0,0 +1,43 @@
+module ActiveRetention
+  class PurgeJob < ActiveJob::Base
+    queue_as :maintenance
+
+    MAX_REENQUEUE_ROUNDS = 10
+
+    def perform(round: 1)
+      Rails.application.eager_load! unless Rails.application.config.eager_load
+
+      has_remaining = false
+
+      models_with_retention.each do |model|
+        Rails.logger.info "[ActiveRetention] Purging #{model.name} (round #{round})..."
+
+        result = model.cleanup_retention!
+
+        if result&.dig(:skipped)
+          Rails.logger.info "[ActiveRetention] Skipped #{model.name} (already locked by another process)."
+        else
+          Rails.logger.info "[ActiveRetention] Cleaned up #{result[:count]} #{model.name} records."
+          has_remaining = true if result[:remaining]
+        end
+      rescue StandardError => e
+        Rails.logger.error "[ActiveRetention] Failed to purge #{model.name}: #{e.message}"
+      end
+
+      if has_remaining && round < MAX_REENQUEUE_ROUNDS
+        Rails.logger.info "[ActiveRetention] Re-enqueueing (round #{round + 1}/#{MAX_REENQUEUE_ROUNDS}) — models still have expired records."
+        self.class.perform_later(round: round + 1)
+      elsif has_remaining
+        Rails.logger.warn "[ActiveRetention] Reached maximum of #{MAX_REENQUEUE_ROUNDS} rounds. Some expired records remain."
+      end
+    end
+
+    private
+
+    def models_with_retention
+      ActiveRecord::Base.descendants.select do |model|
+        model.respond_to?(:retention_config) && model.retention_config.present?
+      end
+    end
+  end
+end

data/lib/active_retention/version.rb

@@ -0,0 +1,3 @@
+module ActiveRetention
+  VERSION = "0.1.0"
+end

data/lib/active_retention.rb

@@ -0,0 +1,28 @@
+require "active_retention/version"
+require "active_retention/errors"
+require "active_retention/configuration"
+require "active_retention/model_extension"
+require "active_retention/purge_job"
+
+module ActiveRetention
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  self.configuration = Configuration.new
+
+  class Railtie < Rails::Railtie
+    initializer "active_retention.model_extension" do
+      if ActiveRetention.configuration.auto_include
+        ActiveSupport.on_load(:active_record) do
+          include ActiveRetention::ModelExtension
+        end
+      end
+    end
+  end
+end

data/lib/generators/active_retention/archive_generator.rb

@@ -0,0 +1,22 @@
+require 'rails/generators/active_record'
+
+module ActiveRetention
+  module Generators
+    class ArchiveGenerator < ActiveRecord::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_migration_file
+        @model_name = name.camelize
+        @table_name = name.underscore.pluralize
+        @archive_table_name = "#{@table_name}_archive"
+        migration_template "archive_migration.rb.erb", "db/migrate/create_#{@archive_table_name}.rb"
+      end
+
+      private
+
+      def model_columns
+        @model_name.constantize.columns.reject { |c| c.name == 'id' }
+      end
+    end
+  end
+end

data/lib/generators/active_retention/templates/archive_migration.rb.erb

@@ -0,0 +1,13 @@
+class Create<%= @archive_table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= @archive_table_name %>, id: :bigserial do |t|
+<% model_columns.each do |column| -%>
+      t.<%= column.type %> :<%= column.name %><%= ", limit: #{column.limit.inspect}" unless column.limit.nil? %><%= ", precision: #{column.precision.inspect}" unless column.precision.nil? %><%= ", scale: #{column.scale.inspect}" unless column.scale.nil? %><%= ", null: #{column.null}" unless column.null %>
+<% end -%>
+      t.datetime :archived_at, null: false, default: -> { 'CURRENT_TIMESTAMP' }
+    end
+
+    add_index :<%= @archive_table_name %>, :created_at
+    add_index :<%= @archive_table_name %>, :archived_at
+  end
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: active_retention
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ray West
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Define retention policies on ActiveRecord models to automatically destroy,
+  delete, or archive expired records. Includes batch limiting, advisory locking, transactional
+  archiving, and background job support.
+email:
+- ray@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/active_retention.rb
+- lib/active_retention/configuration.rb
+- lib/active_retention/errors.rb
+- lib/active_retention/model_extension.rb
+- lib/active_retention/purge_job.rb
+- lib/active_retention/version.rb
+- lib/generators/active_retention/archive_generator.rb
+- lib/generators/active_retention/templates/archive_migration.rb.erb
+homepage: https://github.com/raywest/active_retention
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/raywest/active_retention
+  source_code_uri: https://github.com/raywest/active_retention
+  changelog_uri: https://github.com/raywest/active_retention/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Automatic data retention and purging for ActiveRecord models.
+test_files: []