activerecord

name	activerecord
description	This skill should be used when the user asks to "write a migration", "add a column", "add column to table", "create an index", "add a foreign key", "set up associations", "fix N+1 queries", "optimize queries", "add validations", "create callbacks", "use eager loading", or mentions ActiveRecord, belongs_to, has_many, has_one, :through associations, polymorphic associations, inverse_of, touch: true, counter_cache, dependent: destroy, where clauses, scopes, includes, preload, eager_load, joins, find_each, batch processing, counter caches, foreign key constraints, or database constraints. Should also be used when editing *_model.rb files, working in app/models/ directory, db/migrate/, discussing query performance, N+1 prevention, validation vs constraint decisions, or reviewing database schema design.
version	1.0.2

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: "[e-mail]")
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