# ElectricSQL: a read-path sync engine that streams Postgres tables over HTTP

> Electric is a Postgres sync engine that replicates data out of your database to clients. It is a read-path tool, not a two-way sync layer, and the installation path runs through Docker Compose and a DATABASE_URL.

**electric-sql/electric** — The agent platform built on sync.

- Repository: https://github.com/electric-sql/electric
- Website: https://electric.ax
- Stars: 10,362 · Forks: 374
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/electric-sql-electric

## The problem Electric targets: getting Postgres rows to lots of clients

Most applications start by having every client query the database through an API. That works until the number of clients grows, the queries overlap, and the same rows get fetched over and over. Electric takes a different position: the database is the source of truth, and a separate process sits in front of it to replicate data outward. The README calls this a "read-path sync engine for Postgres" and says it "syncs data out of Postgres into ... anything you like." The problems it claims to solve are partial replication, fan-out, and data delivery. Partial replication means you do not have to ship the whole database to every consumer; you define what a given client should see. Fan-out means one database change can reach many subscribers without each subscriber polling. Data delivery means the transport is a low-level HTTP API that the README says "integrates with CDNs for highly-scalable data delivery." The intended audience is engineers building applications that need live local data, and the repository description frames the project as "the agent platform built on sync," which suggests AI agents reading current data are a first-class use case. If your application already has a single backend that serves a few hundred users with ordinary request-response queries, Electric is solving a problem you may not have yet.

## Shapes, offsets and the HTTP sync protocol

The mechanism is a shape. A shape is a subset of a table defined by query parameters, and it is the unit of replication. The README points to a dedicated guide for shapes and shows the HTTP form directly: a request to the shape endpoint with a table name and an offset. The offset parameter is how the protocol tracks position in the change stream; the README example uses `offset=-1` to start syncing a table from the beginning. A client that has already consumed part of the stream sends its last known offset and receives subsequent changes rather than a full snapshot. This is the data flow: Postgres logical replication feeds Electric, Electric materializes shapes from that stream, and HTTP responses carry the rows and their offsets to consumers. The README states that partial replication is managed with shapes and that sync can be consumed directly over HTTP or through client libraries and framework integrations. The React integration is the example given, with a `useShape` hook that takes a URL and params. Because the transport is plain HTTP with an OpenAPI spec in `website/electric-api.yaml`, the consumer does not have to be JavaScript. The README notes the core protocol is low-level and HTTP-based, which is why CDN caching is possible at all. The trade-off is that offset management is the client's responsibility if you consume the raw API; the client libraries exist to absorb that bookkeeping.

## Installing Electric with Docker Compose and running a first shape

The README gives two prerequisites before anything runs: a Postgres database with logical replication enabled, and Electric running in front of it connected via `DATABASE_URL`. The quickest path in the repository is the Docker Compose file under `.support`, invoked from the repository root. This starts the stack, including the database configured for the sync service.

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

Once that is up, the README shows how to start syncing a table over the HTTP API. The `offset=-1` value means start from the beginning of the stream for that table.

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

If you prefer to consume the stream from a browser application, the README gives the React integration as the example. The hook takes a shape URL and a params object containing the table and an optional `where` clause.

```jsx
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)
}
```

After the curl call, you should see HTTP response headers and a body describing the shape. The README does not document the exact response schema in the repository text; it points to the OpenAPI spec and the HTTP API docs for that. If you are working on Electric itself rather than consuming it, the development setup uses asdf with versions pinned in `.tool-versions`, and the Mac instructions install Node.js, pnpm, Elixir and Erlang plugins before running `asdf install`.

## Where Electric is the wrong tool: writes, authentication and the dashboard port

The README is explicit that Electric is a read-path engine. It syncs data out of Postgres. It does not describe syncing writes back into Postgres, resolving write conflicts, or reconciling offline edits. If your application needs bidirectional sync with conflict resolution, this project as documented does not provide it, and you would be pairing it with something else or looking at a different class of tool. The repository does contain an `examples/write-patterns/` directory, which suggests write patterns are addressed somewhere in the examples, but the README itself does not describe a write path, so treat that as unverified until you read the example. The second limitation is operational and stated bluntly. Electric includes an optional Phoenix LiveDashboard for monitoring VM metrics, process info and ETS tables, enabled by setting `ELECTRIC_LIVE_DASHBOARD_PORT`. When that variable is not set, the dashboard does not start. When it is set, the README warns in bold that the endpoint is completely unauthenticated and that anyone with network access can view internal system state. It instructs you to restrict the port with firewall rules or network policies in production. That is a real deployment constraint, not a footnote: enabling monitoring opens an unauthenticated surface, and the project leaves the network control to you. There is also a `LIMITATIONS.md` file at the repository root, which is the place to look for the maintained list rather than assuming the README is exhaustive.

