Ruby & Rails Pro Playbook

Model      app/models/product.rb          class Product      (singular)
Table      products                                          (plural, snake_case)
Controller app/controllers/products_controller.rb            (plural)
Views      app/views/products/index.html.erb                 (action name)
Route      GET /products  →  ProductsController#index  →  renders index.html.erb

Rails.application.routes.draw do
  root "products#index"

  resources :products          # all 7 RESTful routes in one line

  resources :orders, only: [:index, :show, :create] do
    member     { post :cancel }      # POST /orders/:id/cancel
    collection { get  :export }      # GET  /orders/export
  end

  namespace :admin do
    resources :users             # /admin/users → Admin::UsersController
  end
end

class ProductsController < ApplicationController
  before_action :set_product, only: [:show, :edit, :update, :destroy]

  def create
    @product = Product.new(product_params)      # only permitted fields
    if @product.save
      redirect_to @product, notice: "Created!"
    else
      render :new, status: :unprocessable_entity  # re-show form + errors
    end
  end

  private

  def set_product
    @product = Product.find(params[:id])   # raises 404 if missing — good
  end

  def product_params
    params.expect(product: [:name, :price, :category_id])  # Rails 8
    # Rails ≤7: params.require(:product).permit(:name, :price, :category_id)
  end
end

# $ bin/rails g migration AddStatusToOrders status:string:index

class AddStatusToOrders < ActiveRecord::Migration[8.0]
  def change
    add_column :orders, :status, :string, default: "pending", null: false
    add_index  :orders, :status
  end
end

# richer example — new table
create_table :reviews do |t|
  t.references :product, null: false, foreign_key: true   # FK + index
  t.integer :rating, null: false
  t.text :body
  t.timestamps                       # created_at / updated_at
end

p = Product.create!(name: "Mug", price: 299)
# INSERT INTO "products" ("name","price",...) VALUES ($1,$2,...) RETURNING "id"

Product.find(42)          # SELECT ... WHERE id = 42 LIMIT 1  (raises if missing)
Product.find_by(name: "Mug")   # WHERE name = 'Mug' LIMIT 1   (nil if missing)
Product.find_or_create_by!(sku: "MUG-01") { |x| x.price = 299 }

p.update!(price: 349)     # UPDATE "products" SET "price" = 349 WHERE id = 1
p.price = 399; p.changed? # dirty tracking
p.save!

p.destroy                 # DELETE + runs callbacks/associations
p.persisted?

$ rails g model Product name:string price:decimal category:references
      # → model + migration (+ tests). The workhorse.

$ rails g migration AddStatusToOrders status:string:index
      # → just a migration — most common of all

$ rails g controller Dashboards show
      # → controller + view + route helpers

$ rails g scaffold Post title:string body:text
      # → EVERYTHING (model/controller/7 views/routes/tests)

$ rails destroy model Product     # generated wrong? undo it all
$ rails g model --help            # every generator documents itself

Rails.env                        # "development" | "test" | "production"
Rails.env.production?

# config/environments/production.rb — per-stage rules:
config.consider_all_requests_local = false   # no stack traces to users
config.force_ssl = true

# encrypted secrets — committable, master.key is NOT:
# $ bin/rails credentials:edit
# aws:
#   access_key_id: AKIA...
# stripe_secret: sk_live_...

Rails.application.credentials.stripe_secret
Rails.application.credentials.dig(:aws, :access_key_id)

ENV.fetch("DATABASE_URL")        # 12-factor alternative — also standard
ENV.fetch("QUEUE", "default")    # fetch with default (topic 10 habits!)

module Archivable
  extend ActiveSupport::Concern

  included do                      # runs IN the including class's context
    scope :active,   -> { where(archived_at: nil) }
    scope :archived, -> { where.not(archived_at: nil) }
  end

  class_methods do
    def archive_all! = update_all(archived_at: Time.current)
  end

  def archive!  = update!(archived_at: Time.current)
  def archived? = archived_at.present?
end

class Post < ApplicationRecord
  include Archivable
end

Post.active.count
Post.first.archive!

