Ash Framework

Introducing Temporal Resources

2026-10-03T11:40:12+00:00

Temporal resources are a new, experimental feature in Ash: resources that remember every state their records have ever been in, so you can read and write them as of any moment, past, present or future, with a single option.

Matt Beanland

2026-10-01T00:00:00+00:00

Ash Framework 3.0

2024-09-15T03:24:22+00:00

Ash Framework 3.0: Official Release!

I'm here with the fine folks at Gig City Elixir, pushing the button live on stage 😎

The other packages around Ash will be updated with non-release candidate versions over the next few hours.

What is changing?

While there are far too many things to put them all here, I want to give those who haven't been following along with our 3.0 teasers an idea of where the focus is for Ash 3.0. There are three themes that cover most of the changes:

Security: We want to make sure that Ash is safe and secure by default, and that it is free of foot guns that could lead to security issues, data consistency or other critical failures. Some examples of this are:
Simplicity: Ash is a huge ecosystem, and there is a lot to learn about how it works. Every confusing term and inconsistency increases the mental burden on developers, and increases the likelihood of bugs and wasted time. Some examples of this are:
- Ash.Api is now Ash.Domain
- Not selected attributes show %Ash.NotLoaded{} instead of nil
Developer Experience: With 2.x versions adding support for atomics and bulk actions, the core functionality of Ash is in a very good place. This gives us the time and mental cycles to devote to developer experience. While many of the 3.0 changes are focused on DX, we also expect to see a much greater focus on this moving forward! Some examples of this are:

How do I upgrade?

It is very important that you read and follow the upgrade guide! You will need to go through it section by section and consider if there are changes from that section that you must make. Don't forget that some packages have their own upgrade guides for breaking changes contained in that package. Links to those guides are at the top.

What if I need help?

If you encounter an issue or change that is not covered in the upgrade guide please contact us or open a PR to add to the guide. Even if it's just a note reminding folks to look out for something that might be a gotcha. Every little bit helps :)

Feel free to ask questions here on the forum if you need assistance!

What about 2.x?

Ash 2.x will receive a minimum of 6 months of critical bug fixes and security upgrades. Critical bug fixes include issues that have no reasonable workaround. Security upgrades includes things like updating potentially vulnerable packages, or fixing any issues related to policies, authentication, etc. We won't be leaving folks in the dust, but it will absolutely be in your best interest to find a time in the next few months to upgrade, as there are many features in 3.0 to take advantage of and there are already more on the way!

And don't forget, the Ash book is coming! Keep an eye out for updates 🥳. Thanks again to @sevenseacat for all her fine work on this book, its coming along spectacularly.

Jonatan Männchen

2024-08-01T00:00:00+00:00

Rebecca Le

2024-06-01T00:00:00+00:00

Riccardo Binetti

2024-06-01T00:00:00+00:00

Robert Timis

2024-06-01T00:00:00+00:00

Barnabas Jovanovics

2023-10-01T00:00:00+00:00

There are macros and there are macros

2023-05-11T20:00:29+00:00

A common criticism of Ash is that it has too many macros. This is an understandable position to take, but I think its important to distinguish between two main kinds of macros. One of them should be used extremely sparingly, and the other I think its okay to use a bit more liberally. We'll call them "configuration macros" and "metaprogramming macros". Keep in mind these names are a bit made up and the boundary between the two is not always cut and dry. When people talk about "magic" in the context of macros, they are mostly talking about "metaprogramming macros". Lets take a look at some examples.

Metaprogramming Macros

This snippet is from NX. This function can run as regular elixir code, or it can be compiled to run using multiple backends meant for numerical processing, including running on the GPU. The code that is actually compiled under the hood looks dramatically different from what you see in front of you. This is not a bad thing! If you had to use or write the actual underlying code, you'd get nothing done. Check out Nx's documentation for more.

defn softmax(t) do
  Nx.exp(t) / Nx.sum(Nx.exp(t))
end

Here is an example from Nebulex, an ETS based caching library. In this example, the metaprogramming is quite hidden from you. The actual logic happens in a compiler callback. It involves rewriting the functions to intercept calls and decide if the cached version should be used, or if the value should be computed and cached. This kind of macro is quite magical given how indirect it is, but at the same time in applications where cached functions are common, it stops feeling like magic and starts feeling like a language feature. If I was looking at a large code-base that used this once, I'd likely be concerned. The mental overhead of understanding it for one single case likely isn't worth it.

defmodule MyApp.Example do
  use Nebulex.Caching

  @decorate cacheable(cache: MyApp.Cache, key: :cache_key)
  def get_by_name(name, age) do
    ...
  end
