electric-client: tweak the README and module docs. (#1943)

electric-sql · Nov 6, 2024 · a019025 · a019025
1 parent 31f2309
commit a019025
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 56 deletions.
diff --git a/packages/elixir-client/README.md b/packages/elixir-client/README.md
@@ -1,34 +1,12 @@
-<p align="center">
-  <a href="https://electric-sql.com" target="_blank">
-    <picture>
-      <source media="(prefers-color-scheme: dark)"
-          srcset="https://raw.githubusercontent.com/electric-sql/meta/main/identity/ElectricSQL-logo-next.svg"
-      />
-      <source media="(prefers-color-scheme: light)"
-          srcset="https://raw.githubusercontent.com/electric-sql/meta/main/identity/ElectricSQL-logo-black.svg"
-      />
-      <img alt="ElectricSQL logo"
-          src="https://raw.githubusercontent.com/electric-sql/meta/main/identity/ElectricSQL-logo-black.svg"
-      />
-    </picture>
-  </a>
-</p>
 
-<p align="center">
-  <a href="https://github.com/electric-sql/electric/actions"><img src="https://github.com/electric-sql/electric/actions/workflows/elixir_client_tests.yml/badge.svg"></a>
-  <a href="https://github.com/electric-sql/electric/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-green" alt="License - Apache 2.0"></a>
-  <a href="https://github.com/electric-sql/electric/milestones"><img src="https://img.shields.io/badge/status-alpha-orange" alt="Status - Alpha"></a>
-  <a href="https://discord.electric-sql.com"><img src="https://img.shields.io/discord/933657521581858818?color=5969EA&label=discord" alt="Chat - Discord"></a>
-  <a href="https://x.com/ElectricSQL" target="_blank"><img src="https://img.shields.io/twitter/follow/ElectricSQL.svg?style=social&label=Follow @ElectricSQL"></a>
-</p>
+# ElectricSQL Elixir client
 
-# Elixir client for ElectricSQL
+An Elixir client for [ElectricSQL](https://electric-sql.com).
 
-Real-time Postgres sync for modern apps.
-
-Electric provides an [HTTP interface](https://electric-sql.com/docs/api/http) to Postgres to enable a massive number of clients to query and get real-time updates to subsets of the database, called [Shapes](https://electric-sql.com//docs/guides/shapes). In this way, Electric turns Postgres into a real-time database.
-
-The Elixir client helps ease reading Shapes from the HTTP API in Elixir applications.
+Electric is a sync engine that allows you to sync
+[little subsets](https://electric-sql.com/docs/guides/shapes)
+of data from Postgres into local apps and services. This client
+allows you to sync data from Electric into Elixir applications.
 
 ## Installation
 
@@ -42,25 +20,11 @@ end
 
 ## Usage
 
-```elixir
-{:ok, client} = Electric.Client.new(base_url: "http://localhost:3000")
-
-incomplete_todos = Electric.Client.shape("todos", where: "completed = false")
-
-# Passing `live: false` means the stream will terminate once it's reached
-# the head of the update log from Electric.
-#
-# Without `live: false` the stream is infinite.
-stream = Electric.Client.stream(client, incomplete_todos, live: false)
-
-messages = Enum.into(stream, [])
-```
-
 See the [Documentation](https://hexdocs.pm/electric_client).
 
 ## Testing
 
-[Run Electric](https://github.com/electric-sql/electric/blob/main/packages/sync-service/README.md) and Postgres.
+[Run Electric and Postgres](https://electric-sql.com/docs/guides/installation).
 
 Define `DATABASE_URL` and `ELECTRIC_URL` as env vars. Or see the defaults in `config/runtime.exs`.
 

diff --git a/packages/elixir-client/lib/electric/client.ex b/packages/elixir-client/lib/electric/client.ex
@@ -1,29 +1,44 @@
 defmodule Electric.Client do
   @moduledoc """
-  An Elixir client for the [ElectricSQL synchronisation server](https://electric-sql.com/).
+  An Elixir client for [ElectricSQL](https://electric-sql.com).
 
-  Subscribing to a particular
-  [Shape](https://electric-sql.com/docs/guides/shapes) produce a stream of
-  update messages that will allow you to synchronise your local system to the
-  state the Postgres database.
+  Electric is a sync engine that allows you to sync
+  [little subsets](https://electric-sql.com/docs/guides/shapes)
+  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
+  ### Start and connect the Electric sync service
 
-  Follow the [quickstart guide](https://electric-sql.com/docs/quickstart) to
-  get Electric running and connected to a Postgres database.
+  Follow the
+  [Installation guide](https://electric-sql.com/docs/guides/installation)
+  to get Electric up-and-running and connected to a Postgres database.
 
-  ### Install the Electric Client and Receive sync events
+  ### Create a table
 
-  Create a simple script that will subscribe to events from the `foo` table you created as part of the [Quickstart](#quickstart).
+  Create a `foo` table in your Postgres schema, as per the Electric
+  [Quickstart guide](https://electric-sql.com/docs/guides/installation),
+  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")
@@ -55,8 +70,8 @@ defmodule Electric.Client do
 
   ### Filtering Using WHERE clauses
 
-  You can subscribe to subsets of the data in your table using [`where` clauses](https://electric-sql.com/docs/guides/shapes#where-clause).
-
+  You can subscribe to subsets of the data in your table using
+  [`where` clauses](https://electric-sql.com/docs/guides/shapes#where-clause).
 
       {:ok, client} = Electric.Client.new(base_url: "http://localhost:3000")
 
@@ -75,7 +90,8 @@ defmodule Electric.Client do
 
   ## Ecto Integration
 
-  If you have [Ecto](https://hexdocs.pm/ecto) installed then you can define you Shapes using Ecto queries:
+  If you have [Ecto](https://hexdocs.pm/ecto) installed then you can define your Shapes
+  using Ecto queries:
 
       # ecto.ex
       Mix.install([