Ash Framework

Ash is highly extensible through a variety of specialized packages. Depending on your requirements, you may need to install additional packages for:

Data Layers

Connect Ash to different storage engines:

• AshPostgres: PostgreSQL
• AshSqlite: SQLite
• AshCsv: CSV files
• AshCubdb: CubDB

API & Web

Expose your resources via web interfaces:

• AshJsonApi: JSON:API builder
• AshGraphql: GraphQL builder
• AshPhoenix: Phoenix integrations
• AshAuthentication: User authentication (Password, OAuth, etc.)

Utilities & Advanced Features

• Background Jobs: AshOban (backed by Oban)
• Auditing & History: AshPaperTrail (history) and AshArchival (archiving)
• State Management: AshStateMachine
• Security: AshCloak (attribute encryption)
• Admin UI: AshAdmin (push-button admin interface)
• Testing: Smokestack (declarative test factories)

Ash documentation is organized into three distinct categories to help you find information based on your current goal:

1. Topics: Understanding-oriented documentation. Use these to discover design patterns, core features, and how different parts of Ash (like Resources, Actions, or Security) work together.
2. How-to Guides: Goal-oriented recipes. Use these when you have a specific task to accomplish (e.g., 'Write Queries', 'Encrypt Attributes', or 'Wrap External APIs').
3. Reference: Information-oriented documentation. This is automatically generated from source code and covers every Ash module, function, expression, and DSL.

Tip: When using the Hexdocs search bar, prefix your search with dsl (e.g., dsl name) to jump directly to DSL-specific reference information.

A fully atomic update is an action where every part of the process (changes, validations, etc.) is performed in a single operation in the data layer. This prevents race conditions in concurrent environments.

Non-atomic example (Unsafe): Using an anonymous function that reads the current value in memory and then sets a new one. If two processes do this simultaneously, one update will be lost.

update :increment_score do
  change fn changeset, _ ->
    Ash.Changeset.change_attribute(changeset, :score, changeset.data.score + 1)
  end
end

Atomic example (Safe): Using atomic_update to tell the data layer to increment the value directly.

update :increment_score do
  change atomic_update(:score, expr(score + 1))
end

Policies follow a specific evaluation flow:

1. All applicable policies must pass.
2. Within a policy, checks are evaluated from top to bottom.
3. The first check that produces a decision determines the result.

Implementing AND logic

Because the first successful check stops evaluation, using multiple authorize_if statements creates OR logic. To require BOTH conditions (AND logic), use one of these patterns:

1. Use forbid_unless for the first requirement:

   policy action_type(:update) do
     forbid_unless actor_attribute_equals(:admin?, true)
     authorize_if relates_to_actor_via(:owner)
   end

2. Use a single complex expression: authorize_if expr(condition1 and condition2)
3. Use multiple separate policies: Each policy must pass independently.

An Ash extension is typically composed of one or more Spark.Dsl.Extension modules and additional supporting code. Extensions allow you to modify the DSL (Domain Specific Language) of entities like Resources or Domains. For example, AshGraphql provides both a domain extension (AshGraphql.Domain) and a resource extension (AshGraphql.Resource).

To create a basic extension, you define a module that uses Spark.Dsl.Extension and specifies a list of transformers.

defmodule MyApp.Extensions.Base do
  use Spark.Dsl.Extension, transformers: [MyApp.Extensions.Base.AddTimestamps]
end

Both Aggregates and Calculations are special types of fields that are not necessarily stored directly in the data layer, but they serve different purposes:

• Aggregate: A specialized type of calculation used to summarize related information from associated records (e.g., counting the number of Ticket resources associated with a Project).
• Calculation: A field that is generated on-demand. It derives its value from other information on the record or from external data sources.

In Ash, attributes, calculations, aggregates, and relationships are private by default (public?: false).

• Internal Code: When using core Ash functions like Ash.read/2, the public/private status does not affect visibility; you can read any attribute.
• API Extensions: When using extensions like AshGraphql or AshJsonApi, only fields explicitly marked as public?: true will be included in the generated interfaces. This prevents accidental data exposure through external APIs.

An Actor is the entity that performs an action.

Actors are typically used for auditing or for writing policies to control authorization. While an actor can be any value (like a map), it is highly recommended to use a struct to represent the entity performing the action.

Common examples of actor types include:

• %MyApp.Accounts.User{}
• %MyApp.Accounts.Device{}
• %MyApp.SystemUser{}

Manually constructing changesets can be verbose. You can use Code Interfaces to derive high-quality, concise functions on your resource modules.

For example, instead of manually building a changeset, a code interface allows you to call: Helpdesk.Support.Ticket.assign!(representative.id)