{"id":26340976,"url":"https://github.com/electric-sql/phoenix_sync","last_synced_at":"2025-03-16T04:21:58.622Z","repository":{"id":280859373,"uuid":"938863928","full_name":"electric-sql/phoenix_sync","owner":"electric-sql","description":"Real-time sync for Postgres-backed Phoenix applications.","archived":false,"fork":false,"pushed_at":"2025-03-12T15:08:51.000Z","size":215,"stargazers_count":39,"open_issues_count":6,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-13T02:09:28.256Z","etag":null,"topics":["electric-sql","elixir","elixir-phoenix","phoenix","phoenix-framework","real-time","sync"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/phoenix_sync","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/electric-sql.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-25T16:12:58.000Z","updated_at":"2025-03-12T20:05:28.000Z","dependencies_parsed_at":"2025-03-05T18:30:09.001Z","dependency_job_id":null,"html_url":"https://github.com/electric-sql/phoenix_sync","commit_stats":null,"previous_names":["electric-sql/phoenix_sync"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electric-sql%2Fphoenix_sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electric-sql%2Fphoenix_sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electric-sql%2Fphoenix_sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electric-sql%2Fphoenix_sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/electric-sql","download_url":"https://codeload.github.com/electric-sql/phoenix_sync/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243510057,"owners_count":20302296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electric-sql","elixir","elixir-phoenix","phoenix","phoenix-framework","real-time","sync"],"created_at":"2025-03-16T04:21:57.966Z","updated_at":"2025-03-16T04:21:58.591Z","avatar_url":"https://github.com/electric-sql.png","language":"Elixir","funding_links":[],"categories":["Elixir"],"sub_categories":[],"readme":"# Phoenix.Sync\n\n\u003cp\u003e\n  \u003cbr /\u003e\n  \u003ca href=\"https://hexdocs.pm/phoenix_sync\" target=\"_blank\"\u003e\n    \u003cpicture\u003e\n      \u003cimg alt=\"Phoenix sync illustration\"\n          src=\"https://github.com/electric-sql/phoenix_sync/raw/main/docs/phoenix-sync.png\"\n      /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n\u003c/p\u003e\n\n[![Hex.pm](https://img.shields.io/hexpm/v/phoenix_sync.svg)](https://hex.pm/packages/phoenix_sync)\n[![Documentation](https://img.shields.io/badge/docs-hexdocs-green)](https://hexdocs.pm/phoenix_sync)\n[![License](https://img.shields.io/badge/license-Apache_2.0-green)](./LICENSE)\n[![Status](https://img.shields.io/badge/status-beta-orange)](https://github.com/electric-sql/phoenix_sync)\n[![Discord](https://img.shields.io/discord/933657521581858818?color=5969EA\u0026label=discord)](https://discord.electric-sql.com)\n\nSync is the best way of building modern apps. Phoenix.Sync enables real-time sync for Postgres-backed [Phoenix](https://www.phoenixframework.org/) applications.\n\nDocumentation is available at [hexdocs.pm/phoenix_sync](https://hexdocs.pm/phoenix_sync).\n\n## Build real-time apps on locally synced data\n\n- sync data into Elixir, `LiveView` and frontend web and mobile applications\n- integrates with `Plug` and `Phoenix.{Controller, LiveView, Router, Stream}`\n- uses [ElectricSQL](https://electric-sql.com) for scalable data delivery and fan out\n- maps `Ecto` queries to [Shapes](https://electric-sql.com/docs/guides/shapes) for partial replication\n\n## Usage\n\nThere are four key APIs:\n\n- [`Phoenix.Sync.Client.stream/2`](https://hexdocs.pm/phoenix_sync/Phoenix.Sync.Client.html#stream/2) for low level usage in Elixir\n- [`Phoenix.Sync.LiveView.sync_stream/4`](https://hexdocs.pm/phoenix_sync/Phoenix.Sync.LiveView.html#sync_stream/4) to sync into a LiveView stream\n- [`Phoenix.Sync.Router.sync/2`](https://hexdocs.pm/phoenix_sync/Phoenix.Sync.Router.html#sync/2) macro to expose a statically defined shape in your Router\n- [`Phoenix.Sync.Controller.sync_render/3`](https://hexdocs.pm/phoenix_sync/Phoenix.Sync.Controller.html#sync_render/3) to expose dynamically constructed shapes from a Controller\n\n### Low level usage in Elixir\n\nUse [`Phoenix.Sync.Client.stream/2`](https://hexdocs.pm/phoenix_sync/Phoenix.Sync.Client.html#stream/2) to convert an `Ecto.Query` into an Elixir `Stream`:\n\n```elixir\nstream = Phoenix.Sync.Client.stream(Todos.Todo)\n\nstream =\n  Ecto.Query.from(t in Todos.Todo, where: t.completed == false)\n  |\u003e Phoenix.Sync.Client.stream()\n```\n\n### Sync into a LiveView stream\n\nSwap out `Phoenix.LiveView.stream/3` for [`Phoenix.Sync.LiveView.sync_stream/4`](https://hexdocs.pm/phoenix_sync/Phoenix.Sync.LiveView.html#sync_stream/4) to automatically keep a LiveView up-to-date with the state of your Postgres database:\n\n```elixir\ndefmodule MyWeb.MyLive do\n  use Phoenix.LiveView\n  import Phoenix.Sync.LiveView\n\n  def mount(_params, _session, socket) do\n    {:ok, sync_stream(socket, :todos, Todos.Todo)}\n  end\n\n  def handle_info({:sync, event}, socket) do\n    {:noreply, sync_stream_update(socket, event)}\n  end\nend\n```\n\nLiveView takes care of automatically keeping the front-end up-to-date with the assigned stream. What Phoenix.Sync does is automatically keep the _stream_ up-to-date with the state of the database.\n\nThis means you can build fully end-to-end real-time multi-user applications without writing Javascript _and_ without worrying about message delivery, reconnections, cache invalidation or polling the database for changes.\n\n### Sync shapes through your Router\n\nUse the [`Phoenix.Sync.Router.sync/2`](https://hexdocs.pm/phoenix_sync/Phoenix.Sync.Router.html#sync/2) macro to expose statically (compile-time) defined shapes in your Router:\n\n```elixir\ndefmodule MyWeb.Router do\n  use Phoenix.Router\n  import Phoenix.Sync.Router\n\n  pipeline :sync do\n    plug :my_auth\n  end\n\n  scope \"/shapes\" do\n    pipe_through :sync\n\n    sync \"/todos\", Todos.Todo\n  end\nend\n```\n\nBecause the shapes are exposed through your Router, the client connects through your existing Plug middleware. This allows you to do real-time sync straight out of Postgres _without_ having to translate your auth logic into complex/fragile database rules.\n\n### Sync dynamic shapes from a Controller\n\nSync shapes from any standard Controller using the [`Phoenix.Sync.Controller.sync_render/3`](https://hexdocs.pm/phoenix_sync/Phoenix.Sync.Controller.html#sync_render/3) view function:\n\n```elixir\ndefmodule Phoenix.Sync.LiveViewTest.TodoController do\n  use Phoenix.Controller\n  import Phoenix.Sync.Controller\n  import Ecto.Query, only: [from: 2]\n\n  def show(conn, %{\"done\" =\u003e done} = params) do\n    sync_render(conn, params, from(t in Todos.Todo, where: t.done == ^done))\n  end\n\n  def show_mine(%{assigns: %{current_user: user_id}} = conn, params) do\n    sync_render(conn, params, from(t in Todos.Todo, where: t.owner_id == ^user_id))\n  end\nend\n```\n\nThis allows you to define and personalise the shape definition at runtime using the session and request.\n\n### Consume shapes in the frontend\n\nYou can sync _into_ any client in any language that [speaks HTTP and JSON](https://electric-sql.com/docs/api/http).\n\nFor example, using the Electric [Typescript client](https://electric-sql.com/docs/api/clients/typescript):\n\n```typescript\nimport { Shape, ShapeStream } from \"@electric-sql/client\";\n\nconst stream = new ShapeStream({\n  url: `/shapes/todos`,\n});\nconst shape = new Shape(stream);\n\n// The callback runs every time the data changes.\nshape.subscribe((data) =\u003e console.log(data));\n```\n\nOr binding a shape to a component using the [React bindings](https://electric-sql.com/docs/integrations/react):\n\n```tsx\nimport { useShape } from \"@electric-sql/react\";\n\nconst MyComponent = () =\u003e {\n  const { data } = useShape({\n    url: `shapes/todos`,\n  });\n\n  return \u003cList todos={data} /\u003e;\n};\n```\n\nSee the Electric [demos](https://electric-sql.com/demos) and [documentation](https://electric-sql.com/demos) for more client-side usage examples.\n\n## Installation and configuration\n\n`Phoenix.Sync` can be used in two modes:\n\n1. `:embedded` where Electric is included as an application dependency and Phoenix.Sync consumes data internally using Elixir APIs\n2. `:http` where Electric does _not_ need to be included as an application dependency and Phoenix.Sync consumes data from an external Electric service using it's [HTTP API](https://electric-sql.com/docs/api/http)\n\n### Embedded mode\n\nIn `:embedded` mode, Electric must be included an application dependency but does not expose an HTTP API (internally or externally). Messages are streamed internally between Electric and Phoenix.Sync using Elixir function APIs. The only HTTP API for sync is that exposed via your Phoenix Router using the `sync/2` macro and `sync_render/3` function.\n\nExample config:\n\n```elixir\n# mix.exs\ndefp deps do\n  [\n    {:electric, \"\u003e= 1.0.0-beta.20\"},\n    {:phoenix_sync, \"~\u003e 0.3\"}\n  ]\nend\n\n# config/config.exs\nconfig :phoenix_sync,\n  env: config_env(),\n  mode: :embedded,\n  repo: MyApp.Repo\n\n# application.ex\nchildren = [\n  MyApp.Repo,\n  # ...\n  {MyApp.Endpoint, phoenix_sync: Phoenix.Sync.plug_opts()}\n]\n```\n\n### HTTP\n\nIn `:http` mode, Electric does not need to be included as an application dependency. Instead, Phoenix.Sync consumes data from an external Electric service over HTTP.\n\n```elixir\n# mix.exs\ndefp deps do\n  [\n    {:phoenix_sync, \"~\u003e 0.3\"}\n  ]\nend\n\n# config/config.exs\nconfig :phoenix_sync,\n  env: config_env(),\n  mode: :http,\n  url: \"https://api.electric-sql.cloud\",\n  credentials: [\n    secret: \"...\",    # required\n    source_id: \"...\"  # optional, required for Electric Cloud\n  ]\n\n# application.ex\nchildren = [\n  MyApp.Repo,\n  # ...\n  {MyApp.Endpoint, phoenix_sync: Phoenix.Sync.plug_opts()}\n]\n```\n\n### Local HTTP services\n\nIt is also possible to include Electric as an application dependency and configure it to expose a local HTTP API that's consumed by Phoenix.Sync running in `:http` mode:\n\n```elixir\n# mix.exs\ndefp deps do\n  [\n    {:electric, \"\u003e= 1.0.0-beta.20\"},\n    {:phoenix_sync, \"~\u003e 0.3\"}\n  ]\nend\n\n# config/config.exs\nconfig :phoenix_sync,\n  env: config_env(),\n  mode: :http,\n  http: [\n    port: 3000,\n  ],\n  repo: MyApp.Repo,\n  url: \"http://localhost:3000\"\n\n# application.ex\nchildren = [\n  MyApp.Repo,\n  # ...\n  {MyApp.Endpoint, phoenix_sync: Phoenix.Sync.plug_opts()}\n]\n```\n\nThis is less efficient than running in `:embedded` mode but may be useful for testing or when needing to run an HTTP proxy in front of Electric as part of your development stack.\n\n### Different modes for different envs\n\nApps using `:http` mode in certain environments can exclude `:electric` as a dependency for that environment. The following example shows how to configure:\n\n- `:embedded` mode in `:dev`\n- `:http` mode with a local Electric service in `:test`\n- `:http` mode with an external Electric service in `:prod`\n\nWith Electric only included and compiled as a dependency in `:dev` and `:test`.\n\n```elixir\n# mix.exs\ndefp deps do\n  [\n    {:electric, \"~\u003e 1.0.0-beta.20\", only: [:dev, :test]},\n    {:phoenix_sync, \"~\u003e 0.3\"}\n  ]\nend\n\n# config/dev.exs\nconfig :phoenix_sync,\n  env: config_env(),\n  mode: :embedded,\n  repo: MyApp.Repo\n\n# config/test.esx\nconfig :phoenix_sync,\n  env: config_env(),\n  mode: :http,\n  http: [\n    port: 3000,\n  ],\n  repo: MyApp.Repo,\n  url: \"http://localhost:3000\"\n\n# config/prod.exs\nconfig :phoenix_sync,\n  mode: :http,\n  url: \"https://api.electric-sql.cloud\",\n  credentials: [\n    secret: \"...\",    # required\n    source_id: \"...\"  # optional, required for Electric Cloud\n  ]\n\n# application.ex\nchildren = [\n  MyApp.Repo,\n  # ...\n  {MyApp.Endpoint, phoenix_sync: Phoenix.Sync.plug_opts()}\n]\n```\n\n## Notes\n\n### ElectricSQL\n\nElectricSQL is a [real-time sync engine for Postgres](https://electric-sql.com).\n\nPhoenix.Sync uses Electric to handle the core concerns of partial replication, fan out and data delivery.\n\n### Partial replication\n\nElectric defines partial replication using [Shapes](https://electric-sql.com/docs/guides/shapes).\n\n### Shape definitions\n\nPhoenix.Sync allows shapes to be defined in two ways:\n\n1. using an `Ecto.Query` (or `Ecto.Schema` module)\n2. using a keyword list\n\n### Using an `Ecto.Query`\n\nPhoenix.Sync maps Ecto queries to shape definitions. This allows you to control what data syncs where using Ecto.Schema and Ecto.Query.\n\nFor example, using a query:\n\n```elixir\nsync_render(conn, params, from(t in Todos.Todo, where: t.completed == false))\n```\n\nOr using a schema (equivalent to `from(t in Todos.Todo)`):\n\n```elixir\nsync_render(conn, params, Todos.Todo)\n```\n\nQuery support is currently limited to `where` conditions. Support for more complex queries using `join`, `order_by`, `limit` and preloaded association graphs is planned and will be added in Q2 2025.\n\nThe static shapes defined using the `sync/2` or `sync/3` router macros do not accept `Ecto.Query` structs as a shape definition. This is to avoid excessive recompilation caused by your router having a compile-time dependency on your `Ecto` schemas.\n\nIf you want to add a where-clause filter to a static shape in your router, you can add an explicit [`where` clause](https://electric-sql.com/docs/guides/shapes#where-clause) alongside your `Ecto.Schema` module:\n\n```elixir\n\nsync \"/incomplete-todos\", Todos.Todo, where: \"completed = false\"\n```\n\nYou can also include `replica` (see below) in your static shape definitions:\n\n```elixir\n\nsync \"/incomplete-todos\", Todos.Todo, where: \"completed = false\", replica: :full\n```\n\nFor anything else more dyanamic, or to use Ecto queries, you should switch from using the `sync` macros in your router to using `sync_render/3` in a controller.\n\n### Using a keyword list\n\nAt minimum a shape requires a `table`. You can think of shapes defined with\njust a table name as the sync-equivalent of `SELECT * FROM table`.\n\nThe available options are:\n\n- `table` (required). The Postgres table name. Be aware of casing and [Postgres's handling of unquoted upper-case names](https://wiki.postgresql.org/wiki/Don%27t_Do_This#Don.27t_use_upper_case_table_or_column_names).\n- `namespace` (optional). The Postgres namespace that the table belongs to. Defaults to `public`.\n- `where` (optional). Filter to apply to the synced data in SQL format, e.g. `where: \"amount \u003c 1.23 AND colour in ('red', 'green')\"`.\n- `columns` (optional). The columns to include in the synced data. By default Electric will include all columns in the table. The column list **must** include all primary keys. E.g. `columns: [\"id\", \"title\", \"amount\"]`.\n- `replica` (optional). By default Electric will only send primary keys + changed columns on updates. Set `replica: :full` to receive the full row, not just the changed columns.\n\nSee the [Electric Shapes guide](https://electric-sql.com/docs/guides/shapes) for more information.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectric-sql%2Fphoenix_sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felectric-sql%2Fphoenix_sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectric-sql%2Fphoenix_sync/lists"}