class PlaceOrder
  Result = Data.define(:success?, :order, :error)     # topic 22!

  def initialize(cart:, user:, payment_method:)
    @cart, @user, @payment_method = cart, user, payment_method
  end

  def call
    ensure_stock!
    order = nil
    ActiveRecord::Base.transaction do                 # topic 71
      order  = @user.orders.create!(items: @cart.items, total: @cart.total)
      charge = PaymentGateway.charge!(@payment_method, @cart.total)
      order.update!(charge_id: charge.id)
    end
    OrderMailer.confirmation(order).deliver_later     # after commit
    Result.new(success?: true, order:, error: nil)
  rescue StockError, PaymentGateway::Declined => e
    Result.new(success?: false, order: nil, error: e.message)
  end
end

# controller shrinks to orchestration:
result = PlaceOrder.new(cart:, user: current_user, payment_method:).call
result.success?

"".blank?         # nil, "", "  ", [], {} → true
"  hi  ".present? # opposite of blank?
params[:q].presence || "all"   # THE default idiom (topic 3)

"  too   many spaces ".squish
"user_profile".camelize
"UserProfile".underscore.pluralize
"₹1,499".delete("^0-9").to_i

5.days.from_now
1.year.ago
Time.current.beginning_of_week

h = { name: "Asha", role: :admin, tmp: 1 }
h.slice(:name, :role)          # take only these keys
h.except(:tmp)                 # everything but
[1,2,3,4,5].in_groups_of(2, nil)
%w[a b].to_sentence

# config/application.rb
config.time_zone = "Asia/Kolkata"     # display zone; DB stays UTC

Time.current                # ✅ zone-aware (ActiveSupport::TimeWithZone)
Time.now                    # ❌ server's OS zone — avoid in app code
Date.current                # ✅ today in YOUR zone
Date.today                  # ❌ today on the SERVER

Time.current.zone
Time.zone.parse("2026-07-11 09:00")   # parse as IST, stored as UTC

# per-user zones — the pro move:
Time.use_zone(user.time_zone) do
  Date.current              # "today" for THIS user
end

# range for "today's orders" — zone-correct:
Order.where(created_at: Time.current.all_day)

orders = Order.where(status: "paid")     # no SQL yet!
orders = orders.where("total > ?", 500)  # still no SQL
orders = orders.order(created_at: :desc).limit(10)

orders.each { |o| puts o.id }            # NOW it fires, once:
# SELECT "orders".* FROM "orders"
# WHERE "orders"."status" = 'paid' AND (total > 500)
# ORDER BY "orders"."created_at" DESC LIMIT 10

# aggregates — computed by Postgres, not Ruby:
Order.group(:status).sum(:total)
# SELECT SUM("total"), "status" FROM "orders" GROUP BY "status"

Order.where(status: "paid").pluck(:id)   # just the column, no objects
Order.where.not(status: "cancelled").exists?

class Customer < ApplicationRecord
  has_many :orders, dependent: :destroy   # decide the orphan policy!
end

class Order < ApplicationRecord
  belongs_to :customer                    # FK column: customer_id
end

c = Customer.create!(name: "Acme")
c.orders.create!(total: 500)              # FK set automatically
c.orders.create!(total: 1200)

c.orders.count                    # SELECT COUNT(*) ... WHERE customer_id = 1
c.orders.where("total > ?", 800)  # associations are relations — chain away!
Order.first.customer.name

c.destroy                         # children destroyed too (dependent: :destroy)

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

class Appointment < ApplicationRecord   # the join model — with data!
  belongs_to :doctor
  belongs_to :patient
  # columns: doctor_id, patient_id, scheduled_at, room
end

class Patient < ApplicationRecord
  has_many :appointments
  has_many :doctors, through: :appointments
end

dr = Doctor.create!(name: "Dr. Rao")
pt = Patient.create!(name: "Asha")
Appointment.create!(doctor: dr, patient: pt, scheduled_at: 2.days.from_now)

dr.patients.pluck(:name)
# SELECT "patients"."name" FROM "patients"
#   INNER JOIN "appointments" ON "patients"."id" = "appointments"."patient_id"
#   WHERE "appointments"."doctor_id" = 1
pt.doctors.count

# ❌ THE BUG — looks innocent, fires 1 + 50 queries
Order.limit(50).each do |o|
  puts "#{o.id}: #{o.customer.name}"     # each .customer = one SELECT
end

# ✅ THE FIX — 2 queries total
Order.includes(:customer).limit(50).each do |o|
  puts "#{o.id}: #{o.customer.name}"     # already in memory
