ActiveRecord Cheat Sheet

# BAD — fires 1 query for posts, then 1 per post for user
posts = Post.all
posts.each { |p| puts p.user.name }  # N+1!

# GOOD
posts = Post.includes(:user).all
posts.each { |p| puts p.user.name }  # 2 queries total

# ALSO GOOD when filtering on association
Post.joins(:user).where(users: { active: true })
# (don't use includes if you're only filtering, not loading)

# Gemfile (development/test only)
gem "bullet"

# config/environments/development.rb
config.after_initialize do
  Bullet.enable        = true
  Bullet.alert         = true
  Bullet.rails_logger  = true
end

# Or: strict_loading to raise in dev/test
# config/application.rb
config.active_record.strict_loading_by_default = true

# Per-query opt-out
Post.strict_loading.includes(:user)    # explicit eager load required
Post.strict_loading(false).all         # opt out

Post.preload(:user)
# SELECT * FROM posts
# SELECT * FROM users WHERE id IN (1, 2, 3, ...)

# Cannot use in WHERE:
Post.preload(:user).where(users: { active: true })
# => ActiveRecord::StatementInvalid — can't filter on preloaded table

Post.includes(:user)
# Uses preload (2 queries) by default

Post.includes(:user).where(users: { active: true })
# Detects reference to users table → switches to LEFT OUTER JOIN
# (same as eager_load)

Post.includes(:user).references(:user).where("users.active = true")
# .references forces JOIN mode when using string WHERE clause

# Nested
Post.includes(comments: :author)
Post.includes(:user, comments: [:author, :likes])

Post.eager_load(:user)
# SELECT posts.*, users.* FROM posts
# LEFT OUTER JOIN users ON users.id = posts.user_id

# Good for filtering AND loading in one query:
Post.eager_load(:user).where(users: { active: true })

# Watch out: has_many + eager_load → row duplication
# A post with 3 comments = 3 rows; AR dedupes via ID but
# LIMIT/OFFSET math breaks:
Post.eager_load(:comments).limit(5)  # may return < 5 posts!

Post.joins(:user).where(users: { active: true })
# INNER JOIN — posts without a user are excluded
# user NOT loaded — accessing post.user triggers a new query!

# LEFT OUTER JOIN manually:
Post.joins("LEFT OUTER JOIN users ON users.id = posts.user_id")

# Joining through:
Post.joins(comments: :author)
# JOIN comments ... JOIN users (authors) ...

# join + select for custom columns
Post.joins(:user).select("posts.*, users.name as author_name")
post.author_name  # available as attribute

has_many :posts                          # foreign_key: :user_id inferred
has_many :published_posts,
         -> { where(published: true) },  # scope lambda
         class_name: "Post"
has_many :posts, foreign_key: :author_id
has_many :posts, primary_key: :uuid      # non-id primary key
has_many :posts, inverse_of: :user       # bidirectional identity
has_many :posts, strict_loading: true
has_many :posts, dependent: :destroy     # cascade destroy (slow)
has_many :posts, dependent: :delete_all  # cascade SQL delete (fast, no callbacks)
has_many :posts, dependent: :nullify     # SET foreign_key = NULL
has_many :posts, dependent: :restrict_with_error # prevent deletion if assoc exists
has_many :posts, dependent: :restrict_with_exception

class User < ApplicationRecord
  has_many :memberships
  has_many :groups, through: :memberships
  has_many :posts, through: :groups   # multi-hop
end

class Membership < ApplicationRecord
  belongs_to :user
  belongs_to :group
end

# source: needed when name doesn't match
has_many :admins, through: :memberships,
         source: :user,
         source_type: "User"  # for polymorphic through

belongs_to :user                        # required by default (Rails 5+)
belongs_to :user, optional: true        # allow nil
belongs_to :author, class_name: "User"
belongs_to :user, counter_cache: true   # maintains user.posts_count
belongs_to :user, counter_cache: :articles_count  # custom column name
belongs_to :post, touch: true           # updates post.updated_at
belongs_to :category, touch: :category_updated_at # custom timestamp col
belongs_to :user, inverse_of: :posts    # in-memory identity

class Comment < ApplicationRecord
  belongs_to :commentable, polymorphic: true
end

class Post < ApplicationRecord
  has_many :comments, as: :commentable
end

class Video < ApplicationRecord
  has_many :comments, as: :commentable
end

# columns: commentable_id (integer), commentable_type (string)
comment.commentable        # returns Post or Video instance
comment.commentable_type   # "Post"