end

This one is from Ash. We do similar magic to the Nx example from above for this. Specifically, we have an expression that can be run natively to a data layer (i.e SQL) or in elixir. And Ash reserves the right to decide where it gets run, depending on the context and requirements.

calculate :full_name, :string, expr(first_name <> " " <> last_name)

As you can see, all of these examples represent a significant amount of complexity boiled down to very simple macros. This will also be true of the upcoming examples of "configuration macros", but the big difference here is that each macro call represents very complex code being executed on your behalf.

Configuration Macros

Lets take a look at some examples of macros that I would consider less magical.

This one is likely familiar to most people who have worked with Elixir professionally. Here we have an Ecto.Schema. In this example we actually have three separate macros. The schema/2 macro sets up some module attributes, and field/2 adds to those module attributes. timestamps/0 sets up the schema to track inserted_at and updated_at timestamps. On its own, however, an Ecto.Schema doesn't really do anything. There also isn't a bunch of code hidden behind the scenes that you need to be aware of being executed. This sets up some information on the module that can be read back later. For example: MyApp.MySchema.__schema__(:fields) would return [:field_name, :inserted_at, :updated_at] in this case. This is a classic example of what I'd call a "configuration macro".

defmodule MyApp.MySchema do
  schema "table" do
    field :field_name, :type

    timestamps()
  end
end

Here we can see an example from Absinthe's documentation. Absinthe is a tool for building GraphQL apis with Elixir. This one slightly straddles the line between "configuration macros" and "metaprogramming macros", but I think still lands on the side of a "configuration macro". We configure a field in our GraphQL API, and how to resolve it. There are quite a few macros involved in building an API with Absinthe. Here we configure what code gets run to resolve a given field, but ultimately the responsibility for what code runs is our own.

defmodule BlogWeb.Schema do
  use Absinthe.Schema
  ...

  query do
    @desc "Get all posts"
    field :posts, list_of(:post) do
      resolve &Resolvers.Content.list_posts/3
    end
  end
end

Finally, lets take a look at some code from an Ash.Resource. I'll choose a relatively complex example, specifically the defining of an "action".

create :create do
  primary? true

  accept [:text]

  argument :public, :boolean do
    allow_nil? false
    default true
  end

  change fn changeset, _ ->
    if Ash.Changeset.get_argument(changeset, :public) do
      Ash.Changeset.force_change_attribute(changeset, :visibility, :public)
    else
      changeset
    end
  end

  change relate_actor(:author)
end

For those not familiar with Ash, lets break it down.

primary? true means that if something wants to create one of these, this is the action it should call by default. This is used by certain internal actions and can be used by you or other extensions to determine which action to call in lieu of an explicitly configured action.
accept [:text] means that you can set the text attribute when calling this action.
argument :public, :boolean, … adds an additional input to the action that doesn’t map to an attribute, called :public that must have a value, but defaults to true.
The anonymous function you see with change fn changeset, _ -> is what we call an "inline change". A change is a function that takes a changes and returns a changeset. If you’ve worked with Phoenix or with Plug, you’ll recognize this pattern, it works effectively the same as Plug, working on a Conn. Except in this case, its a change working on an Ash.Changeset. We use this argument to map a boolean toggle input to an enumerated attribute. change relate_actor(:author) refers to a "built in change". This change is provided by Ash out of the box, and this relates the actor (A.K.A current user) to the thing that was just created as the :author.

These are all macros! However, they again map to an introspectable structure, acting more as configuration than as a traditional macro.

iex(1)> Ash.Resource.Info.action(Twitter.Tweets.Tweet, :create)
%Ash.Resource.Actions.Create{
  name: :create,
  primary?: true,
  type: :create,
  …
  arguments: [
    %Ash.Resource.Actions.Argument{
      name: :public,
      …
    }
  ],
  changes: [
    %Ash.Resource.Change{...},
    %Ash.Resource.Change{
      change: {Ash.Resource.Change.RelateActor,
       [allow_nil?: false, relationship: :author]},
      …
    }
  ],
  …
}

This inversion of control is something we're familiar with in other tools like Plug or Phoenix.Endpoint/Router. They are great examples of how this pattern can allow for code reuse, and make complex chains of behavior easier to reason about.

Its not necessarily about macros

Above I've made a case for macros not necessarily being what gives Ash its relatively steep learning curve. We've also create a large suite of tools to mitigate the difficulties that these configuration macros can have. Take a look at spark for more information on those tools.