end

# nested associations? same idea:
Order.includes(:items, customer: :address)

# strict mode — make Rails RAISE on lazy loading (find N+1s in dev/test):
# config.active_record.strict_loading_by_default = true

class Product < ApplicationRecord
  validates :name,  presence: true, length: { maximum: 80 }
  validates :sku,   presence: true, uniqueness: true
  validates :price, numericality: { greater_than: 0 }
  validates :state, inclusion: { in: %w[draft active retired] }

  validate :discount_below_price          # custom rule

  private

  def discount_below_price
    return if discount.blank? || discount < price
    errors.add(:discount, "must be below price")
  end
end

p = Product.new(name: "", price: -5)
p.valid?
p.errors.full_messages
p.save          # returns false — nothing hit the DB

class User < ApplicationRecord
  before_validation :normalize_email
  before_create     :generate_referral_code
  after_commit      :send_welcome_email, on: :create   # AFTER the COMMIT

  private

  def normalize_email
    self.email = email.to_s.strip.downcase    # self. required! (topic 18)
  end

  def generate_referral_code
    self.referral_code = SecureRandom.alphanumeric(8).upcase
  end

  def send_welcome_email
    WelcomeMailer.hello(self).deliver_later   # enqueue, don't inline
  end
end

u = User.create!(email: "  ASHA@Corp.COM ")
[u.email, u.referral_code]

class Subscription < ApplicationRecord
  scope :active,   -> { where(status: "active") }
  scope :expiring, ->(days = 7) { where(expires_at: ..days.days.from_now) }
  scope :premium,  -> { where(plan: %w[pro enterprise]) }
  scope :recent,   -> { order(created_at: :desc) }
end

Subscription.active.premium.expiring(3).recent
# SELECT "subscriptions".* FROM "subscriptions"
# WHERE "status" = 'active'
#   AND "plan" IN ('pro','enterprise')
#   AND "expires_at" <= '2026-07-14 ...'
# ORDER BY "created_at" DESC

# scopes work through associations too:
customer.subscriptions.active.expiring

class WalletTransfer
  def self.call(from:, to:, amount:)
    ActiveRecord::Base.transaction do
      from.lock!                       # SELECT ... FOR UPDATE — row locked
      to.lock!
      raise InsufficientFunds if from.balance < amount

      from.update!(balance: from.balance - amount)   # bang! versions —
      to.update!(balance: to.balance + amount)       # exceptions roll back
    end
  end
end

# optimistic alternative: add integer column lock_version and
# ActiveRecord raises StaleObjectError when two edits collide.

# ❌ loads 2M ActiveRecord objects into RAM
User.all.each { |u| Digest.new(u).deliver_later }

# ✅ batches of 1000, constant memory
User.where(digest: true).find_each(batch_size: 1000) do |u|
  Digest.new(u).deliver_later
end

# bulk write — ONE INSERT statement, no callbacks/validations:
Product.insert_all([
  { sku: "MUG-01", name: "Mug",    price: 299 },
  { sku: "PEN-99", name: "Pen",    price: 49  },
])
# upsert_all → INSERT ... ON CONFLICT DO UPDATE (yes, that one!)

# bulk update — ONE statement, straight SQL:
Order.where(status: "pending").where(created_at: ...30.days.ago)
     .update_all(status: "expired")

class Order < ApplicationRecord
  enum :status, { draft: 0, paid: 1, shipped: 2, cancelled: 3 },
       default: :draft, validate: true
end

o = Order.create!
o.status          # reads as a string name
o.paid!           # transition + save (UPDATE ... SET status = 1)
o.paid?
o.shipped?

Order.paid.count            # free scope per value!
Order.not_cancelled.count   # negative scopes too
Order.statuses              # the legend itself

# in forms:
# f.select :status, Order.statuses.keys.map { |s| [s.humanize, s] }

# migration:
create_table :comments do |t|
  t.references :commentable, polymorphic: true, null: false
  # → commentable_type (string) + commentable_id (bigint) + composite index
  t.text :body
  t.timestamps
end

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

class Post < ApplicationRecord
  has_many :comments, as: :commentable, dependent: :destroy
end
class Photo < ApplicationRecord
  has_many :comments, as: :commentable, dependent: :destroy
end