# Gotcha: can't JOIN across polymorphic — no way to JOIN both tables
# Use includes for loading, avoid JOINs on polymorphic associations

has_one :profile                         # uses user_id on profiles table
has_one :profile, dependent: :destroy
has_one :latest_post,
        -> { order(created_at: :desc) }, # scope to pick which one
        class_name: "Post"

# Build vs create:
user.build_profile(bio: "...")   # builds in memory, not saved
user.create_profile(bio: "...")  # saves immediately
user.profile ||= Profile.new     # equivalent to build if nil

# Appending with <<
user.posts << Post.new(title: "x")  # saves immediately if user is persisted

# build vs create on collection
user.posts.build(title: "x")    # in-memory, not saved
user.posts.create(title: "x")   # saves immediately

# Caching — AR caches association results
user.posts.count  # SELECT COUNT(*)
user.posts.count  # SELECT COUNT(*) again (not cached)
user.posts.size   # uses cached length if loaded

# Force reload
user.posts(true)         # deprecated — use reload
user.association(:posts).reload
user.reload.posts        # reloads full record

# inverse_of prevents creating extra objects in memory
# Without it: post.user.object_id != user.object_id (two User instances)

class Post < ApplicationRecord
  scope :published, -> { where(published: true) }
  scope :recent,    -> { order(created_at: :desc) }
  scope :by_author, ->(user) { where(author: user) }
  scope :created_after, ->(date) { where("created_at > ?", date) }

  # Scope with includes
  scope :with_author, -> { includes(:author) }

  # Never use default_scope — use named scopes instead
end

Post.published.recent.by_author(current_user)
Post.published.created_after(1.week.ago)

# Scopes chain with AND by default
Post.published.recent   # WHERE published = true ORDER BY created_at DESC

# Merging scopes from another model (great with joins)
class Post < ApplicationRecord
  scope :by_active_users, -> { joins(:user).merge(User.active) }
end

class User < ApplicationRecord
  scope :active, -> { where(active: true) }
end

Post.by_active_users
# SELECT posts.* FROM posts INNER JOIN users ON ... WHERE users.active = true

# OR scopes (Rails 5+)
Post.published.or(Post.featured)
# WHERE published = true OR featured = true

class Post < ApplicationRecord
  default_scope { where(published: true) }
end

# Hazard 1: applies to NEW records too
Post.new.published  # => true (set by default_scope)

# Hazard 2: unscoped strips association scope too
user.posts.unscoped  # => ALL posts, not just user's posts!

# Hazard 3: ORDER default_scope stacks
class Post < ApplicationRecord
  default_scope { order(:created_at) }
end
Post.order(:title)   # ORDER BY created_at, title (stacked!)
Post.reorder(:title) # ORDER BY title (replaces)

# Hazard 4: affects associations
user.posts           # WHERE user_id = ? AND published = true
                     # hidden default_scope filter!

# unscoped — removes ALL scopes (including association scope!)
Post.unscoped.where(id: 1)

# unscope — removes specific clauses
Post.published.recent.unscope(:order)    # keeps WHERE, removes ORDER
Post.unscope(:where).order(:title)       # removes WHERE, keeps ORDER
Post.unscope(where: :published)          # removes specific WHERE condition

# Within association context, prefer unscope over unscoped
user.posts.unscope(:order)   # safe — keeps the user_id constraint
user.posts.unscoped          # unsafe — loses user_id constraint!

# after_save fires inside the transaction
# after_commit fires AFTER the transaction commits

# Use after_commit for side effects that shouldn't happen if rollback:
after_commit :send_welcome_email, on: :create
after_commit :notify_update, on: :update
after_commit :log_deletion, on: :destroy

# after_save is INSIDE the transaction:
# - If something later rolls back, after_save already fired
# - Enqueuing jobs in after_save = job may run before data committed
#   → Use after_commit for job enqueuing!

# Shorthand:
after_create_commit  :send_welcome_email
after_update_commit  :notify_update
after_destroy_commit :log_deletion
after_save_commit    :sync_to_cache   # any save (create or update)

before_save :normalize_name, if: :name_changed?
before_save :set_slug,       if: -> { title_changed? || slug.blank? }
after_create :send_email,    unless: :system_user?
before_destroy :check_deps,  if: :has_dependents?

# Multiple conditions (all must be true)
before_save :do_thing, if: [:published?, :title_changed?]

# Skip a specific callback for a model (use sparingly in tests)
User.skip_callback(:create, :after, :send_welcome_email) do
  User.create(name: "test")
end