With that said, in that one example above, we had to add five new words to our vocabulary. This is what can make Ash difficult. When you set out to write your own application patterns, you can let your own vocabulary evolve. This provides a natural learning curve. I'd also argue that it gives you tons of opportunities to repeat the mistakes of every developer who went through that same process.

Therein lies the rub

Ash presents a huge suite of integrated tools, a suite that gets bigger and bigger every day and, in order to leverage it, you need to learn a whole new way of doing things. This is a very valid reason not to use Ash. Our biggest proponents will tell you that it’s worth it to put in the effort to learn these tools. As would I. And I don’t mean for the idea of what the framework may become, but for the benefits you can get right now.

With that said, I think a diversity of mindsets is the most important thing that we can foster as a community, and there is a fine line between telling people "Hey, I think we’ve got some good ideas over here, I think you should check them out", and saying "Hey, this is the right way to do things, stop doing things your way and do them our way". So while I’m of course a proponent of Ash, my plan is not to talk anyone into using it. I have one simple goal, which is to continue to expand this integrated suite of tools, adding new capabilities that are only possible for things built in this way. Ash is a snowball, rolling down a hill, and it has barely even begun to gather snow. By doing this, we move the threshold by which cost of learning the "Ash way" is offset by the benefits. For many users (more every day) that threshold has already been crossed. For others, it may never be crossed, and thats okay 😊. If the tools we build can help even one person find success on their Elixir journey, then I’m a happy camper.

Parting Words

The cost of learning something like Ash is not trivial. It depends on you, your problem space, your experience level, and many other factors as to whether or not that juice is worth the squeeze. My goal, and the core team's goal, is to continue to provide leverage for those already using Ash. To take the patterns we've set down and take them even further, increasing the value of our existing users' investments. Partially because we count among those users, but also because we believe in what we're building and its ability to help us and others build bigger and better software.

Happy Holidays from Ash Framework!

2022-12-22T23:49:03+00:00

Happy Holidays!

This year has been a wild ride 🎢. So much has gone into Ash Framework this year, and our user base has increased massively in that time frame, and there is so much more to come. We have some huge things just around the river bend 🎉, and I can't wait for you all to see it!

Note: A strangely necessary foreword:

This message was not built by or with the use of any ML algorithms. There is a place for generated content, but a thank you to my users and the community is not that place.

When I set out to build Ash, it was about technology💻. It was about what I felt was missing from the Elixir ecosystem and from the programming ecosystem in general. It was something I believed in, and something that I thought other people would want to use, but it was fundamentally about what I wanted. Then the users started trickling in, and it became about a whole lot more. This work has become so much more meaningful than I ever thought it could be and, perhaps a bit delusionally, I think this project can make a real difference on the lives and livelihoods of the people that I've come to care so deeply about. Just like the amazing people who built Elixir and its community up to what it is today. That is what this project is about for me now, and it is what keeps me going.

Community

I'd like to start by thanking the community 🫂 in general, which is exemplified by the Ash Framework Discord. It has become a thriving place, filled with wonderful and helpful people. I thought it was going to be a place for Ash Framework support, but its turned into a place for people with similar ideas about how things ought to be built to talk about anything under the sun. A few fast friendships have sprung from the community, and its been an amazing pleasure to help you all and to see you help each other. If you want to meet and learn about all these amazing folks, join us!

Contributors

Contributions come in many forms, but I'd like to kick this off by thanking everyone who contributed directly to Ash. To all those who added features, fixed bugs, or improved documentation, you have my eternal gratitude. I've never been more busy than I have this last year, so contributions like those that take work directly off my plate are invaluable. More importantly than helping me, these contributions compound over time and help every Ash user, and as such even small contributions have an incalculable impact on the trajectory of Ash. I hope you feel empowered to contribute again, and I hope that anyone else who is interested feels just as empowered to do so.

Another way that people contribute is by creating issues, making feature requests, or just making us aware of issues. It would be easy to see these as a burden. After all, they do typically mean more work for me to do. Maybe on my most cynical days, I feel this way 😆. In reality, it couldn't be further from the truth. I'd like to thank everyone who took the time to point out issues, either by writing up a Github issue or by letting us know in the discord. With each issue resolved, the experience for the next person is that much better. With each suggestion of what Ash could do better or differently, we come to a better shared understanding of where Ash is headed and how it can be made better. Thank you all for your time, effort, and ideas!

Ash Framework 2.0 Release

2022-11-01T04:48:42+00:00

Ash Framework

What is Ash?