post.comments.create!(body: "Great write-up!")
photo.comments.create!(body: "📸")
Comment.last.commentable          # returns a Photo — Rails reads the type column

class Vehicle < ApplicationRecord; end     # table: vehicles, column: type
class Car   < Vehicle
  def toll = base_toll
end
class Truck < Vehicle
  def toll = base_toll * axles              # axles column: NULL for cars...
end

Car.create!(name: "Swift")     # INSERT ... type = 'Car'
Vehicle.all.map(&:toll)        # each row instantiates its OWN class → polymorphism!
Truck.count                    # WHERE type = 'Truck' — automatic

# delegated_type — the modern alternative when subtypes diverge:
class Entry < ApplicationRecord
  delegated_type :entryable, types: %w[Message Comment]
end
# entries: shared cols + entryable_type/id; messages & comments: own tables
entry.entryable      # the specific record
entry.message?

# migration:
add_column :posts, :comments_count, :integer, default: 0, null: false

class Comment < ApplicationRecord
  belongs_to :post, counter_cache: true, touch: true
  #                 ^ maintains posts.comments_count
  #                                      ^ bumps posts.updated_at on change
end

post.comments.create!(body: "hi")   # UPDATE posts SET comments_count = +1 ...
post.comments_count                 # read the dial — no COUNT query
post.comments.size                  # smart: uses the cache if present!

# backfill existing data once:
Post.find_each { |p| Post.reset_counters(p.id, :comments) }

Customer.joins(:orders)                        # INNER JOIN
        .where(orders: { status: "paid" })
        .distinct

Customer.left_joins(:orders)                   # LEFT OUTER JOIN
        .where(orders: { id: nil })            # customers with NO orders!

# merge — reuse Order.big's logic inside a Customer query:
class Order < ApplicationRecord
  scope :big, -> { where("total > ?", 1000) }
end
Customer.joins(:orders).merge(Order.big)

Customer.where(vip: true).or(Customer.where("orders_count > ?", 10))

# subquery — no ids shipped to Ruby and back:
Customer.where(id: Order.paid.select(:customer_id))
# WHERE "customers"."id" IN (SELECT "customer_id" FROM "orders" WHERE ...)

Customer.joins(:orders).group(:id).having("SUM(orders.total) > ?", 5000)

# models back — when rows map to a model:
top = Order.find_by_sql([<<~SQL, { min: 1000 }])
  SELECT o.*, RANK() OVER (PARTITION BY customer_id ORDER BY total DESC) rnk
  FROM orders o
  WHERE total > :min
SQL
top.first.rnk               # extra columns become readers!

# plain rows back — reports, no model overhead:
rows = ActiveRecord::Base.connection.select_all(
  "SELECT status, SUM(total) t FROM orders GROUP BY status"
).to_a                       # array of hashes

# fragments inside relations — sanitized:
Order.where("created_at > ?", 30.days.ago)                 # bind param
Order.order(Arel.sql("RANDOM()"))                          # explicit trust
scope = Order.sanitize_sql_like(params[:q])                # escape % _ for LIKE
Order.where("sku LIKE ?", "#{scope}%")

# migration:
add_column :products, :attrs, :jsonb, null: false, default: {}
add_index  :products, :attrs, using: :gin        # containment queries!

class Product < ApplicationRecord
  store_accessor :attrs, :color, :ram_gb, :tags  # virtual attributes

  validates :ram_gb, numericality: true, allow_nil: true
end

p = Product.create!(name: "ThinkPad", color: "black", ram_gb: 32)
p.color                       # reads attrs["color"]
p.attrs

# querying — your @> containment operator, GIN-indexed:
Product.where("attrs @> ?", { color: "black" }.to_json)
Product.where("(attrs->>'ram_gb')::int >= ?", 16)

# Gemfile: gem "pagy"
class OrdersController < ApplicationController
  include Pagy::Backend

  def index
    @pagy, @orders = pagy(Order.recent.includes(:customer), limit: 25)
  end                              # ^ still a relation — scopes compose!
end

# view: <%== pagy_nav(@pagy) %>
# SQL: SELECT ... ORDER BY created_at DESC LIMIT 25 OFFSET 50

