An Elixir client for ElectricSQL.

Electric is a sync engine that allows you to sync little subsets of data from Postgres into local apps and services. This client allows you to sync data from Electric into Elixir applications.

Quickstart

Start and connect the Electric sync service

Follow the Installation guide to get Electric up-and-running and connected to a Postgres database.

Create a table

Create a foo table in your Postgres schema, as per the Electric Quickstart guide, so that we have a table to sync.

CREATE TABLE foo (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255),
    value FLOAT
);

Install the Electric Client and receive sync events

Create a simple script that will subscribe to events from a foo table in your Postgres database,

# electric.ex
Mix.install([
  :electric_client
])

{:ok, client} = Electric.Client.new(base_url: "http://localhost:3000")

# You can create a stream from a table name or a Shape defined using
# `ShapeDefinition.new/2`
stream = Electric.Client.stream(client, "foo")

for msg <- stream do
  IO.inspect(msg, pretty: true, syntax_colors: IO.ANSI.syntax_colors())
end

Then run it:

elixir electric.ex

In a separate terminal window, connect to the Postgres database:

psql "postgresql://postgres:password@localhost:54321/electric"

Now any modifications you make to the data in the foo table will appear as messages in the elixir process.

INSERT INTO foo (name, value) VALUES
    ('josevalim', 4545),
    ('eksperimental', 966),
    ('lexmag', 677),
    ('whatyouhide', 598),
    ('ericmj', 583),
    ('alco', 377);

UPDATE foo SET value = value + 1;

Filtering Using WHERE clauses

You can subscribe to subsets of the data in your table using where clauses.

{:ok, client} = Electric.Client.new(base_url: "http://localhost:3000")

{:ok, shape} = Electric.Client.ShapeDefinition.new("foo", where: "name ILIKE 'a%'")

stream = Electric.Client.stream(client, shape)

for msg <- stream do
  # you will now only receive events for database rows matching the `where` clause
end

Configuration

See new/1 for configuration options of the client itself, and stream/3 for details on configuring the stream itself.

Ecto Integration

If you have Ecto installed then you can define your Shapes using Ecto queries:

# ecto.ex
Mix.install([
  :ecto_sql,
  :electric_client
])

import Ecto.Query, only: [from: 2]
import Ecto.Query.API, only: [ilike: 2]

defmodule Foo do
  use Ecto.Schema

  schema "foo" do
    field :name, :string
    field :value, :float
  end
end

{:ok, client} = Electric.Client.new(base_url: "http://localhost:3000")

# Replace the table or `ShapeDefinition` with an `Ecto` query and set
# `replica` to `:full` to receive full rows for update messages.
#
# The normal `replica: :default` setting will only send the changed
# columns, so we'd end up with partial `%Foo{}` instances.
stream =
  Electric.Client.stream(
    client,
    from(f in Foo, where: ilike(f.name, "a%")),
    replica: :full
  )

for %{headers: %{operation: operation}, value: value} <- stream do
  # The message `value` will now be a `%Foo{}` struct
  IO.inspect([{operation, value}], pretty: true, syntax_colors: IO.ANSI.syntax_colors())
end

Custom Values

Electric sends all column values as binaries. The Ecto integration uses Ecto's schema information to turn those into the relevant Elixir terms but we can provide our own binary() => term() mapping by implementing the Electric.Client.ValueMapper behaviour.