anima-core 0.2.1 → 1.0.0

data/skills/activerecord/examples/migrations/safe_patterns.rb

@@ -0,0 +1,420 @@
+# ActiveRecord Migration Examples: Safe Production Patterns
+# Patterns for zero-downtime deployments and large table migrations
+
+# =============================================================================
+# SAFE COLUMN REMOVAL (3-Release Process)
+# =============================================================================
+
+# RELEASE 1: Add to ignored_columns in model
+# app/models/user.rb
+class User < ApplicationRecord
+  # Step 1: Tell ActiveRecord to ignore this column
+  # This prevents errors when old code still references it
+  self.ignored_columns += ["legacy_field"]
+end
+
+# RELEASE 2: Drop the column
+class RemoveLegacyField < ActiveRecord::Migration[7.2]
+  def change
+    # Safe to remove now - code doesn't reference it
+    remove_column :users, :legacy_field, :string
+  end
+end
+
+# RELEASE 3: Remove ignored_columns line from model
+
+# =============================================================================
+# SAFE NOT NULL ADDITION (PostgreSQL)
+# =============================================================================
+
+# Adding NOT NULL to existing column can lock table while validating all rows
+# Split into multiple steps for large tables
+
+# Step 1: Add check constraint without validation
+class AddNotNullConstraintStep1 < ActiveRecord::Migration[7.2]
+  def change
+    add_check_constraint :users, "email IS NOT NULL",
+                         name: "users_email_not_null",
+                         validate: false
+  end
+end
+
+# Step 2: Validate constraint (separate deployment)
+class AddNotNullConstraintStep2 < ActiveRecord::Migration[7.2]
+  def change
+    validate_check_constraint :users, name: "users_email_not_null"
+  end
+end
+
+# Step 3: Add actual NOT NULL and remove constraint
+class AddNotNullConstraintStep3 < ActiveRecord::Migration[7.2]
+  def change
+    change_column_null :users, :email, false
+    remove_check_constraint :users, name: "users_email_not_null"
+  end
+end
+
+# =============================================================================
+# SAFE COLUMN ADDITION WITH DEFAULT
+# =============================================================================
+
+# Modern Rails (5.2+) handles this efficiently, but for very large tables:
+
+# Option 1: Add column, backfill, then set default
+class AddStatusSafely < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def up
+    # Step 1: Add column without default
+    add_column :orders, :priority, :string
+
+    # Step 2: Backfill in batches
+    Order.unscoped.in_batches(of: 10_000) do |batch|
+      batch.update_all(priority: "normal")
+      sleep(0.1)  # Throttle
+    end
+
+    # Step 3: Set default for new records
+    change_column_default :orders, :priority, "normal"
+
+    # Step 4: Add NOT NULL if needed
+    change_column_null :orders, :priority, false
+  end
+
+  def down
+    remove_column :orders, :priority
+  end
+end
+
+# =============================================================================
+# SAFE COLUMN RENAME (Dual-Write Pattern)
+# =============================================================================
+
+# Renaming columns breaks running code that references old name
+# Use alias_attribute + phased deployment
+
+# RELEASE 1: Add new column, dual-write
+class RenameNameToFullNameStep1 < ActiveRecord::Migration[7.2]
+  def change
+    add_column :users, :full_name, :string
+  end
+end
+
+# app/models/user.rb (Release 1)
+class User < ApplicationRecord
+  # Dual-write to both columns
+  before_save :sync_name_columns
+
+  # Read from new column, fall back to old
+  def full_name
+    super || name
+  end
+
+  private
+
+  def sync_name_columns
+    self.full_name = name if name_changed?
+    self.name = full_name if full_name_changed?
+  end
+end
+
+# RELEASE 2: Backfill existing data
+class RenameNameToFullNameStep2 < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def up
+    User.unscoped.where(full_name: nil).in_batches(of: 10_000) do |batch|
+      batch.update_all("full_name = name")
+      sleep(0.1)
+    end
+  end
+end
+
+# RELEASE 3: Switch to new column, stop dual-write
+# Update all code to use full_name, remove sync callback
+
+# RELEASE 4: Remove old column (use safe removal pattern)
+class RenameNameToFullNameStep4 < ActiveRecord::Migration[7.2]
+  def change
+    remove_column :users, :name, :string
+  end
+end
+
+# =============================================================================
+# SAFE TYPE CHANGE
+# =============================================================================
+
+# Changing column type often rewrites entire table
+# Use new column + migration instead
+
+class ChangeIdToUuid < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def up
+    # Add new UUID column
+    add_column :products, :uuid, :uuid, default: "gen_random_uuid()"
+
+    # Backfill existing records
+    Product.unscoped.in_batches(of: 10_000) do |batch|
+      batch.update_all("uuid = gen_random_uuid()")
+      sleep(0.1)
+    end
+
+    # Add unique index
+    add_index :products, :uuid, unique: true, algorithm: :concurrently
+
+    # Now update foreign keys and code to use uuid
+    # Then in later migration, remove old id column
+  end
+
+  def down
+    remove_column :products, :uuid
+  end
+end
+
+# =============================================================================
+# SAFE INDEX CREATION
+# =============================================================================
+
+class AddIndexSafely < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!  # Required for concurrent
+
+  def change
+    add_index :users, :email,
+              unique: true,
+              algorithm: :concurrently,
+              name: "index_users_on_email_unique"
+  end
+end
+
+# With if_not_exists for idempotency
+class AddIndexIdempotent < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def change
+    add_index :users, :email, algorithm: :concurrently, if_not_exists: true
+  end
+end
+
+# =============================================================================
+# SAFE FOREIGN KEY ADDITION
+# =============================================================================
+
+# Foreign keys validate all rows on creation, which can lock tables
+
+# Step 1: Add without validation
+class AddForeignKeySafely1 < ActiveRecord::Migration[7.2]
+  def change
+    add_foreign_key :orders, :users, validate: false
+  end
+end
+
+# Step 2: Validate in separate migration
+class AddForeignKeySafely2 < ActiveRecord::Migration[7.2]
+  def change
+    validate_foreign_key :orders, :users
+  end
+end
+
+# =============================================================================
+# SAFE DATA BACKFILL
+# =============================================================================
+
+class BackfillUserStatus < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def up
+    # Process in batches to avoid memory issues and long locks
+    loop do
+      # Find batch of records to update
+      count = User.unscoped
+                  .where(status: nil)
+                  .limit(10_000)
+                  .update_all(status: "active")
+
+      break if count.zero?
+
+      sleep(0.1)  # Throttle to reduce database load
+    end
+  end
+end
+
+# Using find_each for complex logic
+class BackfillCalculatedField < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  # Define local model to avoid depending on app code
+  class Order < ApplicationRecord
+    self.table_name = "orders"
+  end
+
+  def up
+    Order.unscoped.where(total_cents: nil).find_each(batch_size: 1000) do |order|
+      total = order.subtotal_cents.to_i + order.tax_cents.to_i
+      order.update_columns(total_cents: total)
+    end
+  end
+end
+
+# =============================================================================
+# MIGRATION WITH LOCK TIMEOUT
+# =============================================================================
+
+class MigrationWithTimeout < ActiveRecord::Migration[7.2]
+  def change
+    # Set lock timeout to avoid blocking for too long
+    execute "SET lock_timeout = '5s'"
+
+    begin
+      add_column :users, :verified, :boolean, default: false
+    ensure
+      execute "SET lock_timeout = DEFAULT"
+    end
+  end
+end
+
+# =============================================================================
+# SAFE TABLE COPY PATTERN
+# =============================================================================
+
+# For massive schema changes, copy to new table
+
+class RestructureProductsTable < ActiveRecord::Migration[7.2]
+  def up
+    # Create new table with desired schema
+    create_table :products_v2 do |t|
+      t.string :name, null: false
+      t.decimal :price_cents, precision: 12, scale: 0, null: false
+      # ... new schema
+      t.timestamps
+    end
+
+    # Copy data (in production, do this in background job)
+    execute <<~SQL
+      INSERT INTO products_v2 (id, name, price_cents, created_at, updated_at)
+      SELECT id, name, (price * 100)::bigint, created_at, updated_at
+      FROM products
+    SQL
+
+    # Rename tables
+    rename_table :products, :products_legacy
+    rename_table :products_v2, :products
+
+    # Later: drop legacy table after verification
+  end
+
+  def down
+    rename_table :products, :products_v2
+    rename_table :products_legacy, :products
+    drop_table :products_v2
+  end
+end
+
+# =============================================================================
+# ENUM CHANGES (PostgreSQL)
+# =============================================================================
+
+# Adding enum values requires disable_ddl_transaction
+class AddEnumValue < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def up
+    execute "ALTER TYPE order_status ADD VALUE 'refunded'"
+  end
+
+  def down
+    # Cannot remove enum values easily in PostgreSQL
+    # Would need to recreate enum type
+    raise ActiveRecord::IrreversibleMigration
+  end
+end
+
+# =============================================================================
+# IDEMPOTENT MIGRATIONS
+# =============================================================================
+
+# Make migrations safe to run multiple times (useful for retry scenarios)
+
+class IdempotentMigration < ActiveRecord::Migration[7.2]
+  def change
+    # Check before creating
+    unless table_exists?(:audits)
+      create_table :audits do |t|
+        t.string :action
+        t.timestamps
+      end
+    end
+
+    # Check before adding column
+    unless column_exists?(:users, :audit_count)
+      add_column :users, :audit_count, :integer, default: 0
+    end
+
+    # Check before adding index
+    unless index_exists?(:users, :audit_count)
+      add_index :users, :audit_count
+    end
+  end
+end
+
+# =============================================================================
+# POST-DEPLOYMENT MIGRATIONS
+# =============================================================================
+
+# For non-critical operations that can run after deployment
+# These don't block the deploy and can take longer
+
+# Place in db/post_migrate/ if using GitLab-style setup
+# Or run via separate rake task
+
+class PostDeploymentCleanup < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def up
+    # Remove unused indexes (non-blocking)
+    remove_index :orders, :legacy_column, algorithm: :concurrently, if_exists: true
+
+    # Clean up orphaned data
+    execute "DELETE FROM order_items WHERE order_id NOT IN (SELECT id FROM orders)"
+
+    # Add new index (non-blocking)
+    add_index :orders, :new_column, algorithm: :concurrently, if_not_exists: true
+  end
+end
+
+# =============================================================================
+# USING strong_migrations GEM
+# =============================================================================
+
+# With strong_migrations installed, dangerous operations are blocked
+# Use safety_assured only after careful review
+
+class MigrationWithStrongMigrations < ActiveRecord::Migration[7.2]
+  def change
+    # This would normally be blocked
+    safety_assured do
+      add_column :users, :settings, :jsonb, default: {}
+    end
+  end
+end
+
+# Better: Follow recommended pattern
+class SafeAddColumnWithDefault < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def change
+    # Add column without default first
+    add_column :users, :settings, :jsonb
+
+    # Backfill (for existing records)
+    User.unscoped.in_batches do |batch|
+      batch.update_all(settings: {})
+    end
+
+    # Set default for new records
+    change_column_default :users, :settings, {}
+
+    # Add NOT NULL if needed
+    change_column_null :users, :settings, false
+  end
+end