# keyset for infinite scroll / deep pages (playbook #10):
def feed
  after = params[:after]           # last seen id
  scope = Order.order(id: :desc).limit(25)
  scope = scope.where("id < ?", after) if after
  render json: { items: scope, next_after: scope.last&.id }
end

add_column :users, :discarded_at, :datetime
add_index  :users, :discarded_at
# your Postgres playbook move — partial index keeps live lookups tiny:
# CREATE UNIQUE INDEX ... ON users (email) WHERE discarded_at IS NULL

class User < ApplicationRecord
  include Discard::Model         # gem "discard"
end

user.discard                     # sets discarded_at — no row deleted
user.discarded?
User.kept.count                  # live users (explicit scope!)
User.discarded.count             # the basement
user.undiscard                   # undo — the whole point

# associations still work for audit trails:
user.orders.count                # history intact, FKs intact

<h1>Products (<%= @products.size %>)</h1>

<%# render the _product.html.erb partial once per record — one line: %>
<%= render @products %>

<%= link_to "New product", new_product_path, class: "btn" %>

<div class="card" id="<%= dom_id(product) %>">
  <h2><%= product.name %></h2>          <%# auto HTML-escaped! %>
  <p><%= number_to_currency(product.price, unit: "₹") %></p>
  <% if product.sale? %>                <%# <% %> = logic, no output %>
    <span class="tag">SALE</span>
  <% end %>
</div>

<%= form_with model: @product do |f| %>
  <% if @product.errors.any? %>
    <ul class="errors">
      <% @product.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
    </ul>
  <% end %>

  <%= f.label :name %>
  <%= f.text_field :name %>

  <%= f.number_field :price, step: 0.01 %>
  <%= f.collection_select :category_id, Category.order(:name), :id, :name %>

  <%= f.submit %>   <%# button text adapts: "Create Product" / "Update Product" %>
<% end %>

class SessionsController < ApplicationController
  def create                      # POST /login
    user = User.authenticate_by(email: params[:email], password: params[:password])
    if user
      session[:user_id] = user.id            # signed+encrypted cookie
      redirect_to root_path, notice: "Welcome back!"   # notice = flash
    else
      flash.now[:alert] = "Invalid credentials"        # .now = THIS render
      render :new, status: :unprocessable_entity
    end
  end

  def destroy                     # logout
    reset_session                 # nuke it all — new session id too
    redirect_to root_path, notice: "Logged out"
  end
end

# in ApplicationController — the pattern every app has:
def current_user
  @current_user ||= User.find_by(id: session[:user_id])   # ||= memoize!
end
helper_method :current_user

class Invoice < ApplicationRecord
  has_many :items, dependent: :destroy
  accepts_nested_attributes_for :items,
    allow_destroy: true, reject_if: :all_blank
end

# the view — fields_for renders per-child inputs:
# <%= form_with model: @invoice do |f| %>
#   <%= f.text_field :number %>
#   <%= f.fields_for :items do |item| %>
#     <%= item.text_field :description %>
#     <%= item.number_field :amount %>
#     <%= item.check_box :_destroy %>    <!-- tick to delete -->
#   <% end %>
# <% end %>

def invoice_params
  params.expect(invoice: [ :number,
    items_attributes: [[ :id, :description, :amount, :_destroy ]] ])
end

Invoice.create!(invoice_params)   # parent + children, one transaction

<%# Turbo Drive: already on — every link/form is intercepted,
    body swapped via fetch. You wrote nothing. %>

<%# Turbo Frame: scope navigation to a fragment %>
<%= turbo_frame_tag dom_id(@product) do %>
  <h2><%= @product.name %></h2>
  <%= link_to "Edit", edit_product_path(@product) %>
<% end %>

<%# edit.html.erb — response must contain a MATCHING frame: %>
<%= turbo_frame_tag dom_id(@product) do %>
  <%= render "form", product: @product %>
<% end %>

<%# clicking Edit swaps ONLY the card for the form. Cancel = link back
    to show — swaps the form back out. Inline editing, no JS. %>

<%# lazy frame — loads when scrolled into view: %>
<%= turbo_frame_tag "stats", src: dashboard_stats_path, loading: :lazy %>

# controller — respond with surgical instructions:
def create
  @comment = @post.comments.create!(comment_params)
  respond_to do |format|
    format.turbo_stream    # renders create.turbo_stream.erb
    format.html { redirect_to @post }
  end
