---
url: /sync/postgres-sync.md
description: >-
  Read-path sync engine for Postgres that handles partial replication, data
  delivery and fan-out.
---

# Postgres Sync

Read-path sync engine for Postgres that handles partial replication,

data delivery and

fan-out.

## Postgres sync engine

Postgres Sync is a sync engine that syncs [subsets of your data](/docs/sync/guides/shapes) out of your Postgres database, into local apps and services.

You can sync data into anything you like. From web, mobile and desktop apps and client stores like [TanStack DB](/sync/tanstack-db) to databases like [PGlite](/sync/pglite).

> \[!Warning] 🎓  A quick note on naming
> Postgres Sync used to just be called "Electric" or the "Electric sync engine". Some docs and package names still use the old naming.

## How does it work?

Postgres Sync connects to your Postgres using a [`DATABASE_URL`](/docs/sync/api/config#database-url), consumes the logical replication stream and fans out data into [Shapes](/docs/sync/guides/shapes), which [Clients](/docs/sync/api/clients/typescript) then consume and sync.

Technically, Postgres Sync is an [Elixir](https://elixir-lang.org) application, developed at [packages/sync-service](https://github.com/electric-sql/electric/tree/main/packages/sync-service). It runs as a seperate service, [between your API and your database](/docs/sync/guides/deployment). Clients consume data over an [HTTP API](/docs/sync/api/http) that [works with CDNs](/docs/sync/api/http#caching) to scale data delivery and fan-out.

The same shape log is delivered to every subscriber — web tabs, mobile devices, server workers, agents — in real time, with the same ordering and guarantees. This allows you to have [millions of concurrent users](/docs/sync/reference/benchmarks) subscribing to real-time updates to your database with minimal additional load on your database.

## Define a Shape — sync just what you need

A **Shape** is a SQL query against your Postgres. Postgres Sync carves out the matching rows and keeps them live for every client that subscribes.

See the [Shapes guide](/docs/sync/guides/shapes) for the full shape definition syntax, including `where` clauses, `columns` projection, and progressive loading.

## Query-driven sync

Your shape defines the **outer bounds** — the slice of Postgres a user is allowed to see. Live queries running on the client narrow that slice further, syncing only the rows actually needed for the current view.

[TanStack DB](/sync/tanstack-db) has this built in. Pick the sync mode that fits the work: **eager** to preload everything for instant interactions, **on-demand** to fetch only what the current query needs, or **progressive** to start fast and fill in the rest in the background.

See the [Live queries guide](https://tanstack.com/db/latest/docs/guides/live-queries) for the full TanStack DB sync-mode reference.

## Bring your own writes

Postgres Sync handles the read path. Writes go through your existing backend — pick how much sync you want on top.

1. **Write through your API** (Plain API). POST or PUT to your existing endpoints. The Postgres txid flows back through the read path. [Learn more](/docs/sync/guides/writes#through-the-db)
2. **Shared write path** (API + clients). Many clients hit the same backend. Sync delivers the same change to every reader. [Learn more](/docs/sync/guides/writes#shared-write-path)
3. **Optimistic mutations** (+ TanStack DB). UI updates instantly. The collection awaits the txid on the stream and reconciles. [Learn more](/sync/tanstack-db)

See the [Writes guide](/docs/sync/guides/writes) for the four write patterns and how to pair them with optimistic mutations in TanStack DB.

## Related posts

- [Electric 1.1: new storage engine with 100x faster writes](/blog/2025/08/13/electricsql-v1.1-released)
- [Bringing agents back down to earth](/blog/2025/08/12/bringing-agents-back-down-to-earth)
- [120 days of hardening – the post‑1.0 reliability sprint](/blog/2025/08/04/reliability-sprint)
- [Super-fast apps on sync with Electric and TanStack DB](/blog/2025/07/29/super-fast-apps-on-sync-with-tanstack-db)

## More information

See the [Quickstart](/docs/sync/quickstart), the [Stacks](/docs/sync/stacks) overview, and the [HTTP API reference](/docs/sync/api/http). The full source is on GitHub at [electric-sql/electric](https://github.com/electric-sql/electric).