data/skills/activerecord/examples/migrations/schema_changes.rb

@@ -0,0 +1,277 @@
+# ActiveRecord Migration Examples: Schema Changes
+# Run migrations: rails db:migrate
+# Rollback: rails db:rollback
+
+# =============================================================================
+# CREATING TABLES
+# =============================================================================
+
+# Basic table creation
+class CreateProducts < ActiveRecord::Migration[7.2]
+  def change
+    create_table :products do |t|
+      t.string :name, null: false
+      t.string :sku, null: false
+      t.text :description
+      t.decimal :price, precision: 10, scale: 2, null: false
+      t.integer :quantity, default: 0
+      t.boolean :active, default: true
+      t.timestamps
+    end
+
+    add_index :products, :sku, unique: true
+  end
+end
+
+# Table with foreign key reference
+class CreateOrderItems < ActiveRecord::Migration[7.2]
+  def change
+    create_table :order_items do |t|
+      t.references :order, null: false, foreign_key: true
+      t.references :product, null: false, foreign_key: true
+      t.integer :quantity, null: false, default: 1
+      t.decimal :unit_price, precision: 10, scale: 2, null: false
+      t.timestamps
+    end
+  end
+end
+
+# Join table (no primary key)
+class CreateProductsCategories < ActiveRecord::Migration[7.2]
+  def change
+    create_join_table :products, :categories do |t|
+      t.index [:product_id, :category_id], unique: true
+      t.index :category_id
+    end
+  end
+end
+
+# Table with UUID primary key
+class CreateApiKeys < ActiveRecord::Migration[7.2]
+  def change
+    create_table :api_keys, id: :uuid do |t|
+      t.references :user, null: false, foreign_key: true
+      t.string :name, null: false
+      t.string :key_digest, null: false
+      t.datetime :expires_at
+      t.datetime :last_used_at
+      t.timestamps
+    end
+
+    add_index :api_keys, :key_digest, unique: true
+  end
+end
+
+# Table with composite primary key
+class CreateTenantUsers < ActiveRecord::Migration[7.2]
+  def change
+    create_table :tenant_users, primary_key: [:tenant_id, :user_id] do |t|
+      t.bigint :tenant_id, null: false
+      t.bigint :user_id, null: false
+      t.string :role, null: false, default: "member"
+      t.timestamps
+    end
+  end
+end
+
+# Polymorphic association table
+class CreateComments < ActiveRecord::Migration[7.2]
+  def change
+    create_table :comments do |t|
+      t.references :commentable, polymorphic: true, null: false
+      t.references :author, null: false, foreign_key: { to_table: :users }
+      t.text :body, null: false
+      t.timestamps
+    end
+
+    add_index :comments, [:commentable_type, :commentable_id]
+  end
+end
+
+# =============================================================================
+# ADDING COLUMNS
+# =============================================================================
+
+class AddFieldsToUsers < ActiveRecord::Migration[7.2]
+  def change
+    # Simple columns
+    add_column :users, :phone, :string
+    add_column :users, :verified_at, :datetime
+
+    # Column with default
+    add_column :users, :locale, :string, default: "en", null: false
+
+    # JSON/JSONB column (PostgreSQL)
+    add_column :users, :preferences, :jsonb, default: {}
+    add_column :users, :metadata, :jsonb, default: {}
+
+    # Add index on JSON field (PostgreSQL GIN index)
+    add_index :users, :preferences, using: :gin
+  end
+end
+
+# Adding reference column
+class AddOrganizationToUsers < ActiveRecord::Migration[7.2]
+  def change
+    # Creates user_id column with index and foreign key
+    add_reference :users, :organization, foreign_key: true
+
+    # Without index
+    add_reference :users, :invited_by, foreign_key: { to_table: :users }, index: false
+
+    # Polymorphic reference (no foreign key possible)
+    add_reference :attachments, :attachable, polymorphic: true, index: true
+  end
+end
+
+# =============================================================================
+# MODIFYING COLUMNS
+# =============================================================================
+
+# Renaming columns (reversible)
+class RenameUserFields < ActiveRecord::Migration[7.2]
+  def change
+    rename_column :users, :name, :full_name
+    rename_column :users, :type, :account_type  # Avoid STI conflict
+  end
+end
+
+# Changing defaults (reversible with from/to)
+class ChangeUserDefaults < ActiveRecord::Migration[7.2]
+  def change
+    change_column_default :users, :status, from: nil, to: "pending"
+    change_column_default :users, :role, from: "user", to: "member"
+  end
+end
+
+# Changing null constraint
+class AddNotNullToEmail < ActiveRecord::Migration[7.2]
+  def change
+    # Backfill NULLs first with default value
+    change_column_null :users, :email, false, "unknown@example.com"
+  end
+end
+
+# Changing column type (IRREVERSIBLE - requires up/down)
+class ChangeDescriptionToText < ActiveRecord::Migration[7.2]
+  def up
+    change_column :products, :description, :text
+  end
+
+  def down
+    change_column :products, :description, :string
+  end
+end
+
+# Changing precision/scale
+class IncreasePricePrecision < ActiveRecord::Migration[7.2]
+  def up
+    change_column :products, :price, :decimal, precision: 12, scale: 2
+  end
+
+  def down
+    change_column :products, :price, :decimal, precision: 10, scale: 2
+  end
+end
+
+# =============================================================================
+# REMOVING COLUMNS
+# =============================================================================
+
+# Removing single column (must include type for reversibility)
+class RemoveLegacyField < ActiveRecord::Migration[7.2]
+  def change
+    remove_column :users, :legacy_token, :string
+  end
+end
+
+# Removing multiple columns
+class RemoveDeprecatedFields < ActiveRecord::Migration[7.2]
+  def change
+    remove_columns :users, :old_field1, :old_field2, type: :string
+  end
+end
+
+# Removing reference
+class RemoveOrganizationFromUsers < ActiveRecord::Migration[7.2]
+  def change
+    remove_reference :users, :organization, foreign_key: true
+  end
+end
+
+# =============================================================================
+# RENAMING TABLES
+# =============================================================================
+
+class RenameUsersToAccounts < ActiveRecord::Migration[7.2]
+  def change
+    rename_table :users, :accounts
+  end
+end
+
+# =============================================================================
+# DROPPING TABLES
+# =============================================================================
+
+# Must include full schema for reversibility
+class DropLegacyReports < ActiveRecord::Migration[7.2]
+  def change
+    drop_table :legacy_reports do |t|
+      t.string :name
+      t.text :data
+      t.references :user
+      t.timestamps
+    end
+  end
+end
+
+# Irreversible drop (when you don't need rollback)
+class DropTemporaryTable < ActiveRecord::Migration[7.2]
+  def up
+    drop_table :temp_imports
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+end
+
+# =============================================================================
+# PRACTICAL PATTERNS
+# =============================================================================
+
+# Adding column with index in one migration
+class AddStatusToOrders < ActiveRecord::Migration[7.2]
+  def change
+    add_column :orders, :status, :string, default: "pending", null: false
+    add_index :orders, :status
+  end
+end
+
+# Adding timestamps to existing table
+class AddTimestampsToProducts < ActiveRecord::Migration[7.2]
+  def change
+    # Adds created_at and updated_at with null: false, precision: 6
+    add_timestamps :products, default: -> { "CURRENT_TIMESTAMP" }
+  end
+end
+
+# Converting column with data preservation
+class ConvertPriceToInteger < ActiveRecord::Migration[7.2]
+  def up
+    # Add new column
+    add_column :products, :price_cents, :integer
+
+    # Migrate data (for small tables)
+    execute "UPDATE products SET price_cents = (price * 100)::integer"
+
+    # Remove old column
+    remove_column :products, :price
+  end
+
+  def down
+    add_column :products, :price, :decimal, precision: 10, scale: 2
+    execute "UPDATE products SET price = price_cents / 100.0"
+    remove_column :products, :price_cents
+  end
+end