Phoenix
Phoenix is a full-stack web development framework for Elixir.
Electric and Phoenix
Electric is developed in Elixir and provides an Elixir client. We've leveraged this to develop a batteries-included Phoenix integration for:
- front-end sync: into a front-end client from a Postgres-backed Phoenix application
- LiveView sync: into Phoenix LiveView from Postgres in realtime via Phoenix.Streams
Electric.Phoenix
is published on Hex as hex.pm/packages/electric_phoenix.
Inspiration
It was inspired by josevalim/sync
. You can read José's original design document.
How to use
Front-end sync
Phoenix is a general framework that provides a number of different methods to get data from the server to the client. These include exposing REST APIs and using Absinthe to expose a GraphQL endpoint.
Electric.Phoenix
provides an alternative method: exposing Shapes that sync data directly from Postgres into the client. With this, shapes are exposed and configured in your Phoenix Router. For example, here we expose a predefined shape of all visible todos, deriving the shape definition from an Ecto query using your existing data model:
defmodule MyAppWeb.Router do
use Phoenix.Router
alias MyApp.Todos.Todo
scope "/shapes" do
pipe_through :browser
get "/todos", Electric.Phoenix.Plug,
shape: Electric.Client.shape!(Todo, where: "visible = true")
end
end
Because the shape is defined in your Router, it can use Plug middleware for authorization. See Parameter-based shapes for more details.
LiveView sync
Phoenix LiveView allows you to develop interactive web applications in Elixir/Phoenix, often without writing any front-end code.
LiveView provides a primitive, called Phoenix.Streams that allows you to stream data into a LiveView. Electric.Phoenix
provides a wrapper around this to automatically stream a Shape into a LiveView.
The key primitive is an electric_stream/4
function that wraps Phoenix.LiveView.stream/4
to provide a live updating collection of items.
def mount(_params, _session, socket) do
socket =
Electric.Phoenix.LiveView.electric_stream(
socket,
:visible_todos,
from(t in Todo, where: t.visible == true)
)
{:ok, socket}
end
This makes your LiveView applications real-time. In fact, it allows you to build interactive, real-time multi-user applications straight out of your existing Ecto schema, without writing any JavaScript at all 🤯
More details
For more details and full documentation see hexdocs.pm/electric_phoenix.
Examples
Phoenix LiveView
See the phoenix-liveview example on GitHub.
This is an example Phoenix LiveView application that uses Electric.Phoenix.LiveView.electric_stream/4
to sync data from Postgres into a LiveView using Phoenix Streams. This keeps the LiveView automatically in-sync with Postgres, without having to re-run queries or trigger any change handling yourself.
See the documentation for more details.
Gatekeeper Auth
The gatekeeper-auth example also contains a Phoenix application that uses Electric.Phoenix.Plug
to authorize shape access and issue shape-scoped access tokens.
Help wanted Good first issue
We have an open GitHub issue tracking this if you'd like to contribute an equivalent integration for other server-side frameworks, such as Rails, Laravel, Django, etc.
Please leave a comment or ask on Discord if you'd like any pointers or to discuss how best to approach this.