ash-framework

Ash Framework Reference

Reference for Ash Framework in Phoenix/LiveView projects. Ash complements Phoenix/Ecto — LiveView, security, and OTP Iron Laws still apply. Only data access patterns shift toward Ash actions and domain code interfaces.

Iron Laws

1. USE DOMAIN CODE INTERFACES — Never call Ash.create/Ash.read directly in LiveViews or Controllers; use domain code interfaces: MyApp.Accounts.register_user() not Ash.create(User, attrs)
2. SET ACTOR/SCOPE AT QUERY PREP, NOT EXECUTION — Pass actor: or scope: to for_read/for_create/for_action (prep), NOT to Ash.read!/Ash.create! (execution); execution-level actor bypasses row-level policy evaluation. If project uses Ash.Scope, pass scope: consistently instead of bare actor: — do not mix styles
3. GENERATORS FIRST — Before writing Ash code manually, run mix ash.gen.resource or mix ash.gen.domain with --yes; check mix help ash.gen.<task> for options
4. CODEGEN AFTER RESOURCE CHANGES — Always run mix ash.codegen after modifying resources; this generates migrations from resource snapshots — never write AshPostgres migrations by hand
5. ACTIONS OVER FUNCTIONS — Put business logic in named actions, not domain functions; expose via code interfaces defined on the domain
6. NEVER EDIT RESOURCE SNAPSHOTS — priv/resource_snapshots/ is owned exclusively by mix ash.codegen; manual edits corrupt migration tracking
7. NO DIRECT Repo.* IN ASH PROJECTS — Repo.all/get/insert bypass Ash policies and notifications; use domain code interfaces. Any Repo call in an Ash project is an escape hatch and must be documented

Quick Reference

Domain Code Interface Pattern

# Domain definition
defmodule MyApp.Accounts do
  use Ash.Domain

  resources do
    resource MyApp.Accounts.User do
      define :register_user, action: :create, args: [:email, :password]
      define :get_user_by_email, action: :read, get_by: [:email]
    end
  end
end

# In LiveView/Controller — always via domain, never Ash.create directly
{:ok, user} = MyApp.Accounts.register_user(email, password, actor: nil)
user = MyApp.Accounts.get_user_by_email!(email, actor: current_user)