end

<%= turbo_stream.append "comments", @comment %>
<%= turbo_stream.update "comments_count", @post.comments.size %>
<%= turbo_stream.replace "new_comment", partial: "comments/form",
                          locals: { comment: Comment.new } %>

class Comment < ApplicationRecord
  belongs_to :post
  broadcasts_to :post        # after_commit → WebSocket push
end
# view:  <%= turbo_stream_from @post %>
#        <div id="comments">...</div>
# every open browser appends the new comment. Chat-grade UX, ~3 lines.

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["source", "button"]

  copy() {
    navigator.clipboard.writeText(this.sourceTarget.value)
    this.buttonTarget.textContent = "Copied!"
    setTimeout(() => this.buttonTarget.textContent = "Copy", 1500)
  }
}

<div data-controller="clipboard">
  <input data-clipboard-target="source" value="<%= @api_key %>" readonly>
  <button data-clipboard-target="button"
          data-action="click->clipboard#copy">Copy</button>
</div>

# app/controllers/api/v1/products_controller.rb
module Api::V1
  class ProductsController < ApplicationController
    skip_forgery_protection            # token auth instead (topic 91)

    def index
      products = Product.kept.includes(:category).limit(100)
      render json: products.as_json(
        only:    [:id, :name, :price],          # allowlist the shape!
        methods: [:display_price],
        include: { category: { only: [:id, :name] } }
      )
    end

    def create
      product = Product.new(product_params)
      if product.save
        render json: product, status: :created            # 201
      else
        render json: { errors: product.errors }, status: :unprocessable_entity
      end
    end
  end
end
# routes: namespace(:api) { namespace(:v1) { resources :products } }

# config/locales/en.yml
# en:
#   orders:
#     show:
#       title: "Order %{number}"
#       state: { paid: "Paid ✓", pending: "Awaiting payment" }
#   activerecord:
#     attributes:
#       order: { placed_at: "Order date" }   # form labels read this!

I18n.t("orders.show.title", number: "A-42")
I18n.l(Time.current, format: :short)         # localized dates
I18n.with_locale(:mr) { I18n.t("orders.show.title", number: "A-42") }

# in views — "lazy" keys resolve by view path:
# app/views/orders/show.html.erb:  <%= t(".title", number: @order.number) %>
#                                       ^ means orders.show.title

# per-request locale — the standard hook:
# around_action { |_, blk| I18n.with_locale(current_user&.locale || :en, &blk) }

# $ bin/rails generate authentication     (Rails 8 — writes all of this)
# The core it generates, worth understanding line by line:

class User < ApplicationRecord
  has_secure_password            # needs password_digest column + bcrypt gem
  normalizes :email_address, with: ->(e) { e.strip.downcase }
end

User.create!(email_address: "asha@corp.com", password: "s3cure-pass!")
# INSERT ... password_digest = "$2a$12$N9qo8uLOickgx2ZMRZoMye..."

user = User.authenticate_by(email_address: "asha@corp.com",
                            password: "s3cure-pass!")   # timing-attack safe
user ? "in" : "out"

# session controller sets: session[:user_id] / signed cookies
# API flavor: user.generate_token_for(:api) — expiring signed tokens

class PostPolicy < ApplicationPolicy         # gem "pundit"
  def update? = user.admin? || record.author_id == user.id
  def destroy? = user.admin?

  class Scope < Scope                        # "which rows exist for me?"
    def resolve
      user.admin? ? scope.all : scope.where(published: true)
                                     .or(scope.where(author_id: user.id))
    end
  end
end

class PostsController < ApplicationController
  include Pundit::Authorization
  after_action :verify_authorized, except: :index    # forget = raise!

  def index  = @posts = policy_scope(Post)            # scoped SELECT
  def update
    @post = Post.find(params[:id])
    authorize @post                # raises Pundit::NotAuthorizedError
    @post.update!(post_params)
  end
end
# view: <%= link_to "Edit", ... if policy(post).update? %>

# $ bin/rails active_storage:install && rails db:migrate

class Product < ApplicationRecord
  has_one_attached  :photo
  has_many_attached :manuals

  validates :photo, content_type: %w[image/png image/jpeg],   # gem a-s-validations
                    size: { less_than: 5.megabytes }
end

product.photo.attach(params[:photo])       # from form_with file_field
product.photo.attached?