Ash Framework is a declarative, resource-oriented application development framework for Elixir. A resource can model anything, like a database table, an external API, or even custom code. Ash provides a rich, and extensive set of tools for interacting with and building on top of these resources. By modeling your application as a set of resources, other tools know exactly how to use them, allowing extensions like AshGraphql and AshJsonApi to provide top tier APIs with minimal configuration. With filtering, sorting, pagination, calculations, aggregations, pub/sub, policy authorization, rich introspection, and much more built-in, as well as a comprehensive suite of tools to allow you to build your own extensions, the possibilities are endless.

For those familiar with Phoenix, you can think of Ash as a declarative application modeling layer designed to replace your Phoenix contexts.

Ash Framework 2.0

Ash Framework 2.0 has been released! This begins the official stable release cycle (although it was already quite stable). Thanks to everyone in the community who helped make this possible, from the contributors, the curious, to those already using Ash in prod. I'm eternally grateful for all of your support.

Additionally, I'd like to thank Alembic, who have brought me on to work on Ash full time. Alembic is building complex software with small teams in record time by leveraging tools like Ash Framework and Phoenix LiveView.

Along with the 2.0 release of core, the AshPostgres, AshPhoenix and AshArchival packages have had 1.0 version released as well. AshGraphql is next up, and should be released in the next few weeks. Feel free to dive in to it before then, though :).

Is Ash an alternative to X?

Ash is not meant to be an alternative to Phoenix, Ecto, or Absinthe. Ash uses Ecto under the hood, AshGraphql uses Absinthe. Phoenix is absolutely the recommended way to build web interfaces on top of your Ash application (there is a whole package dedicated to it, AshPhoenix). Ash is not meant to be the only way that you ever interact with your data, so it is almost a certainty that you will need to use Ecto in some cases. For instance, Ash does not currently support bulk actions or atomic updates. For this reason, you can implement custom actions for things that can be encapsulated in your resource, and you have all of Elixir at your disposal to implement custom behavior outside of your resources, with a wide array of escape hatches in between.

Extensions

Extensions in 1.0+

AshPostgres - Back a resource with postgres. Rich querying capabilities, supporting aggregates, calculations, and fragments. Comes with a migration generator to get you up and running in record time!
AshPhoenix - Helpers to integrate Ash Resources with Phoenix. Tools like AshPhoenix.Form allow you to build forms over your resources, and manage complex nested related data with one data structure.
AshArchival - A tiny but powerful extension. Get archival (A.K.A soft deletion) with one line of code.

Extensions <1.0

AshGraphql - Create a GraphQL from your resources with only a few lines of code. Backed by the excellent Absinthe library. It comes with its own fully implemented dataloader, and automatically derives all the types, fields, and mutations automatically. Getting a relay compatible GraphQL API is as easy as setting the relay? toggle.

AshJsonApi - Create a JSON:API spec compliant API in minutes.
AshAdmin - A rich admin UI automatically derived from your resource definitions.
AshCsv - Back your resource with a CSV file.
Spark - The core declarative DSL library that backs Ash and its extensions.

Unreleased Extensions

AshPaperTrail - Creates and manages a versions table for a resource, and writes all changes to that version resource. With one line of code.
AshJsonApiWrapper - Back your resource with an external API using finch and configuration to describe how your resource maps to the response from the external service.

Your Own Extensions

All of the extensions above are created with a set of tools that are free to use to create your own extensions. They can all be used as a basis point, or as inspiration. Many users have created their own extensions for various reasons. An extension can both add to the resource's DSL and programatically restructure the resource. For example, AshArchival adds an attribute, modifies every destroy action, and adds a "base filter" to the resource. This allows for extremely powerful extensions.

Links

Expect to see a lot more content before long, like tutorial and short, topical videos.

Where to start?

Ash is quite broad, and covers a considerable amount of ground. My suggestion is to follow the tutorials for a kicking off point. There are getting started guides for each individual package as well that, combined, will get you up and running from scratch.

😎 Happy hacking! 😎

Ash Framework

Introducing Temporal Resources

Matt Beanland

Ash Framework 3.0

Ash Framework 3.0: Official Release!

What is changing?

How do I upgrade?

What if I need help?

What about 2.x?

Jonatan Männchen

Rebecca Le

Riccardo Binetti

Robert Timis

Barnabas Jovanovics

There are macros and there are *macros*

Metaprogramming Macros

Configuration Macros

Its not necessarily about macros

Therein lies the rub

Parting Words

Happy Holidays from Ash Framework!

Happy Holidays!

Community

Contributors

Sponsors

Ash Framework 2.0 Release

Ash Framework

What is Ash?

Ash Framework 2.0

Is Ash an alternative to X?

Extensions

Extensions in 1.0+

Extensions <1.0

Unreleased Extensions

Your Own Extensions

Links

Where to start?

There are macros and there are macros