Module: Whodunit::MigrationHelpers

Defined in:
lib/whodunit/migration_helpers.rb

Overview

Database migration helpers for adding whodunit stamp columns.

This module provides convenient methods for adding creator/updater/deleter tracking columns to database tables based on configuration. Uses the configured column names and data types, and adds appropriate indexes for performance.

The helpers respect column enabling/disabling configuration: - Only adds columns that are enabled (not nil) in configuration - Uses configured column names and data types - Deleter column inclusion based on soft_delete_column configuration

Examples:

Add stamps to existing table

class AddWhodunitStampsToPosts < ActiveRecord::Migration[7.0]
  def change
    add_whodunit_stamps :posts
    # Adds enabled columns: creator_id, updater_id
    # Adds deleter_id if soft_delete_column is configured
  end
end

Add stamps to new table

class CreatePosts < ActiveRecord::Migration[7.0]
  def change
    create_table :posts do |t|
      t.string :title
      t.text :body
      t.whodunit_stamps
      t.timestamps
    end
  end
end

Custom data types and explicit deleter inclusion

add_whodunit_stamps :posts,
  creator_type: :string,
  updater_type: :uuid,
  include_deleter: true

With custom column configuration

# In config/initializers/whodunit.rb:
Whodunit.configure do |config|
  config.creator_column = :created_by_id
  config.deleter_column = nil  # Disable deleter column
  config.soft_delete_column = :archived_at
end

# Migration will use custom column names and only add enabled columns

Since:

  • 0.1.0

Instance Method Summary collapse

Instance Method Details

#add_whodunit_stamps(table_name, include_deleter: :auto, creator_type: nil, updater_type: nil, deleter_type: nil) ⇒ void

This method returns an undefined value.

Add creator/updater/deleter stamp columns to an existing table.

This method adds the configured whodunit columns to an existing table based on the current configuration. Only adds columns that are enabled (not nil). The deleter column is included based on soft_delete_column configuration when include_deleter is :auto, or explicitly when include_deleter is true. Indexes are automatically added for performance.

Examples:

Basic usage (uses configuration)

add_whodunit_stamps :posts

With custom types

add_whodunit_stamps :posts, creator_type: :string, updater_type: :uuid

Force deleter column inclusion

add_whodunit_stamps :posts, include_deleter: true

Exclude deleter column

add_whodunit_stamps :posts, include_deleter: false

Parameters:

  • table_name (Symbol) —

    the table to add stamps to

  • include_deleter (Symbol, Boolean) (defaults to: :auto) —

    :auto to check soft_delete_column configuration, true to force inclusion, false to exclude

  • creator_type (Symbol, nil) (defaults to: nil) —

    data type for creator column (defaults to configured type)

  • updater_type (Symbol, nil) (defaults to: nil) —

    data type for updater column (defaults to configured type)

  • deleter_type (Symbol, nil) (defaults to: nil) —

    data type for deleter column (defaults to configured type)

Since:

  • 0.1.0



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/whodunit/migration_helpers.rb', line 77

def add_whodunit_stamps(table_name, include_deleter: :auto, creator_type: nil, updater_type: nil, deleter_type: nil)
  if Whodunit.creator_enabled?
    add_column table_name, Whodunit.creator_column, creator_type || Whodunit.creator_data_type, null: true
  end

  if Whodunit.updater_enabled?
    add_column table_name, Whodunit.updater_column, updater_type || Whodunit.updater_data_type, null: true
  end

  if should_include_deleter?(include_deleter)
    add_column table_name, Whodunit.deleter_column, deleter_type || Whodunit.deleter_data_type, null: true
  end

  add_whodunit_indexes(table_name, include_deleter)
end

#remove_whodunit_stamps(table_name, include_deleter: :auto, **_options) ⇒ void

This method returns an undefined value.

Remove stamp columns from an existing table.

This method removes the configured creator, updater, and optionally deleter columns from an existing table. Only removes columns that are enabled in configuration and actually exist in the database.

Examples:

Basic usage (uses configuration)

remove_whodunit_stamps :posts

Force deleter removal

remove_whodunit_stamps :posts, include_deleter: true

Exclude deleter removal

remove_whodunit_stamps :posts, include_deleter: false

Parameters:

  • table_name (Symbol) —

    the table to remove stamps from

  • include_deleter (Symbol, Boolean) (defaults to: :auto) —

    :auto to check soft_delete_column configuration, true to force removal, false to exclude

  • _options (Hash) —

    additional options (reserved for future use)

Since:

  • 0.1.0



110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/whodunit/migration_helpers.rb', line 110

def remove_whodunit_stamps(table_name, include_deleter: :auto, **_options)
  if Whodunit.creator_enabled? && column_exists?(table_name, Whodunit.creator_column)
    remove_column table_name, Whodunit.creator_column
  end

  if Whodunit.updater_enabled? && column_exists?(table_name, Whodunit.updater_column)
    remove_column table_name, Whodunit.updater_column
  end

  if should_include_deleter?(include_deleter) &&
     column_exists?(table_name, Whodunit.deleter_column)
    remove_column table_name, Whodunit.deleter_column
  end
end

#whodunit_stamps(table_def = nil, include_deleter: :auto, creator_type: nil, updater_type: nil, deleter_type: nil) ⇒ void

This method returns an undefined value.

Add stamp columns to a table definition or existing table.

This method can be used in two ways: 1. Inside a create_table block (pass table definition as first argument) 2. As a standalone method in migrations (attempts to infer table name)

Only adds columns that are enabled in configuration. For new tables, deleter column is only added when explicitly requested (include_deleter: true) to be conservative.

Examples:

In create_table block (uses configuration)

create_table :posts do |t|
  t.string :title
  t.whodunit_stamps
end

Standalone (infers table from migration name)

def change
  whodunit_stamps  # Adds to inferred table
end

Force deleter column in new table

create_table :posts do |t|
  t.whodunit_stamps include_deleter: true
end

Parameters:

  • table_def (ActiveRecord::ConnectionAdapters::TableDefinition, nil) (defaults to: nil) —

    the table definition (when used in create_table block) or nil

  • include_deleter (Symbol, Boolean) (defaults to: :auto) —

    :auto to check soft_delete_column configuration, true to force inclusion, false to exclude

  • creator_type (Symbol, nil) (defaults to: nil) —

    data type for creator column (defaults to configured type)

  • updater_type (Symbol, nil) (defaults to: nil) —

    data type for updater column (defaults to configured type)

  • deleter_type (Symbol, nil) (defaults to: nil) —

    data type for deleter column (defaults to configured type)

Since:

  • 0.1.0



156
157
158
159
160
161
162
163
 
# File 'lib/whodunit/migration_helpers.rb', line 156

def whodunit_stamps(table_def = nil, include_deleter: :auto, creator_type: nil, updater_type: nil,
                    deleter_type: nil)
  if table_def.nil?
    handle_migration_stamps(include_deleter, creator_type, updater_type, deleter_type)
  else
    handle_table_definition_stamps(table_def, include_deleter, creator_type, updater_type, deleter_type)
  end
end