# views — variants resize lazily, cached forever:
# <%= image_tag product.photo.variant(resize_to_limit: [300, 300]) %>
# <%= f.file_field :photo, direct_upload: true %>   ← browser → S3 directly

url_for(product.photo)                      # signed, expiring URL

class ReceiptJob < ApplicationJob
  queue_as :default
  retry_on Net::OpenTimeout, wait: :polynomially_longer, attempts: 5
  discard_on ActiveRecord::RecordNotFound   # order deleted? drop the job

  def perform(order_id)                 # pass IDs, never objects!
    order = Order.find(order_id)
    return if order.receipt_sent?       # idempotency guard
    ReceiptMailer.send_receipt(order).deliver_now
    order.update!(receipt_sent: true)
  end
end

# enqueue — controller or after_commit callback (topic 69!):
ReceiptJob.perform_later(order.id)
ReceiptJob.set(wait: 10.minutes).perform_later(order.id)

class ReceiptMailer < ApplicationMailer
  default from: "billing@shop.example"

  def send_receipt(order)
    @order = order                       # ivars flow to the view
    @customer = order.customer
    mail to: @customer.email,
         subject: "Receipt for order ##{@order.number}"
  end
end
# views: app/views/receipt_mailer/send_receipt.html.erb (+ .text.erb twin)

ReceiptMailer.send_receipt(order).deliver_later    # via the job queue

# preview while developing — app/mailers/previews/receipt_mailer_preview.rb
class ReceiptMailerPreview < ActionMailer::Preview
  def send_receipt = ReceiptMailer.send_receipt(Order.last)
end
# → http://localhost:3000/rails/mailers

<%# fragment cache — key auto-includes product.updated_at: %>
<% @products.each do |product| %>
  <% cache product do %>
    <%= render product %>
  <% end %>
<% end %>

<%# collection render + cache in ONE line (fast path): %>
<%= render partial: "product", collection: @products, cached: true %>

stats = Rails.cache.fetch("dashboard/stats", expires_in: 5.minutes) do
  Order.group(:status).sum(:total)     # runs only on cache miss
end

# model touch chain for russian-doll invalidation:
class Review < ApplicationRecord
  belongs_to :product, touch: true     # review changes → product.updated_at bumps
end

class ProductTest < ActiveSupport::TestCase
  test "is invalid without a name" do
    p = Product.new(price: 10)
    assert_not p.valid?
    assert_includes p.errors[:name], "can't be blank"
  end

  test "discounted price applies percentage" do
    p = Product.new(price: 200, discount_pct: 25)
    assert_equal 150, p.discounted_price
  end
end

class ProductsFlowTest < ActionDispatch::IntegrationTest
  test "creating a product" do
    assert_difference "Product.count", 1 do
      post products_path, params: { product: { name: "Mug", price: 299 } }
    end
    assert_redirected_to product_path(Product.last)
  end

  test "rejects bad input" do
    post products_path, params: { product: { name: "" } }
    assert_response :unprocessable_entity
  end
end

# 1. SQL injection
User.where("email = '#{params[:email]}'")     # ❌ propped open
User.where(email: params[:email])             # ✅ parameterized
User.where("created_at > ?", params[:since])  # ✅ placeholder form

# 2. XSS (views auto-escape — topic 82)
<%= @comment.body %>                          # ✅ escaped
<%= @comment.body.html_safe %>                # ❌ stored XSS
<%= sanitize @comment.body %>                 # ✅ if HTML is required

# 3. Mass assignment (topic 55)
Product.new(params[:product])                 # ❌ raises, thankfully
Product.new(product_params)                   # ✅ allowlisted

# 4. Secrets
config/credentials.yml.enc                    # ✅ encrypted, committable
Rails.application.credentials.stripe_key      # read at runtime
ENV["STRIPE_KEY"]                             # ✅ also fine (12-factor)

$ bin/rails console
> o = Order.last
> o.status                          # "pending" — why?
> o.payments.map(&:state)           # ["failed", "failed"]
> o.payments.last.error_message     # "card_declined" — mystery solved
> ActiveRecord::Base.logger = Logger.new(STDOUT)   # show me the SQL
> Order.expiring.to_sql             # inspect a scope without running it
> app.get "/products/42"            # drive a real request from console!
> helper.number_to_currency(499.5)  # test any helper

