DEV Community: Dennis Beatty

Use the new Enum type in Ecto 3.5

Dennis Beatty — Tue, 05 Jan 2021 17:20:33 +0000

Booleans are one of the oldest constructs in programming. They're simple. Binary. And we use booleans everywhere. One of my earliest software projects had a database table called "users" with several columns used to specify role like is_admin, is_moderator, and is_seller.

%User{is_admin: false, is_moderator: false, is_seller: false}

This gets even worse when booleans are used to represent some sort of state. For example a payment service that stores its state in booleans could potentially have columns like is_authorized, is_captured, is_failed, and is_refunded. That's just complicated. And that's just with a single piece of state. Many places support partial refunds, which means now you've got another boolean is_partial_refund.

%Payment{
  is_authorized: false,
  is_captured: false,
  is_failed: false,
  is_refunded: false,
  is_partial_refund: false
}

But there's another issue: now you can have impossible states. For instance if somehow a record has is_partial_refund set to true but is_refunded set to
false what does that even mean? Or if a record has is_failed set to true but also is_captured set to true. Make impossible states impossible!

Enums

Enums allow us to do just that. They enable a variable to contain a value from a set of predefined constants. In a statically-typed language, enum values are checked at compile time to eradicate bad values. Elixir is dynamically-typed, so we don't get that safety guarantee, but that doesn't demean enums' usefulness.

The user example above is made simpler with the use of an enum:

%User{role: :admin}

The role field would contain one of the following atoms: :admin, :moderator, :seller, :buyer. That simplifies our user struct immensely, but the difference is even bigger with the payment example:

%Payment{status: :pending}

Instead of setting different combinations of five boolean flags, we can change the status to one of :authorized, :captured, :failed, :refunded, or :partially_refunded. And there is no way for the payment to get into one of the impossible states mentioned above. But how does this work with a database?

Rolling your own enums with Strings

The simplest way to store "enums" in a database with Elixir and Ecto has been to roll your own enums. By creating a new varchar column on your table, you can then write the appropriate string to it when creating or updating a record.
Ecto.Changeset.validate_inclusion/4 will allow you to check that the string being provided contains one of the supported values so that you're not inputting bad data.

But that safety only exists at the application layer. It ignores the potential that someone accessing the database directly could input a bad value by bypassing the application. If a bad string gets in and the application doesn't handle it, that bad string will crash the process. But you shouldn't have to waste time validating values coming from your data layer. Your application deserves better.

EctoEnum

Postgres and MySQL have the ability to create enum types that can be used for columns and will validate them at the data layer rather than the application layer. This means that your data store would be protected from bad values. For
a long time, the EctoEnum library has been the best way to set up custom enum types for Postgres:

# lib/my_app/accounts/user_role.ex
defmodule MyApp.Accounts.UserRole do
  use EctoEnum, type: :user_role, enums: [:admin, :moderator, :seller, :buyer]
end

# lib/my_app/accounts/user.ex
defmodule MyApp.Accounts.User do
  use Ecto.Schema
  alias MyApp.Accounts.UserRole

  schema "users" do
    field :role, UserRole
  end
end

# priv/repo/migrations/20210102193646_add_role_to_users.exs
defmodule MyApp.Repo.Migrations.AddRoleToUsers do
  use Ecto.Migration
  alias MyApp.Accounts.UserRole

  def change do
    UserRole.create_type()

    alter table(:users) do
      add :role, :user_role
    end
  end
end

It requires creating a new module for the enum type, but it has some nice conveniences for using the type in your schema and for creating the type in your migrations in the first place. But using one more dependency also means one more thing in the application that has to be maintained.

Ecto 3.5

Ecto 3.5 was released in October 2020, and it included the new Ecto.Enum module. The module's documentation expects the Enum type to be a string when stored in the database, but we can also make it work with a Postgres enum. This means you can now use enums without needing another library. Ecto SQL still doesn't have convenience functions for creating enums in migrations (yet) so you'll have to drop down to raw SQL and do that manually:

defmodule MyApp.Repo.Migrations.AddRoleToUsers do
  use Ecto.Migration

  def up do
    execute("CREATE TYPE user_role AS ENUM ('admin', 'moderator', 'seller', 'buyer')")

    alter table(:users) do
      add :role, :user_role
    end
  end

  def down do
    alter table(:users) do
      remove :role, :user_role
    end

    execute("DROP TYPE user_role")
  end
end

Then you can add an enum to your schema without having to create a new module and Ecto type though:

