madbomber/ai_misc/skills/hoblin-activerecord

ActiveRecord

This skill provides comprehensive guidance for working with ActiveRecord in Rails applications. Use for writing migrations, defining associations, optimizing queries, preventing N+1 issues, implementing validations, and following database best practices.

Quick Reference

CRUD Operations

# Create
user = User.create(name: "Alice", email: "[email protected]")
user = User.create!(...)  # Raises on failure

# Read
User.find(1)              # Raises RecordNotFound
User.find_by(email: "x")  # Returns nil if not found
User.where(active: true)  # Returns Relation

# Update
user.update(name: "Bob")
user.update!(...)         # Raises on failure

# Delete (callbacks run)
user.destroy

# Delete (no callbacks)
user.delete

Key Concepts

| Concept | Purpose | |---------|---------| | belongs_to | Child side of association (has foreign key) | | has_many / has_one | Parent side of association | | has_many :through | Many-to-many via join model | | includes / preload | Eager loading (prevent N+1) | | scope | Named query builder | | validates | Model-level data validation | | before_save / after_commit | Lifecycle callbacks |

Eager Loading Decision Tree

Need to access associated data?
├── NO → Use `joins` (filtering only)
└── YES → Need to filter/sort by association?
          ├── NO → Use `preload` (separate queries)
          └── YES → Large dataset with many associations?
                    ├── YES → Use `includes` with `references`
                    └── NO → Use `eager_load` (single JOIN)

Quick Comparison

| Method | Strategy | Best For | |--------|----------|----------| | includes | Auto-choose | Default choice | | preload | Separate queries | Large datasets, no filtering | | eager_load | LEFT OUTER JOIN | Filtering by association | | joins | INNER JOIN | Filtering only, not accessing data |

# N+1 problem
Post.all.each { |p| p.author.name }  # 1 + N queries

# Solution
Post.includes(:author).each { |p| p.author.name }  # 2 queries

Validation vs Constraint Decision

Does the rule ALWAYS apply, regardless of business logic?
├── Yes → Database constraint
│   └── Examples: NOT NULL, foreign keys, unique emails
└── No → Model validation
    └── Examples: Format rules that change, conditional requirements

Need helpful user-facing error messages?
├── Yes → Model validation (possibly WITH constraint)
└── No → Constraint alone is fine

Best Practice: Use both for critical fields:

# Migration (data integrity)
add_index :users, :email, unique: true

# Model (user feedback)
validates :email, presence: true, uniqueness: true

Associations Quick Reference

Basic Types

class Author < ApplicationRecord
  has_many :books, dependent: :destroy
  has_one :profile
end

class Book < ApplicationRecord
  belongs_to :author                    # Required by default
  belongs_to :publisher, optional: true # Allow NULL
end

Through Associations

class Physician < ApplicationRecord
  has_many :appointments
  has_many :patients, through: :appointments
end

class Appointment < ApplicationRecord
  belongs_to :physician
  belongs_to :patient
  # Join model can have attributes
  validates :scheduled_at, presence: true
end

Critical Options

| Option | Purpose | |--------|---------| | inverse_of | Required with custom foreign_key | | dependent: :destroy | Cascade delete with callbacks | | counter_cache: true | Cache association count | | touch: true | Update parent's updated_at |

Migrations Quick Reference

Safe Patterns

# Always reversible
add_column :users, :name, :string
add_index :users, :email, unique: true
add_reference :orders, :user, foreign_key: true

# Concurrent index (no table lock)
disable_ddl_transaction!
add_index :users, :email, algorithm: :concurrently

Must Include Type for Reversibility

remove_column :users, :legacy_field, :string  # Include type!
change_column_default :users, :status, from: nil, to: "active"

Callbacks Quick Reference

Order of Execution

before_validation → after_validation →
before_save → around_save → before_create →
around_create → [INSERT] → after_create →
after_save → [COMMIT] → after_commit

Critical Rule: Use after_commit for External Systems

# WRONG - Race condition!
after_save :enqueue_processing

# CORRECT - Runs after COMMIT
after_commit :enqueue_processing, on: :create

Batch Processing

# BAD - loads all records
User.all.each { |u| process(u) }

# GOOD - processes in batches
User.find_each { |u| process(u) }

# Bulk operations
User.where(old: true).in_batches.update_all(archived: true)

Best Practices

Do

• Add database index for columns used in WHERE, ORDER BY, JOIN
• Use includes to prevent N+1 queries
• Pair uniqueness validations with unique database indexes
• Use find_each for processing large datasets
• Use pluck(:column) instead of all.map(&:column)
• Define inverse_of when using custom foreign_key
• Use after_commit for background jobs and external APIs
• Prefer has_many :through over has_and_belongs_to_many

Don't

• Don't use default_scope (causes subtle issues)
• Don't use delete when you need callbacks
• Don't skip database constraints for critical uniqueness
• Don't use update_column to bypass validations casually
• Don't reference models in migrations (use raw SQL)
• Don't edit already-deployed migrations
• Don't use after_save for external system interactions

Anti-Patterns Quick List

| Anti-Pattern | Solution | |--------------|----------| | N+1 queries | Use includes, preload, or eager_load | | User.all.map(&:email) | Use User.pluck(:email) | | Uniqueness without index | Add unique database index | | validates :active, presence: true | Use inclusion: { in: [true, false] } for booleans | | after_save for jobs | Use after_commit | | Callback hell | Extract to service objects | | default_scope | Use explicit scopes | | has_and_belongs_to_many | Use has_many :through |

Additional Resources

Reference Files

For detailed patterns and complete API references, consult:

• references/basics.md - Conventions, CRUD, dirty tracking, STI, type casting
• references/migrations.md - Schema changes, indexes, constraints, safe patterns
• references/validations.md - Built-in validators, custom validators, contexts
• references/callbacks.md - Lifecycle hooks, transaction callbacks, alternatives
• references/associations.md - All association types, inverse_of, dependent options
• references/querying.md - Finders, eager loading, scopes, batch processing

Example Files

Ready-to-use code patterns in examples/:

• examples/basics/ - CRUD, dirty tracking, type casting, inheritance
• examples/migrations/ - Schema changes, indexes, safe patterns, reversibility
• examples/validations/ - Built-in, conditional, custom, contexts, constraints
• examples/callbacks/ - Lifecycle, transaction callbacks, conditional, alternatives
• examples/associations/ - Basic, through, polymorphic, self-referential, extensions
• examples/querying/ - Finders, eager loading, scopes, batch processing, optimization