# update_column / update_columns — bypass all callbacks + validations
user.update_column(:name, "New")   # single column, no callbacks
user.update_columns(name: "New", role: "admin")  # multiple

# update_attribute — bypasses validations but RUNS callbacks
user.update_attribute(:name, "New")

# save(validate: false) — skips validation, runs callbacks

# Method bypass matrix:
# update_attribute  → skips validations, runs callbacks, touches updated_at
# update_column     → skips both, skips updated_at
# update_columns    → skips both, skips updated_at
# update_all        → skips both, skips updated_at (class-level)

# Throwing :abort halts the callback chain and returns false
before_create do
  throw(:abort) if name.blank?
end

# Returns false from save / create:
user.save  # => false if callback throws :abort

# false return value from callback no longer halts (Rails 5+)
# Must explicitly throw :abort

# Checking why save failed:
user.save  # => false
user.errors.full_messages  # may be empty if halted without errors
# Add errors before throwing abort for better UX:
before_create do
  errors.add(:base, "Name required")
  throw(:abort) if name.blank?
end

validates :name,  presence: true
validates :email, presence: true,
                  uniqueness: { case_sensitive: false, scope: :account_id },
                  format: { with: URI::MailTo::EMAIL_REGEXP }
validates :age,   numericality: { greater_than: 0, less_than: 150 }
validates :role,  inclusion: { in: %w[admin mod user] }
validates :bio,   length: { maximum: 500 }
validates :slug,  uniqueness: true, if: :published?

# Multiple attrs same validation:
validates :first_name, :last_name, presence: true

validates :password, presence: true, on: :create
validates :old_password, presence: true, on: :update
validates :terms, acceptance: true, on: :registration  # custom context

# Trigger with context:
user.save(context: :registration)
user.valid?(:registration)

# Validate without saving:
user.valid?           # runs all default validations
user.invalid?         # inverse
user.errors           # ActiveModel::Errors
user.errors[:email]   # array of messages for :email
user.errors.full_messages

# Inline with validate (method)
validate :slug_format

def slug_format
  unless slug =~ /\A[a-z0-9-]+\z/
    errors.add(:slug, "only lowercase letters, numbers, and hyphens")
  end
end

# EachValidator class (reusable)
class EmailDomainValidator < ActiveModel::EachValidator
  def validate_each(record, attribute, value)
    unless value.end_with?("@myco.com")
      record.errors.add(attribute, options[:message] || "must be a company email")
    end
  end
end

validates :email, email_domain: true
validates :email, email_domain: { message: "must end in @myco.com" }

user.save(validate: false)      # skips ALL validations, runs callbacks
user.update_attribute(:x, val)  # skips validations, runs callbacks
user.update_column(:x, val)     # skips validations AND callbacks
User.update_all(x: val)         # skips both, class level

# uniqueness validation has a race condition!
# Always back it up with a DB-level unique index:
# add_index :users, :email, unique: true
# The validation is UX sugar; the index is the real guard.

ActiveRecord::Base.transaction do
  user.save!
  account.update!(balance: account.balance - amount)
end

# Any exception rolls back the transaction
# Only ActiveRecord::Rollback is swallowed (not re-raised)
# All other exceptions propagate after rollback

# Force rollback without exception:
ActiveRecord::Base.transaction do
  do_some_work
  raise ActiveRecord::Rollback  # rolls back, no exception propagates
end

# The model the transaction is called on doesn't matter —
# all AR connections in the same thread share the transaction:
User.transaction do
  user.save!
  order.save!  # also in transaction, even though it's an Order
end

# By default, nested transactions JOIN the outer transaction
# (no savepoint)
User.transaction do
  User.transaction do   # joins outer — NOT a savepoint
    user.save!
  end                   # inner commit is a no-op
end                     # outer commit fires here

# requires_new: true creates a savepoint
User.transaction do
  User.transaction(requires_new: true) do
    user.save!
    raise ActiveRecord::Rollback  # only rolls back to savepoint
  end                  # outer continues
  other.save!
end

# Gotcha: ActiveRecord::Rollback raised in inner transaction
# without requires_new: true will propagate as a no-op,
# but outer transaction will STILL commit!

# Pessimistic locking — SELECT ... FOR UPDATE
user = User.lock.find(1)
user = User.find(1)
user.lock!             # issues SELECT ... FOR UPDATE

User.transaction do
  user = User.lock.find(params[:id])
  user.update!(balance: user.balance - 10)
end

# Optimistic locking — add lock_version integer column
# add_column :users, :lock_version, :integer, default: 0
User.find(1).save!  # auto-increments lock_version
# Concurrent saves raise ActiveRecord::StaleObjectError