defmodule MyApp.Accounts.User do
  use Ecto.Schema

  schema "users" do
    field :role, Ecto.Enum, values: [:admin, :moderator, :seller, :buyer]
  end
end

Just like the EctoEnum library, Ecto handles all of the casting for changesets, and the role is available as an atom rather than a string. This provides some safety because you will be able to more easily differentiate between the
unsafe string values provided by users and the safer atoms that have been validated by the application.

What do you think?

Do you like the new Ecto.Enum API, or do you wish the API was different? Are you going to stick to the EctoEnum library or to just using Strings? Let me know on Twitter!

And if you liked this post, hopefully you'll like the others I write. Subscribe to my email newsletter and get a notification whenever I write a new one!

Happy New Year!

How to Create a Todo List with Phoenix LiveView

Dennis Beatty — Mon, 02 Nov 2020 17:03:20 +0000

Update Nov 2, 2020: It's been over a year and a half since I first published this Phoenix LiveView tutorial. Since then a lot has changed with the library. I've now updated the entire tutorial to work with Phoenix 1.5 and Phoenix LiveView 0.14. The new generators will let you get up and running a lot faster. As always let me know on Twitter if there's anything you don't understand or want me to cover more in depth!

I previously released a pretty basic Phoenix LiveView tutorial where we made a simple counter that you could increment and decrement. Phoenix LiveView is a great solution for anyone who wants to get a real-time app out to the world quickly without spending a ton of time building out both frontend and backend. Today I want to show you just how simple it can be to build something that is a little more useful than a counter: a todo list. Because we're building it to be database backed, you could use this same pattern for business applications to add real-time functionality without much overhead.

Since this is a tutorial for a bigger project, I've created the entire thing on GitHub as well. If you prefer you can see the code there. If you click the computer emoji next to any of the section titles, it will take you to the corresponding commit so you can check what you have against the full codebase there.

New LiveView Project 💻

To start out, set up a new project with Phoenix LiveView. Thanks to the changes to the generator in Phoenix 1.5, all of the LiveView boilerplate will be added for you when you generate a new project. First, make sure you have the latest version of the generator:

mix archive.install hex phx_new

As of the time of writing, version 1.5.4 is the latest. With it installed, you can create a new project. Including the live flag will include all the boilerplate necessary to get LiveView up and running:

mix phx.new live_view_todos --live

Use Y to download and install dependencies, and then cd into the new project directory and setup its database:

mix ecto.setup

And now you can start your server, and go to http://localhost:4000 in your browser to see your application running

mix phx.server

Generate the Schema 💻

With your basic project up and running, you'll want to create the table for the todos. Since there are already plenty of great Phoenix tutorials out there, I'm going to skip over how to build out our data schema manually. Just use the Phoenix generator to do that quickly:

mix phx.gen.context Todos Todo todos title:string done:boolean

Then migrate your database:

mix ecto.migrate

That should be everything you'll need from the database standpoint, as well as all the functions you'll need to work with your database. Now you'll create an interface for interacting with the todo list.

Set up the page 💻

I always like to start from the top level when creating a page and work down to the lowest level. So let's start at the router. You should have a route that looks like this:

live "/", PageLive, :index

Replace that route with a new one for the todo list:

live "/", TodoLive, :index

If you try to run your app, you'll see a compilation error because TodoLive doesn't exist yet. Go ahead and create a new file at lib/live_view_todos_web/live/todo_live.ex. Implement the standard mount callback, and use the render callback to render an example string inline:

defmodule LiveViewTodosWeb.TodoLive do
  use LiveViewTodosWeb, :live_view

  def mount(_params, _session, socket) do
    {:ok, socket}
  end

  def render(assigns) do
    ~L"Rendering LiveView"
  end
end

Now if you start your server again with mix phx.server and open your browser to http://localhost:4000, you should see "Rendering LiveView" on the page. Awesome! Except now let's do something with it.

Display the Todo List 💻

