electric README

The project's README from github.com/electric-sql/electric. As one markdown file: README.md.

ElectricSQL logo

License - Apache 2.0 Status - Beta Chat - Discord

Electric

Real-time sync for Postgres.

Table of Contents:

What is Electric?

Sync is the magic ingredient behind fast, modern software. From apps like Figma and Linear to AI agents running on live local data.

Electric is a Postgres sync engine. It solves the hard problems of sync for you, including partial replication, fan-out, and data delivery. So you can build awesome software, without rolling your own sync.

Specifically, Electric is a read-path sync engine for Postgres. It syncs data out of Postgres into ... anything you like. The core sync protocol is based on a low-level HTTP API. This integrates with CDNs for highly-scalable data delivery.

Partial replication is managed using Shapes. Sync can be consumed directly or via client libraries and framework integrations.

Getting Started

See the Quickstart guide to get up and running. In short, you need to:

  1. have a Postgres database with logical replication enabled; and then to
  2. run Electric in front of it, connected via DATABASE_URL

For example, using Docker Compose from the root of this repo:

docker compose -f .support/docker-compose.yml up

You can then use the HTTP API to sync data from your Postgres. For example, to start syncing the whole foo table:

curl -i 'http://localhost:3000/v1/shape?table=foo&offset=-1'

Or use one of the clients or integrations, such as the useShape React hook:

import { useShape } from '@electric-sql/react'

function Component() {
  const { data } = useShape({
    url: `http://localhost:3000/v1/shape`,
    params: {
      table: `foo`,
      where: `title LIKE 'foo%'`,
    },
  })

  return JSON.stringify(data)
}

Again, see the Quickstart and the Docs for more details.

HTTP API Docs

The HTTP API is defined in an OpenAPI spec in website/electric-api.yaml.

Phoenix LiveDashboard

Electric includes an optional Phoenix LiveDashboard for real-time monitoring of the running system (VM metrics, process info, ETS tables, etc.).

To enable it, set the ELECTRIC_LIVE_DASHBOARD_PORT environment variable:

ELECTRIC_LIVE_DASHBOARD_PORT=4000

The dashboard will be available at http://localhost:4000 (or whichever port you choose). When the variable is not set, the dashboard is not started.

WARNING: The LiveDashboard endpoint is completely unauthenticated. Anyone with network access to the port can view internal system state. In production, you must restrict access to this port using firewall rules, network policies, or similar controls. Do not expose it to the public internet.

Developing Electric

We use asdf to install Elixir, Erlang, and Node.js. Versions are defined in .tool-versions.

Mac setup

brew install asdf
asdf plugin add nodejs
asdf plugin add pnpm
asdf plugin add elixir
asdf plugin add erlang
asdf install

You'll probably need to fiddle with your bash/zsh/etc rc file to load the right tool into your environment.

Running Tests

Electric has comprehensive test suites for both Elixir and TypeScript components.

Prerequisites

Install dependencies (if not already done):

asdf install
pnpm install

Then start the test Postgres database:

cd packages/sync-service
mix start_dev

This starts a Docker Compose setup with Postgres configured for logical replication on port 54321.

To stop the database:

mix stop_dev

Elixir Tests

Sync Service:

cd packages/sync-service
mix test

For coverage reports:

mix coveralls.html

Elixir Client:

cd packages/elixir-client
mix test

TypeScript Tests

TypeScript tests require both the database and a running sync service.

In a separate terminal, start the sync service:

cd packages/sync-service
iex -S mix

Then run the tests:

Individual Package:

cd packages/typescript-client  # or any other TS package
pnpm test

All TypeScript Packages:

From the root directory:

pnpm -r test

For coverage:

pnpm coverage

Contributing

See the:

Support

We have an open community Discord. Come and say hello and let us know if you have any questions or need any help getting things running.

It's also super helpful if you leave the project a star here at the top of the page☝️

electric (electric-sql/electric)

Searching Database…

10.4K ·GitHub
Electric
Что это такое?Electric — это движок синхронизации в реальном времени для Postgres: он реплицирует данные из вашей базы куда угодно — в веб-приложения, мобильные клиенты, ИИ-агенты — беря на себя сложные задачи вроде частичной репликации, рассылки на множество подписчиков и доставки данных.
Это библиотека, которую я добавляю в приложение, или то, что я разворачиваю?Это отдельный сервер, который вы запускаете перед своим Postgres, а не зависимость в коде. Electric — это движок синхронизации на стороне чтения; ваши приложения просто потребляют данные, которые из него выходят.
Как его запустить?Укажите ему через DATABASE_URL базу Postgres с включённой логической репликацией и запустите Electric перед ней — в репозитории есть готовая конфигурация Docker Compose. Затем вызовите HTTP API, чтобы начать синхронизацию, например целой таблицы.
Что мне нужно, кроме самого Postgres?Только Postgres с логической репликацией; в quickstart Electric поднимается через Docker Compose. Для разработки самого Electric нужны Elixir, Erlang и Node.js, установленные через asdf.
Есть ли подводные камни перед запуском в продакшене?Необязательный эндпоинт мониторинга Phoenix LiveDashboard полностью без аутентификации: любой, кто может достучаться до порта, видит внутреннее состояние системы. Ограничьте доступ правилами файрвола и никогда не открывайте его наружу.
Так это для фронтендов приложений, ИИ-агентов или для того и другого?Для того и другого — командам, которые строят быстрые современные приложения вроде Figma или Linear, и ИИ-агентам, которым нужно работать на живых локальных данных, а не опрашивать базу вручную.
Что такое Shape?Единица частичной репликации: вы просите Electric синхронизировать определённый срез Postgres — например, целую таблицу — и он сам занимается доставкой этих данных клиентам.
Как данные на самом деле попадают в моё приложение?Через низкоуровневый протокол синхронизации поверх HTTP, спроектированный для интеграции с CDN и масштабируемой доставки, либо через клиентские библиотеки и интеграции с фреймворками, например React-хук useShape.
Где задокументирован API синхронизации?В OpenAPI-спеке, которая лежит в репозитории по пути website/electric-api.yaml.
What are similar projects?rxdb, rankme.fast, postgrest, parse-server, kafgres, instant, walshadow, goshen-email
Which topics is it in?platform, crdt, elixir, replication, cdn, data, postgres, sync, scalability, openapi, runtime, http
Creator
electric-sql
Size
261.5 MB
Stars
10.4K
Updated
CommitOct 06Release@electric-sql/[email protected]Sep 09
Age
4y
Commits · 90 Days