# Custom lock clauses:
User.lock("LOCK IN SHARE MODE").find(1)  # MySQL
User.lock("FOR UPDATE SKIP LOCKED").where(...) # PG skip locked rows

# after_save: fires inside the transaction
# after_commit: fires AFTER the transaction commits to DB

# Problem pattern:
after_save :enqueue_job  # BAD — job may run before transaction commits

# Correct pattern:
after_commit :enqueue_job, on: :create  # GOOD

# In tests: use_transactional_tests wraps each test in a transaction
# that never commits → after_commit never fires!
# Solutions:
# 1. DatabaseCleaner with :truncation strategy for those tests
# 2. Rails built-in: test.rb transactional callbacks workaround
#    config.active_record.maintain_test_schema = true

# after_rollback — fires if transaction rolled back
after_rollback :cleanup_uploaded_files

# OLD BAD (rewrites entire table — locks it):
add_column :users, :active, :boolean, default: true, null: false

# GOOD on PG 11+: constant defaults are instant (stored in catalog)
add_column :users, :active, :boolean, default: true, null: false
# PG 11+ handles constant defaults without table rewrite

# STILL SLOW on PG < 11 or for non-constant defaults:
# Step 1: add nullable column
add_column :users, :score, :integer

# Step 2: backfill in batches
User.find_in_batches { |g| User.where(id: g).update_all(score: 0) }

# Step 3: add NOT NULL + default after backfill
change_column_null :users, :score, false
change_column_default :users, :score, 0

add_index :users, :email, unique: true
add_index :users, [:account_id, :email], unique: true  # compound unique
add_index :users, :email, name: "idx_users_email_lower",
          using: :btree  # default; also :hash, :gin, :gist (PG)

# Partial index (PG) — much smaller, faster for filtered queries
add_index :users, :email, where: "deleted_at IS NULL"

# Concurrent index creation (PG) — doesn't lock table
add_index :users, :email, algorithm: :concurrently

# expression index
add_index :users, "lower(email)", name: "idx_users_lower_email"

# Remove
remove_index :users, :email
remove_index :users, column: :email
remove_index :users, name: "idx_users_email_lower"

class AddIndexToUsersEmail < ActiveRecord::Migration[7.1]
  disable_ddl_transaction!  # required for :concurrently

  def change
    add_index :users, :email,
              algorithm: :concurrently,
              if_not_exists: true  # idempotent
  end
end

# change: auto-reversible (add_column, add_index, create_table, etc.)
def change
  add_column :users, :bio, :text
end

# up/down: when change isn't reversible
def up
  change_column :users, :score, :decimal, precision: 10, scale: 2
end

def down
  change_column :users, :score, :integer
end

# Reversible block inside change:
def change
  reversible do |dir|
    dir.up   { execute "CREATE EXTENSION IF NOT EXISTS citext" }
    dir.down { execute "DROP EXTENSION IF EXISTS citext" }
  end
  add_column :users, :email, :citext
end

# Without bulk: each change = separate ALTER TABLE (slow)
def change
  change_table :users, bulk: true do |t|  # single ALTER TABLE
    t.add    :bio,     :text
    t.add    :score,   :integer, default: 0
    t.remove :legacy_col
    t.rename :old_name, :new_name
  end
end

# Note: bulk: true is MySQL-specific optimization
# PG handles multiple columns in one ALTER TABLE natively

# Removing a column: AR caches column list at boot
# If you remove a column while app is running, existing processes
# will fail trying to SELECT the removed column.

# Safe sequence (zero-downtime):
# 1. Tell AR to ignore the column (before migration):
class User < ApplicationRecord
  self.ignored_columns = [:old_col]
end

# 2. Deploy app code with ignored_columns
# 3. Run migration to drop the column
# 4. Remove ignored_columns from model

# Renaming: same issue — use ignored_columns + new column + backfill
# Avoid rename_column in zero-downtime deployments

add_reference :posts, :user, foreign_key: true        # adds user_id + FK
add_reference :posts, :user, foreign_key: true,
              index: { algorithm: :concurrently }     # concurrent index

add_foreign_key :posts, :users                        # adds FK constraint
add_foreign_key :posts, :users, on_delete: :cascade   # DB-level cascade

# Check constraints (Rails 6.1+, PG)
add_check_constraint :users, "age > 0", name: "age_positive"

# Timestamps
add_timestamps :posts                                  # adds created_at, updated_at
add_column :posts, :published_at, :datetime, null: true

# Default value
change_column_default :users, :role, from: nil, to: "user"