## How Electric differs from a general-purpose replication tool

The closest comparison in the sync space is a tool that replicates the entire database to every client and then reconciles writes locally. Electric deliberately does not do that. It replicates shapes, which are query-defined subsets, and it keeps the write path out of scope. That difference matters at scale: full-database replication pushes the same bytes to every consumer, while shape-based partial replication lets different consumers receive different subsets, which is what makes CDN-level fan-out practical. The HTTP API being the core protocol is the second difference. A replication tool that requires a persistent socket connection to a specific server node cannot sit behind a CDN in the same way; Electric's README states the HTTP API "integrates with CDNs for highly-scalable data delivery." The cost of that choice is that the client is responsible for tracking offsets and reconnecting, which is why the client libraries exist. If you need a database that itself handles multi-master conflict resolution, Electric is not that product; it is the delivery layer between Postgres and consumers. The repository's topic list includes CRDTs, and there is an `examples/yjs/` directory plus a published `@electric-sql/y-electric` package, which indicates CRDT-based collaborative editing is an integration pattern rather than the core engine.

## Maintenance, releases and the Apache 2.0 licence

The repository is not archived, and the last push was on 2026-09-09. Recent releases on the same date include `@electric-sql/react@1.0.57`, `@electric-sql/y-electric@0.1.54` and `expo-db-electric-starter@1.0.29`, so the npm packages and the starter templates are versioned together through a changesets workflow defined in the root `package.json`. The README badge links to a 1.0 release announcement from March 2025. The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That is a permissive licence, and for most adopters the practical implication is that you can embed Electric in a commercial product. Apache-2.0 does not impose copyleft obligations on your application code. The repository also carries a Contributor License Agreement and a `CLA.md` file, which affects people contributing to the project rather than people consuming it. For upgrade cost, the monorepo publishes both npm packages and Hex packages (`ci:publish:hex-electric` and `ci:publish:hex-electric-client` in the root scripts), so Elixir and TypeScript consumers upgrade on separate tracks. The README does not document a migration or rollback procedure for shape protocol changes, so pin your client version and read the changesets before upgrading across a minor release.

## Conclusion

Adopt Electric if you need to stream Postgres tables to many clients and are comfortable with a read-path model where writes stay in your own stack. Do not adopt it if you need bidirectional sync or offline write reconciliation, because the README describes only a read-path engine. Before committing, verify that your Postgres instance has logical replication enabled and confirm how your deployment handles the unauthenticated LiveDashboard port.

## FAQ

### What is ElectricSQL and what does it do?

ElectricSQL is a Postgres sync engine that replicates data out of Postgres to clients. The README describes it as a read-path sync engine that handles partial replication, fan-out and data delivery, with shapes used to define which subsets of tables are synced.

### How do I install and run ElectricSQL?

The README requires a Postgres database with logical replication enabled and Electric running in front of it via DATABASE_URL. From the repository root you can start the stack with the Docker Compose file under .support, then query the shape endpoint on port 3000.

### Does ElectricSQL sync writes back into Postgres?

The README describes Electric as a read-path sync engine that syncs data out of Postgres. It does not document a write-back or conflict resolution path, so bidirectional sync is not something the README claims.

### What licence does ElectricSQL use?

The repository licence is Apache-2.0, shown in the README badge and the LICENSE file. The repository also includes a Contributor License Agreement, which applies to contributors rather than to users of the software.

## Sources

- [electric-sql/electric on GitHub](https://github.com/electric-sql/electric)
- [License: Apache-2.0](https://github.com/electric-sql/electric/blob/main/LICENSE)
- [Project website](https://electric.ax)
- [README](https://github.com/electric-sql/electric/blob/main/README.md)
- [Releases](https://github.com/electric-sql/electric/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/electric-sql-electric