anima-core 0.3.0 → 1.0.0

data/skills/activerecord/examples/callbacks/transaction_callbacks.rb

@@ -0,0 +1,340 @@
+# Transaction Callbacks Examples
+# Demonstrates after_commit, after_rollback, and transaction gotchas
+
+# =============================================================================
+# The Critical Difference: after_save vs after_commit
+# =============================================================================
+
+class Order < ApplicationRecord
+  # WRONG - Race condition with background jobs
+  # The job may start before the transaction commits
+  # after_save :enqueue_processing_wrong
+
+  # CORRECT - Job runs after transaction commits
+  after_commit :enqueue_processing, on: :create
+
+  private
+
+  def enqueue_processing_wrong
+    # Sidekiq might query: "Couldn't find Order with 'id'=123"
+    # because the transaction hasn't committed yet
+    OrderProcessingJob.perform_later(id)
+  end
+
+  def enqueue_processing
+    # Transaction committed - record guaranteed to exist
+    OrderProcessingJob.perform_later(id)
+  end
+end
+
+# =============================================================================
+# Transaction Callback Variants (Rails 7.1+)
+# =============================================================================
+
+class Article < ApplicationRecord
+  # Fires on any commit (create, update, or destroy)
+  after_commit :clear_cache
+
+  # Scoped to specific actions
+  after_create_commit :notify_followers
+  after_update_commit :sync_to_search
+  after_destroy_commit :cleanup_attachments
+
+  # Fires on create OR update (not destroy)
+  after_save_commit :reindex_content
+
+  # Equivalent to after_create_commit + after_update_commit
+  after_commit :update_analytics, on: [:create, :update]
+
+  # Rollback callback
+  after_rollback :log_failure
+
+  private
+
+  def clear_cache
+    Rails.cache.delete("article_#{id}")
+    Rails.cache.delete("articles_list")
+  end
+
+  def notify_followers
+    author.followers.find_each do |follower|
+      NotificationJob.perform_later(follower.id, "new_article", id)
+    end
+  end
+
+  def sync_to_search
+    SearchIndexJob.perform_later("update", self.class.name, id)
+  end
+
+  def cleanup_attachments
+    AttachmentCleanupJob.perform_later(attachment_keys)
+  end
+
+  def reindex_content
+    FullTextIndexJob.perform_later(id)
+  end
+
+  def update_analytics
+    AnalyticsJob.perform_later("article_saved", id: id)
+  end
+
+  def log_failure
+    Rails.logger.error("Article #{id || 'new'} save failed, transaction rolled back")
+  end
+end
+
+# =============================================================================
+# Gotcha: Callback Deduplication
+# =============================================================================
+
+class Product < ApplicationRecord
+  # WRONG - Only the LAST one runs due to deduplication
+  after_commit :sync_inventory
+  after_commit :sync_inventory  # This one "wins"
+
+  # Also deduplicated across variants!
+  after_commit :notify_warehouse
+  after_create_commit :notify_warehouse  # These are considered duplicates
+  after_save_commit :notify_warehouse
+
+  # CORRECT - Use :on option
+  after_commit :sync_inventory, on: [:create, :update]
+  after_commit :notify_warehouse, on: :create
+
+  private
+
+  def sync_inventory
+    InventorySyncJob.perform_later(id)
+  end
+
+  def notify_warehouse
+    WarehouseNotificationJob.perform_later(id)
+  end
+end
+
+# =============================================================================
+# Gotcha: Exception Handling in after_commit
+# =============================================================================
+
+class Payment < ApplicationRecord
+  after_commit :notify_external_service
+  after_commit :update_analytics
+  after_commit :send_receipt
+
+  private
+
+  def notify_external_service
+    # If this raises, update_analytics and send_receipt won't run!
+    ExternalPaymentService.notify(self)
+  rescue ExternalPaymentService::Error => e
+    # Handle gracefully - don't let it bubble up
+    Rails.logger.error("External notification failed: #{e.message}")
+    ErrorTracker.capture(e)
+    # Don't re-raise - let other callbacks run
+  end
+
+  def update_analytics
+    Analytics.track("payment_completed", amount:, user_id:)
+  rescue => e
+    Rails.logger.error("Analytics failed: #{e.message}")
+  end
+
+  def send_receipt
+    PaymentMailer.receipt(self).deliver_later
+  end
+end
+
+# =============================================================================
+# Gotcha: previous_changes in after_commit
+# =============================================================================
+
+class User < ApplicationRecord
+  after_commit :log_changes
+
+  private
+
+  def log_changes
+    # WARNING: If the record was saved multiple times in one transaction,
+    # previous_changes only contains the LAST save's changes
+
+    # If transaction did: user.save, then user.save again
+    # previous_changes only shows changes from the second save
+
+    Rails.logger.info("User #{id} changed: #{previous_changes.inspect}")
+  end
+end
+
+# =============================================================================
+# Gotcha: after_commit Also Fires on Destroy
+# =============================================================================
+
+class Subscription < ApplicationRecord
+  # Be careful! This fires on CREATE, UPDATE, AND DESTROY
+  after_commit :sync_to_billing
+
+  # If you only want create/update:
+  after_save_commit :sync_to_billing_safe
+
+  # Or be explicit:
+  after_commit :sync_to_billing_explicit, on: [:create, :update]
+
+  private
+
+  def sync_to_billing
+    # This will run on destroy too - might not be what you want!
+    BillingService.sync(self)
+  end
+
+  def sync_to_billing_safe
+    BillingService.sync(self)
+  end
+
+  def sync_to_billing_explicit
+    BillingService.sync(self)
+  end
+end
+
+# =============================================================================
+# Transaction Callback Ordering (Rails 7.1+)
+# =============================================================================
+
+class Invoice < ApplicationRecord
+  # Rails 7.1+ default: runs in definition order
+  after_commit :step_one   # Runs first
+  after_commit :step_two   # Runs second
+  after_commit :step_three # Runs third
+
+  # Pre-7.1 behavior (if configured): reverse order
+  # config.active_record.run_after_transaction_callbacks_in_order_defined = false
+
+  private
+
+  def step_one
+    Rails.logger.info("Step 1: Generate PDF")
+    PdfGeneratorJob.perform_later(id)
+  end
+
+  def step_two
+    Rails.logger.info("Step 2: Send email")
+    InvoiceMailer.send_invoice(self).deliver_later
+  end
+
+  def step_three
+    Rails.logger.info("Step 3: Update dashboard")
+    DashboardRefreshJob.perform_later(user_id)
+  end
+end
+
+# =============================================================================
+# Real-World Pattern: External System Sync
+# =============================================================================
+
+class Customer < ApplicationRecord
+  after_create_commit :create_in_crm
+  after_update_commit :update_in_crm
+  after_destroy_commit :delete_from_crm
+
+  private
+
+  def create_in_crm
+    CrmSyncJob.perform_later("create", id)
+  end
+
+  def update_in_crm
+    # Only sync if relevant fields changed
+    relevant_changes = previous_changes.keys & %w[name email phone company]
+    return if relevant_changes.empty?
+
+    CrmSyncJob.perform_later("update", id, changes: previous_changes.slice(*relevant_changes))
+  end
+
+  def delete_from_crm
+    # Can't use id lookup since record is gone
+    CrmSyncJob.perform_later("delete", crm_external_id)
+  end
+end
+
+# =============================================================================
+# Real-World Pattern: Search Index Management
+# =============================================================================
+
+class Post < ApplicationRecord
+  after_save_commit :update_search_index
+  after_destroy_commit :remove_from_search_index
+
+  private
+
+  def update_search_index
+    SearchIndexJob.perform_later(
+      action: "index",
+      type: "post",
+      id:,
+      body: {
+        title:,
+        content:,
+        author_name: author.name,
+        published_at:,
+        tags: tags.pluck(:name)
+      }
+    )
+  end
+
+  def remove_from_search_index
+    SearchIndexJob.perform_later(
+      action: "delete",
+      type: "post",
+      id:
+    )
+  end
+end
+
+# =============================================================================
+# Real-World Pattern: Cache Invalidation
+# =============================================================================
+
+class Category < ApplicationRecord
+  has_many :products
+
+  after_commit :invalidate_caches
+
+  private
+
+  def invalidate_caches
+    Rails.cache.delete("category_#{id}")
+    Rails.cache.delete("category_#{id}_products")
+    Rails.cache.delete("categories_tree")
+    Rails.cache.delete("navigation_menu")
+
+    # Invalidate parent category caches if nested
+    parent&.invalidate_caches if parent_id_previously_changed?
+  end
+end
+
+# =============================================================================
+# Nested Transactions and Callbacks
+# =============================================================================
+
+class Transfer < ApplicationRecord
+  def self.create_with_ledger_entries!(from_account:, to_account:, amount:)
+    transaction do
+      transfer = create!(from_account:, to_account:, amount:)
+
+      # Nested transaction - callbacks still wait for outer commit
+      transaction(requires_new: true) do
+        LedgerEntry.create!(account: from_account, amount: -amount, transfer:)
+        LedgerEntry.create!(account: to_account, amount:, transfer:)
+      end
+
+      transfer
+    end
+    # after_commit callbacks run here, after outer transaction commits
+  end
+
+  after_commit :notify_accounts, on: :create
+
+  private
+
+  def notify_accounts
+    TransferNotificationJob.perform_later(id)
+  end
+end

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