$ bin/rails console --sandbox       # everything ROLLS BACK on exit — safe prod spelunking

def create
  @order = Order.new(order_params)
  debugger                 # server pauses HERE on next request
  @order.save
end
# in the paused terminal:
#   order_params        → inspect anything
#   next / step / continue
#   break Order#total   → breakpoint elsewhere

class ApplicationController < ActionController::Base
  # order matters: LAST declared wins ties, so put the generic FIRST
  rescue_from StandardError, with: :internal_error unless Rails.env.local?
  rescue_from ActiveRecord::RecordNotFound,    with: :not_found
  rescue_from Pundit::NotAuthorizedError,      with: :not_found  # hide existence
  rescue_from PaymentGateway::Declined do |e|
    redirect_to checkout_path, alert: "Payment declined: #{e.message}"
  end

  private

  def not_found
    respond_to do |f|
      f.html { render "errors/not_found", status: :not_found }
      f.json { render json: { error: "not_found" }, status: :not_found }
    end
  end

  def internal_error(e)
    Rails.error.report(e)          # → Sentry/Honeybadger via subscriber
    render "errors/internal", status: :internal_server_error
  end
end

Rails.logger.info  "order placed"                       # fine
Rails.logger.info  "order.placed id=#{o.id} total=#{o.total} gateway=stripe"
                                                        # grep-able: better
Rails.logger.tagged("import", batch.id) do              # prefix a whole block
  Rails.logger.info "start rows=#{rows.size}"
end

# time anything:
ActiveSupport::Notifications.instrument("import.batch", rows: rows.size) do
  process(rows)
end
ActiveSupport::Notifications.subscribe("import.batch") do |event|
  Rails.logger.info "import.batch #{event.duration.round}ms rows=#{event.payload[:rows]}"
end

# config/environments/production.rb — one line per request:
# config.log_tags = [:request_id]     ← ties every log line to its request

# reference data — idempotent, safe to run ANY time, ANY env:
%w[starter pro enterprise].each_with_index do |name, i|
  Plan.find_or_create_by!(slug: name) do |p|     # find_or_create = re-runnable
    p.name, p.position = name.titleize, i
  end
end

# dev/demo sample data — guarded and generated:
if Rails.env.development?
  require "faker"
  admin = User.find_or_create_by!(email_address: "admin@example.com") do |u|
    u.password = "password"; u.role = :admin
  end
  50.times do
    c = Customer.find_or_create_by!(email: Faker::Internet.unique.email) do |x|
      x.name = Faker::Name.name
    end
    c.orders.create!(total: rand(100..9000),
                     status: Order.statuses.keys.sample,
                     created_at: Faker::Time.backward(days: 90))
  end
end
puts "Seeded: #{Plan.count} plans, #{Customer.count} customers"

service: shop
image: balu/shop
servers:
  web: [203.0.113.10]
  job:
    hosts: [203.0.113.11]
    cmd: bin/jobs                    # Solid Queue workers
proxy:
  ssl: true                          # auto Let's Encrypt
  host: shop.example.com
registry:
  username: balu
  password: [KAMAL_REGISTRY_PASSWORD]
env:
  secret: [RAILS_MASTER_KEY, DATABASE_URL]

# 1. every dev page, always-on: rack-mini-profiler (badge shows ms + SQL count)
# Gemfile(dev): gem "rack-mini-profiler"

# 2. the request log — already telling you (topic 99):
# Completed 200 OK in 840ms (Views: 210ms | ActiveRecord: 590ms | Allocations: 148k)
#                                            ^^^^^ DB-bound: hunt queries first

# 3. find the queries:
Order.recent.explain(:analyze)      # your EXPLAIN, via ActiveRecord
# config: config.active_record.query_log_tags_enabled = true
#         → every SQL gets a comment: /*controller:orders,action:index*/
#           pg_stat_statements now maps hot SQL to Rails code! (playbook #22)

# 4. common wins, in the order they usually pay:
Order.includes(:customer)           # N+1 (topic 67)
add_index :orders, [:status, :created_at]   # the WHERE you filter hourly
Order.select(:id, :total)           # stop loading 40 columns for 2
Rails.cache.fetch(...) { ... }      # cache the proven-expensive (topic 96)