On mount, you should load in your todo list so that the live view can render them. Update your mount function to look like this (make sure you don't forget the alias):

alias LiveViewTodos.Todos

def mount(_params, _session, socket) do
  {:ok, assign(socket, todos: Todos.list_todos())}
end

Now the live view process will have the list of todos, but it isn't actually displaying them. Create a LiveEEx file to do that. Add a new template file at lib/live_view_todos_web/live/todo_live.html.leex. In it you'll just add code to display the list of todos from the database:

<%= for todo <- @todos do %>
<div><%= todo.title %></div>
<% end %>

Previously you would have needed to also create a view module and change your render callback to call the view and tell it to render the template. Thanks to some new Phoenix magic though, a template in the same folder as the live view code that has the same name will be used automatically. For a large project with many live views and templates, this might not be the easiest way to organize things, but because this project is smaller, go ahead and take advantage of it by removing the render implementation from your live view module so that only the mount callback remains.

Now if you refresh your page, you'll see that that it's blank below the header. That's because there aren't currently any todos to display. So let's enable adding new todos to the list.

Create a Todo 💻

To start add a new form to the top of your template:

<form action="#" phx-submit="add">
  <%= text_input :todo, :title, placeholder: "What do you want to get done?" %>
  <%= submit "Add", phx_disable_with: "Adding..." %>
</form>

There's a few things to break down there. The first is the phx-submit attribute in the <form> element. This instructs LiveView to send an add action to the server that contains the contents of the form when it is submitted. The phx_disable_with attribute on the submit button is a nice LiveView feature that will disable the button when the form is submitted and change its text to Adding... so that the user won't submit it more than once. If you try clicking that button now, nothing will happen in the browser, and you'll see an error in the console:

** (UndefinedFunctionError) function LiveViewTodosWeb.TodoLive.handle_event/3 is undefined or private
  (live_view_todos) LiveViewTodosWeb.TodoLive.handle_event("add", %{"todo" => %{"title" => ""}}, #Phoenix.LiveView.Socket<...>)
  ...

That's because you haven't set up a handler for the form. You can use the second line of the stacktrace to set up the new function in the live view. Create a new handle_event function that's watching for an add event and then takes the todo information that's passed in and creates a todo. Then you'll tell it to load the list of todos again so that the list will be re-rendered. Since you're already doing that in mount, go ahead and refactor that into a private function called fetch:

def mount(_params, _session, socket) do
  {:ok, fetch(socket)}
end

def handle_event("add", %{"todo" => todo}, socket) do
  Todos.create_todo(todo)

  {:noreply, fetch(socket)}
end

defp fetch(socket) do
  assign(socket, todos: Todos.list_todos())
end

Now if you type a new title into the input and hit enter or click the Add button, you'll see that it shows up in the list below! What's cooler than a list that updates itself without us writing any Javascript? You can make it work
across multiple sessions so that if you and I are both looking at the same todo list, you can add a new item and it will show up for us both.

Updating in Real-Time with PubSub 💻

While Phoenix LiveView is the star of the show in this tutorial, its older sister Phoenix PubSub is doing a lot of the heavy lifting behind the scenes. In case you haven't used Phoenix PubSub before, it allows you to set up subscriptions in your app to listen to topics and handle events when they occur. Since the process that manages the LiveView components won't necessarily be the process updating the todo list in the database, we'll want to have the LiveView process subscribe to updates to the todos table.

Phoenix PubSub comes bundled in Phoenix by default, so all you have to do is use it. To start off, add a function in lib/live_view_todos/todos.ex to enable subscribing. Use the module name as our PubSub topic:

@topic inspect(__MODULE__)

def subscribe do
  Phoenix.PubSub.subscribe(LiveViewTodos.PubSub, @topic)
end

Now go ahead and add a call to that function into the mount callback of your live view so that processes will get subscribed on mount:

def mount(_params, _session, socket) do
  Todos.subscribe()

  {:ok, fetch(socket)}
end

Now that the process is subscribed, it will need to handle the events that come in. This can be implemented with a handle_info callback that looks like this:

def handle_info({Todos, [:todo | _], _}, socket) do
  {:noreply, fetch(socket)}
end

Notice the callback is matching on an event from the Todos topic since you used the module name for the topic name when you created it. Then it's expecting an event key that has :todo as the first element in a list. If you want to get
fancy, you could try diffing the todos yourself. With the intent of keeping this tutorial as simple as possible, we'll stick to just loading them from the database each time though.

Now that the live views are subscribed to the topic and handling events, you need to actually broadcast events to them. Go back to the Todos context and create a new function that will broadcast whenever a change occurs:

defp broadcast_change({:ok, result}, event) do
  Phoenix.PubSub.broadcast(LiveViewTodos.PubSub, @topic, {__MODULE__, event, result})

  {:ok, result}
end

And to make this all work, modify all of the functions in the context that will mutate data in the database so that they will call your new broadcast_change function:

def create_todo(attrs \\ %{}) do
  %Todo{}
  |> Todo.changeset(attrs)
  |> Repo.insert()
  |> broadcast_change([:todo, :created])
end
...
def update_todo(%Todo{} = todo, attrs) do
  todo
  |> Todo.changeset(attrs)
  |> Repo.update()
  |> broadcast_change([:todo, :updated])
end
...
def delete_todo(%Todo{} = todo) do
  todo
  |> Repo.delete()
  |> broadcast_change([:todo, :deleted])
end

And that's all there is to it! Now if you open the app in a second window, you can add new todos to the list and see that they're being added in real-time in both windows. Any time there is a change in the Todos context, it's being
broadcasted out. The live view processes listen to those changes, and then send the update down to the client in real-time. I don't know if there has ever been a way to build something like this with so little effort.

Marking Items as Done 💻

Now that you're properly creating and reading the list of todos, let's give updating a shot. Since it's a todo list, you really ought to be able to mark items as done right? To start with, modify the LiveEEx template to show a checkbox next to each todo item. Swap out this line:

<div><%= todo.title %></div>

for this:

<div>
  <%= checkbox(:todo, :done, value: todo.done) %>
  <%= todo.title %>
</div>

You'll notice that the checkbox value will be specifically handled by todo.done. This will now display whether or not an item is done. Try toggling one or two via psql (UPDATE todos SET done = TRUE WHERE id = 1;) and refresh
the page; you'll see that its box will get checked. But you want to be able to update those values using the checkboxes. Modify that checkbox line in your template to add some more attributes:

<%= checkbox(:todo, :done, phx_click: "toggle_done", phx_value_id: todo.id, value: todo.done) %>

Now your checkbox will have a phx_click as well as a phx_value attribute. You may remember this from my last tutorial, but in case you don't, phx_click adds a click handler to an item. Now when the checkbox is clicked, LiveView will send an event to the server. I didn't previously cover phx_value_* though. It will allow you to specify values that get sent to the server with the event. To see this in action, go ahead and save your new template and then click on one of our checkboxes. You should see an error like this in your terminal where your application is running:

** (FunctionClauseError) no function clause matching in LiveViewTodosWeb.TodoLive.handle_event/3
    (live_view_todos) lib/live_view_todos_web/live/todo_live.ex:11: LiveViewTodosWeb.TodoLive.handle_event("toggle_done", %{...}, #Phoenix.LiveView.Socket<...>)

If you look at that second line, you'll see that it's trying to call LiveViewTodosWeb.TodoLive.handle_event and pass the parameters "toggle_done", a map of values including one called "id" set to the ID of the task you clicked on, and the socket. Go ahead and implement a handler for this in your live view:

def handle_event("toggle_done", %{"id" => id}, socket) do
  todo = Todos.get_todo!(id)
  Todos.update_todo(todo, %{done: !todo.done})
  {:noreply, fetch(socket)}
end

A few things are happening there. First the live view uses the ID it receives from the phx_value_* attribute and fetches the todo from the database. Then it updates that todo and sets its done property to the opposite of whatever it was before (if it was false, it's now true, and vice versa). Then you'll notice that the process reloads the list of todos from the database and sends them back down to the application. One more thing though: the PubSub subscription should already be telling our socket to fetch all the new todos, so you don't need to do that here. Go ahead and remove the call to fetch from the new event handler. You can do the same with the add event too:

{:noreply, socket}

Now if you try checking (and unchecking) a few boxes, you'll see that they update in real-time, even across multiple browser windows!

What's Next?

Well there you have it! A simple todo list with Phoenix LiveView that didn't take too long to implement. Like I said before, LiveView is awesome, and Phoenix PubSub is pretty amazing too. It was super simple to subscribe to events and
publish those when you update the database, and that allowed you to get this all set up really easily. I would highly recommend spending some time getting more familiar with PubSub because it can be a very powerful tool in your arsenal as you build real-time applications.

If you want to keep going with this project, the next thing I would recommend is adding a delete functionality. The Todos context already has a delete_todo function that you can make use of, so you can probably use what you just did with the checkbox as a template. If you do anything further, please reach out to me on Twitter and let me know what you did. I'd love to see the things you're building as a result of these tutorials.

If you liked this, please retweet it so others can find
it and
subscribe to my YouTube
channel
so you get notified of my next post. I plan to continue releasing new YouTube videos with accompanying blog posts whenever I can make time. Let me know on Twitter or in the comments for the video above if there is anything further you'd like to see me cover. Thanks for reading!