@@ -0,0 +1,337 @@
+# ActiveRecord Migration Examples: Indexes and Constraints
+
+# =============================================================================
+# BASIC INDEXES
+# =============================================================================
+
+class AddBasicIndexes < ActiveRecord::Migration[7.2]
+  def change
+    # Single column index
+    add_index :users, :email
+
+    # Unique index
+    add_index :users, :username, unique: true
+
+    # Named index
+    add_index :users, :created_at, name: "idx_users_created"
+  end
+end
+
+# =============================================================================
+# COMPOSITE INDEXES
+# =============================================================================
+
+# Column order matters! Most selective column first
+class AddCompositeIndexes < ActiveRecord::Migration[7.2]
+  def change
+    # Good for: WHERE last_name = 'X' AND first_name = 'Y'
+    # Good for: WHERE last_name = 'X'
+    # NOT useful for: WHERE first_name = 'Y' alone
+    add_index :users, [:last_name, :first_name]
+
+    # Foreign key + status (common lookup pattern)
+    add_index :orders, [:user_id, :status]
+
+    # Polymorphic association (always add this!)
+    add_index :comments, [:commentable_type, :commentable_id]
+
+    # Unique composite
+    add_index :memberships, [:user_id, :organization_id], unique: true
+  end
+end
+
+# =============================================================================
+# PARTIAL INDEXES (PostgreSQL, SQLite)
+# =============================================================================
+
+class AddPartialIndexes < ActiveRecord::Migration[7.2]
+  def change
+    # Index only active records (smaller, faster)
+    add_index :users, :email, where: "active = true", name: "idx_users_email_active"
+
+    # Index only non-null values
+    add_index :sessions, :user_id, where: "user_id IS NOT NULL"
+
+    # Index only pending orders
+    add_index :orders, :created_at, where: "status = 'pending'"
+
+    # Unique email only for non-deleted users (soft delete pattern)
+    add_index :users, :email, unique: true, where: "deleted_at IS NULL"
+
+    # Index only recent records
+    add_index :events, :created_at, where: "created_at > '2024-01-01'"
+  end
+end
+
+# =============================================================================
+# EXPRESSION INDEXES (PostgreSQL)
+# =============================================================================
+
+class AddExpressionIndexes < ActiveRecord::Migration[7.2]
+  def change
+    # Case-insensitive email lookup
+    add_index :users, "lower(email)", unique: true, name: "idx_users_email_lower"
+
+    # Date extraction
+    add_index :events, "date(created_at)", name: "idx_events_created_date"
+
+    # JSON field indexing
+    add_index :users, "(preferences->>'theme')", name: "idx_users_theme"
+  end
+end
+
+# =============================================================================
+# COVERING INDEXES (PostgreSQL)
+# =============================================================================
+
+class AddCoveringIndexes < ActiveRecord::Migration[7.2]
+  def change
+    # Include additional columns to avoid table lookups
+    # Useful when you always SELECT these columns with the WHERE clause
+    add_index :orders, :user_id, include: [:status, :total]
+
+    # SELECT status, total FROM orders WHERE user_id = ?
+    # Can be answered entirely from index!
+  end
+end
+
+# =============================================================================
+# CONCURRENT INDEXES (PostgreSQL)
+# =============================================================================
+
+class AddConcurrentIndex < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!  # REQUIRED for concurrent operations
+
+  def change
+    # Won't lock the table during creation
+    add_index :users, :email, algorithm: :concurrently
+
+    # Remove index concurrently
+    remove_index :users, :old_column, algorithm: :concurrently
+  end
+end
+
+# Adding concurrent index with safety check
+class AddEmailIndexSafely < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def change
+    # Check if index exists before creating
+    unless index_exists?(:users, :email, name: "index_users_on_email")
+      add_index :users, :email, algorithm: :concurrently
+    end
+  end
+end
+
+# =============================================================================
+# SPECIAL INDEX TYPES
+# =============================================================================
+
+class AddSpecialIndexes < ActiveRecord::Migration[7.2]
+  def change
+    # GIN index for JSONB (PostgreSQL)
+    add_index :products, :metadata, using: :gin
+
+    # GiST index for geometric/range types (PostgreSQL)
+    add_index :locations, :coordinates, using: :gist
+
+    # Full-text search index (PostgreSQL)
+    add_index :articles, "to_tsvector('english', title || ' ' || body)",
+              using: :gin, name: "idx_articles_fulltext"
+
+    # Trigram index for LIKE queries (PostgreSQL, requires pg_trgm)
+    add_index :products, :name, using: :gin, opclass: :gin_trgm_ops
+
+    # FULLTEXT index (MySQL)
+    # add_index :articles, [:title, :body], type: :fulltext
+  end
+end
+
+# =============================================================================
+# INDEX WITH ORDERING
+# =============================================================================
+
+class AddOrderedIndexes < ActiveRecord::Migration[7.2]
+  def change
+    # Descending order (useful for ORDER BY col DESC queries)
+    add_index :events, :created_at, order: :desc
+
+    # Mixed ordering
+    add_index :leaderboards, [:game_id, :score], order: { game_id: :asc, score: :desc }
+
+    # NULLS positioning (PostgreSQL)
+    add_index :tasks, :due_date, order: { due_date: "ASC NULLS LAST" }
+  end
+end
+
+# =============================================================================
+# FOREIGN KEY CONSTRAINTS
+# =============================================================================
+
+class AddForeignKeys < ActiveRecord::Migration[7.2]
+  def change
+    # Basic foreign key
+    add_foreign_key :orders, :users
+
+    # With custom column name
+    add_foreign_key :orders, :users, column: :customer_id
+
+    # With ON DELETE behavior
+    add_foreign_key :comments, :posts, on_delete: :cascade
+
+    # With ON UPDATE behavior
+    add_foreign_key :order_items, :products, on_update: :cascade
+
+    # Referencing non-id primary key
+    add_foreign_key :profiles, :users, primary_key: :uuid, column: :user_uuid
+
+    # Self-referential
+    add_foreign_key :employees, :employees, column: :manager_id
+  end
+end
+
+# Foreign key with custom name
+class AddNamedForeignKey < ActiveRecord::Migration[7.2]
+  def change
+    add_foreign_key :orders, :users,
+                    column: :placed_by_id,
+                    name: "fk_orders_placed_by_user"
+  end
+end
+
+# =============================================================================
+# CHECK CONSTRAINTS
+# =============================================================================
+
+class AddCheckConstraints < ActiveRecord::Migration[7.2]
+  def change
+    # Positive price
+    add_check_constraint :products, "price > 0", name: "products_price_positive"
+
+    # Valid quantity
+    add_check_constraint :order_items, "quantity >= 1", name: "order_items_quantity_min"
+
+    # Status validation
+    add_check_constraint :orders, "status IN ('pending', 'processing', 'shipped', 'delivered')",
+                         name: "orders_valid_status"
+
+    # Date range
+    add_check_constraint :events, "end_date >= start_date", name: "events_valid_dates"
+
+    # Email format (basic)
+    add_check_constraint :users, "email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$'",
+                         name: "users_valid_email"
+
+    # Percentage range
+    add_check_constraint :discounts, "percentage BETWEEN 0 AND 100",
+                         name: "discounts_valid_percentage"
+  end
+end
+
+# PostgreSQL: Add constraint without validation (for large tables)
+class AddConstraintSafely < ActiveRecord::Migration[7.2]
+  def change
+    # Step 1: Add without validation
+    add_check_constraint :products, "price > 0",
+                         name: "products_price_positive",
+                         validate: false
+  end
+end
+
+class ValidateConstraint < ActiveRecord::Migration[7.2]
+  def change
+    # Step 2: Validate in separate migration/deployment
+    validate_check_constraint :products, name: "products_price_positive"
+  end
+end
+
+# =============================================================================
+# UNIQUE CONSTRAINTS
+# =============================================================================
+
+class AddUniqueConstraints < ActiveRecord::Migration[7.2]
+  def change
+    # Simple unique
+    add_index :users, :email, unique: true
+
+    # Composite unique
+    add_index :subscriptions, [:user_id, :plan_id], unique: true
+
+    # Unique with condition (soft delete)
+    add_index :users, :email, unique: true, where: "deleted_at IS NULL"
+
+    # Case-insensitive unique (PostgreSQL)
+    add_index :users, "lower(email)", unique: true, name: "idx_users_email_unique_lower"
+  end
+end
+
+# =============================================================================
+# REMOVING INDEXES AND CONSTRAINTS
+# =============================================================================
+
+class RemoveIndexesAndConstraints < ActiveRecord::Migration[7.2]
+  def change
+    # Remove index by column (must specify column for reversibility)
+    remove_index :users, :email
+
+    # Remove index by name
+    remove_index :users, name: "idx_users_email_lower"
+
+    # Remove composite index
+    remove_index :orders, [:user_id, :status]
+
+    # Remove foreign key
+    remove_foreign_key :orders, :users
+
+    # Remove foreign key by column
+    remove_foreign_key :orders, column: :customer_id, to_table: :users
+
+    # Remove check constraint
+    remove_check_constraint :products, name: "products_price_positive"
+  end
+end
+
+# =============================================================================
+# PRACTICAL PATTERNS
+# =============================================================================
+
+# Complete reference setup with all constraints
+class CreateOrdersWithConstraints < ActiveRecord::Migration[7.2]
+  def change
+    create_table :orders do |t|
+      t.references :user, null: false
+      t.references :shipping_address, null: false
+      t.string :status, null: false, default: "pending"
+      t.decimal :subtotal, precision: 10, scale: 2, null: false
+      t.decimal :tax, precision: 10, scale: 2, null: false
+      t.decimal :total, precision: 10, scale: 2, null: false
+      t.timestamps
+    end
+
+    # Foreign keys
+    add_foreign_key :orders, :users, on_delete: :restrict
+    add_foreign_key :orders, :addresses, column: :shipping_address_id
+
+    # Check constraints
+    add_check_constraint :orders, "subtotal >= 0", name: "orders_subtotal_non_negative"
+    add_check_constraint :orders, "tax >= 0", name: "orders_tax_non_negative"
+    add_check_constraint :orders, "total = subtotal + tax", name: "orders_total_calculation"
+    add_check_constraint :orders, "status IN ('pending', 'paid', 'shipped', 'delivered', 'cancelled')",
+                         name: "orders_valid_status"
+
+    # Indexes for common queries
+    add_index :orders, [:user_id, :status]
+    add_index :orders, [:status, :created_at]
+  end
+end
+
+# Index strategy for polymorphic association
+class SetupPolymorphicIndexes < ActiveRecord::Migration[7.2]
+  def change
+    # Always create composite index for polymorphic associations
+    add_index :taggings, [:taggable_type, :taggable_id]
+
+    # If you query by tag_id within a type
+    add_index :taggings, [:taggable_type, :tag_id]
+  end
+end