What Is ZeBridge? The Beginner's Guide to Offline-First PostgreSQL Replicas on Devices

CodexFuse Team · 2026-11-05T21:30:37.144Z · 26 min read min read

What Is ZeBridge? The Beginner's Guide to Offline-First PostgreSQL Replicas on Devices

What Is ZeBridge?

ZeBridge is an offline-first sync engine that keeps a local copy of your PostgreSQL tables on each device and keeps it in sync over NATS. In one sentence, what is ZeBridge?

It is a small system that puts a real database on the phone, laptop, or browser, lets the app read and write while offline, and sends every change back to PostgreSQL when the connection returns. PostgreSQL stays in charge: it applies the rules, settles conflicting writes, and sends a verdict back to the app.

The project is brand new. Its first public release landed on Saturday, 10 October 2026, and by Friday, 6 November 2026 it had already reached version 0.2.11 — 16 versions in 24 days, or a new release every 1.6 days on average. That pace tells you two things at once: the maker is shipping fast, and this is 0.x software whose API may still change.

ZeBridge is free and open source under the Apache 2.0 license, and there is no managed cloud to buy. The quickstart pulls published container images, and if you ever want to check a download before you run it, a SHA-256 hash generator gives you the file fingerprint in seconds. You run the hub yourself, usually on one small server, which is the kind of job a VPS hosting plan exists for.

The name is worth unpacking. "Ze" comes from the native core, libzb, written in Zig.

"Bridge" is the server process that bridges PostgreSQL and your devices. Together, ZeBridge PostgreSQL sync means your app talks to a database on the device, and the bridge makes sure that database matches PostgreSQL.

ZeBridge offline-first design solves a plain problem. Field teams, fleets, depots, and sites often work where the connection is poor or gone entirely.

A normal app stops when the network stops. A ZeBridge app keeps working, because the data is already on the device.

That is the whole idea in one paragraph. The rest of this guide explains how the pieces fit together, what runs on the device, how you start, where the limits are, and how ZeBridge compares with PowerSync and Electric.

How Does ZeBridge Work?

ZeBridge has two sides: a hub on your server and a small client library on each device. The hub runs NATS plus three ZeBridge processes, each with one job. The client keeps the local replica, queues writes while offline, and applies changes as they arrive.

The flow starts in PostgreSQL. The bridge reads PostgreSQL logical replication feed, the same change stream that tools like PowerSync use, and publishes schemas and changes to NATS JetStream. Connected clients apply those changes to their local databases, so the replica follows PostgreSQL row by row.

Seeding a new device does not replay the whole history. The bridge builds compressed snapshot chains per table and tenant, full snapshots plus deltas, and the client downloads them from NATS, then follows live changes after the snapshot cut point. On the maker's measured run, 10 clients seeded a 10,000-row table in 0.98 seconds at the median.

Writes travel the other way, and they travel with manners. The client publishes a mutation request to NATS.

A separate admission process validates it and enforces a per-principal queue budget before storing it for the bridge. The bridge then applies admitted writes to PostgreSQL and records a durable receipt with the outcome. If a retry matches an earlier request, the bridge reuses the receipt instead of committing the mutation twice.

The bridge also exposes HTTP APIs for invites and demos, and the client talks to those endpoints during enrollment. Enrollment is invite-based, not user login: after your backend signs a user in, it asks PostgreSQL for a one-time invite code with a single SQL call, SELECT zebridge_invite with the principal, tenant, and a one-hour interval.

One design rule shapes everything else. PostgreSQL is the authority, and offline writes are provisional until the server judges them. This is not peer-to-peer or multi-master replication, and the client never rewrites server data on its own.

Regional leaves are optional. A seeding leaf runs its own JetStream domain and mirrors the authorized tenants snapshot data, so clients nearby can download snapshots locally. Authoritative change streams, mutation processing, and verdicts still live at the hub, and leaves can also host responders near their users.

What Is a Local PostgreSQL Replica, and Why Would You Want One?

A local PostgreSQL replica is a copy of selected PostgreSQL tables that lives on the device itself, inside a real database engine, not a cache file. The app queries it with plain SQL, and it stays usable with no network at all.

The difference from a normal app is where the read happens. A normal app asks the server for every screen, so a dead connection means a dead app. A ZeBridge app asks the database on the device, so the screen loads in milliseconds and the user keeps working through a tunnel, a basement, or a rural site with one bar of signal.

Writes work the same way. The user changes a record while offline, and the write goes into a local outbox instead of failing. When the connection returns, the outbox replays the queued writes through NATS, PostgreSQL judges each one, and the verdict comes back to the app.

This model has a name in the wider industry: local-first software. The device is the primary place the app works, and the server is the authority that keeps every device honest. ZeBridge is one implementation of that idea, built around PostgreSQL as the single source of truth.

The trade is honest. You gain offline reads, instant local queries, and work that survives a dead connection.

You pay for it with a hub to run, a sync protocol to understand, and conflict rules you must accept. The sections below show exactly what those costs look like.

Which Databases Can Live on the Device?

ZeBridge does not force one local engine. The client library, libzb, can carry up to three local storage engines: SQLite plus compression by default, with PostgreSQL and DuckDB engines opened at run time. The app picks the engine that fits the job.

SQLite is the default everywhere: a file on phones, desktops, and Node, and browser storage through OPFS in the browser. It is small, fast, and already the standard embedded database on every phone. Most apps will never need anything else.

PGlite is PostgreSQL compiled to WebAssembly, available in the browser or Node. It matters because it speaks the same SQL dialect as the server, so queries written for PostgreSQL run unchanged on the device. That removes a whole class of "works on the server, breaks on the phone" bugs.

DuckDB is the analytical option, reached through libzb. It fits dashboards and services that scan large tables rather than fetching single rows. PostgreSQL itself is the fourth option, through libzb, for a service that wants a full PostgreSQL replica rather than an embedded engine.

The choice is per client, not per project. A phone can run SQLite while a dashboard service runs DuckDB against the same PostgreSQL tables, because the bridge sends the same changes to both. That flexibility is unusual: most sync engines lock you to one local store.

One more detail matters for developers. The table schema on the client is sent by the bridge, so the app does not declare the schema twice.

PowerSync, by contrast, asks the app to declare the schema again. Fewer declarations means fewer chances for the two sides to drift apart.

Which Platforms and Languages Does ZeBridge Support?

The main client is the Dart and Flutter package "zebridge" on pub.dev, currently at version 0.2.11. It needs Dart 3.10 or later, which means Flutter 3.38, and it carries libzb built in for Android, iOS, macOS, and Linux. Its build hook hands the right native library to every build, so there is nothing to install or link by hand.

For Flutter, the package delivers a PostgreSQL offline replica Flutter developers install with one command and query with plain SQL. The example in the package docs spawns a worker with a bridge URL, an invite code, and a table list, then queries and mutates with ordinary SQL: zb.query to read rows, zb.mutate to write them.

One isolate owns the client and its poll loop, and the app talks to it with futures and a report stream. The default poll wait is 100 milliseconds, and pause and resume follow the app lifecycle, so the client sleeps when the app sleeps. Device identity is protected too: on iOS it is flagged out of iCloud and computer backups, and on Android it lives in the app no-backup folder, so a restore does not resurrect an old identity.

ZeBridge is not a Flutter-only project. The same core ships as a TypeScript client for browsers and Node, a Python client over libzb C ABI, a React Native Expo module, and an Android library on Maven Central. Each binding is a thin wrapper with no behavior of its own: the shared core holds the protocol, the NATS client, and the C ABI, and every package carries the same version number as the release.

Linux users get one more route: Debian 12 and Ubuntu 22.04 packages, amd64 and arm64, from the APT repository at packages.zebridge.eu, installed with a plain sudo apt install zebridge libzb.

The gap to know is Windows. The Dart package supports Android, iOS, Linux, and macOS, and there is no Windows build of libzb yet.

The distribution notes list Windows as a stated desktop target, but add that Windows release builds do not exist yet and the two optional engines do not load on Windows. Do not plan a Windows desktop client until that changes.

How Do You Get Started With ZeBridge?

Starting is deliberately boring: one Docker Compose file, no repository clone, no local build. The quickstart needs Docker Compose only, and it starts PostgreSQL, NATS, the bridge, the sweeper, and two browser demos from published images. If you have never used it, our guide explains what Docker is and why containers make this kind of setup repeatable.

The five steps below take you from zero to a working sync. They follow the project's own quickstart, and every command comes from the ZeBridge README.

1. Download the quickstart file: curl -O the docker-compose.quickstart.yml file from the ZeBridge repository on GitHub.
2. Start the stack: docker compose -f docker-compose.quickstart.yml up, which boots PostgreSQL, NATS, the bridge, the sweeper, and two browser demos.
3. Open a demo in the browser and watch five trucks drive across a map of France's 16,173 charge points.
4. Change a truck destination from any open screen and watch it turn from where it is, on every screen at once.
5. Add the client to your own app: dart pub add zebridge or flutter pub add zebridge, then spawn a worker with your bridge URL, invite code, and tables.

The Dart side is three lines of setup. Add the dependency with dart pub add zebridge, or write zebridge: ^0.2.11 in pubspec.yaml, then import package:zebridge/zebridge.dart. The worker spawns with a bridge URL, an invite code from your backend, and the tables to follow, for example orders.

Invites are the auth model, and they are refreshingly small. ZeBridge does not authenticate users and does not care how you do it: OAuth, passwords, or magic links all work.

After your backend signs a user in, it decides the principal and tenant and asks PostgreSQL for a one-time invite code. The first run enrolls with that invite and keeps the identity next to the replica; later runs need no invite, and the token renews itself.

No CodexFuse ZeBridge tool exists, and this guide does not promise one. The quickstart above is the maker's own path, and it is the fastest way to see the sync working with your own eyes.

How Does ZeBridge Handle Offline Writes and Conflicts?

Two devices can change the same row while both are offline. Somebody has to decide, and in ZeBridge that somebody is PostgreSQL.

Ordinary writes use last-writer-wins: the newest write, by the server clock, wins the row. Cooperative editing can merge per-field registers instead, but this is not collaborative text editing, and the README says so plainly.

Every write ends with a verdict. The bridge applies the admitted mutation to PostgreSQL and records a durable receipt with the outcome, then returns that verdict to the app. The app therefore always knows whether its write landed, was rejected, or needs attention, instead of guessing from silence.

Retries are safe by design. If a client resends a mutation because it never saw the answer, the bridge matches the retry to the earlier receipt and reuses it rather than committing the mutation a second time. That single rule removes the classic duplicate-write bug that haunts offline systems.

Newer versions added two more outcomes for tricky moments: indeterminate and reconciled, with a reconciling state in the poll report. A write can be indeterminate when its result is not yet known, and reconciled when the system has settled it after the fact. The client sees these states instead of a false success.

Cleanup is the sweeper job. It advances the database garbage-collection floor and then deletes tombstones, the markers left behind by deleted rows, once they are older than that floor. One active sweeper runs per database, and it is what keeps the change log from growing forever.

The sharpest warning in the README is about device identity. Deleting a replica or reinstalling an app can destroy unsent writes, because the outbox lives with the replica. Protect device identity and storage as application data, or an uninstalled app takes its unsent work with it.

How Fast Is ZeBridge?

Speed claims need a date, hardware, and a witness, so here are the maker's own numbers with all three attached. The README reports a production-hub run on version 0.2.10, measured Monday, 2 November 2026, four days before this article: bridge, admission, sweeper, and NATS on one VPS with 6 vCPUs, 11.7 GB of memory, and 4 ingress lanes; PostgreSQL on Supabase in London; clients on one Mac; a table of 10,000 rows of about 200 bytes each.

Seeding was quick: 10 clients syncing the 10,000-row table finished in 0.98 seconds at the median. A single statement inserting 100,000 rows published at about 46,700 events per second, which is roughly 2.14 seconds for the whole batch. One client write reaching all 10 clients through PostgreSQL took 117 to 121 milliseconds at the median.

Writes judged and answered ran at 263 writes per second with one client, 1,414 per second with 10 clients, and 1,447 per second with 50 clients, where the median verdict took 3.2 seconds. The curve flattens fast: 50 clients barely beat 10, because the bottleneck is the verdict round trip, not the fan-out.

The README's own caveat belongs next to every number above: each figure is one run on the hardware named, not a capacity guarantee. No independent benchmark of ZeBridge was found, so treat these as the maker's report of what the system did once, on one setup, not as a promise of what it will do on yours.

Seeding speed also depends on the client. On an iPhone 12, seeding a large table took 35.0 seconds in React Native, 70.8 seconds in Flutter, and 725 seconds in the JavaScript client.

The JavaScript path was about 20.7 times slower than React Native and about 10.2 times slower than Flutter, while Flutter was about 2.02 times slower than React Native. The Python package page reports a writer loop at 1,700 writes per second, all settled, again as the maker's own figure.

The practical reading is simple. Reads are local and instant once seeded.

Seeding a big table on a phone takes tens of seconds in a native client and far longer in JavaScript. And write throughput tops out in the low thousands per second on a single hub, which is plenty for field teams and far from a high-frequency trading system.

ZeBridge vs PowerSync vs Electric

ZeBridge is not the first sync engine for PostgreSQL, and the honest comparison is with the two names every local-first developer already knows: PowerSync and Electric. All three keep a local database on the device and sync it with PostgreSQL. They differ in where the write path lives, what you run, and who hosts it.

PowerSync is a Postgres to SQLite bi-directional sync layer, and its goal is to give developers leverage in building local-first architecture: app code works directly with a client-side embedded database that syncs with the backend in the background. It streams changes from PostgreSQL into SQLite on the client and uploads local writes through an upload function your backend implements. Client SDKs exist for Flutter, React Native, and web.

Electric, formerly ElectricSQL, is now branded as the data primitives for collaborative, multi-agent systems, including Postgres Sync, Durable Streams, TanStack DB, and PGlite. Its core primitive is Shapes: partial replication that syncs only the relevant data subset to each client. The legacy ElectricSQL version was stopped in July 2024 and rebuilt as the current Electric, so old ElectricSQL claims are not current Electric claims.

Licensing splits the three cleanly. ZeBridge is Apache 2.0 throughout.

Electric core is Apache 2.0 too. PowerSync Open Edition is source-available under the Functional Source License, which converts to Apache 2.0 two years after release, while its client SDKs carry Apache 2.0 and MIT licenses.

Pricing splits them too. ZeBridge has no managed cloud at all: you run the hub yourself.

PowerSync Cloud starts free, with Pro from $49 a month and Team from $599 a month. Electric Cloud is usage-based: pay-as-you-go starts at $0 with bills under $5 waived, Pro is $249 a month, and Scale is $1,999 a month.

The maker's own benchmark against PowerSync deserves a careful read. Run on 2 November 2026 with 500 clients and one Supabase database, cold delivery of the 10,000-row table took 5.3 to 5.7 seconds at the median for ZeBridge against 61 to 76 seconds for PowerSync, or about 11.5 to 13.3 times faster. The snapshot was 0.23 MB per client for ZeBridge against 4.63 MB for PowerSync, or about 20.1 times smaller, because ZeBridge sends one shared compressed snapshot while PowerSync sends per-client data.

Writes were closer. Offered at 1,000 per second, ZeBridge judged 990 per second with a median verdict of 0.69 seconds, against PowerSync 879 per second with a median acknowledgement of 4.8 seconds.

Offered at 2,000 per second, ZeBridge judged 1,572 per second against PowerSync 1,702 per second. One write reaching every client took 0.4 to 0.8 seconds at the median for ZeBridge against 0.7 to 1.6 seconds for PowerSync.

That benchmark is the maker's own run on the maker's own hardware, and the README points readers to its comparison document for the configurations and what the runs do not measure. It is useful evidence that the design is fast at cold delivery, not an independent verdict on which engine you should pick.

ZeBridge vs PowerSync, then, is a choice between a young, narrow, self-hosted engine and a mature, broader, hosted-or-self-hosted one. ZeBridge gives you one hub to run, a verdict for every write, and a schema sent by the bridge. PowerSync gives you a version 1.0 product, a free cloud tier, and a team that has worked on sync since 2009 by its own account.

When Should You Not Use ZeBridge?

Do not use ZeBridge for a consumer app with one tenant per user. The README is blunt: it is not built for B2C apps with one tenant per user, and one tenant per consumer at B2C scale is outside the intended topology. Replication is tenant-based, and a followed table brings the tenant rows into the replica, so the design assumes a modest number of tenants with many devices each.

Do not use it if you need a managed cloud. There is no ZeBridge Cloud to sign up for, no dashboard, and no one to page when the hub stops. If your team cannot run PostgreSQL, NATS, and three small processes, PowerSync Cloud or Electric Cloud will fit better.

Do not use it if you need automatic high availability. The supported architecture is offline-capable clients, optional regional seeding leaves, and a single active hub.

The README warns that it is not automatic high availability, and running duplicate containers would not make it one safely. Plan your own backup and recovery for the hub.

Do not use it for collaborative text editing. Conflict handling is last-writer-wins for ordinary writes, with per-field register merges for cooperative editing. Two people typing in the same document need a CRDT editor, not a row sync engine.

Finally, do not use it on Windows desktops yet, and do not build on an API that is still 0.x without pinning the version. Sixteen releases in 24 days is exciting and unstable in equal measure, and the honest move is to pin 0.2.11, read the changelog on every upgrade, and keep the client and the hub on the same version, since the bridge, libzb, and every client package carry the same version number.

Is ZeBridge Ready for Production?

ZeBridge is 27 days old, and that fact cuts both ways. The first release was 10 October 2026, the latest is 0.2.11 from about 3 November, and the Show HN post went up on Thursday, 5 November 2026, two days after an earlier submission on Tuesday, 3 November. Both posts pointed at the same GitHub repository, and both were quiet: 1 point and 0 comments each when checked on 5 November.

The project is small by the usual signals. The repository was created 27 November 2025, and at the 5 November fetch it held 1,362 commits, 6 stars, 0 forks, 19 releases, and 21 tags.

Six stars is not adoption; it is a handful of curious developers. No independent reviews, tutorials, or third-party coverage were found beyond the Show HN listing and the package listings.

Against that, the engineering looks serious. The native core is written in Zig, the NATS client is a maintained fork, the distribution story covers five client platforms plus Debian and Ubuntu packages, and the README documents its own limits instead of hiding them. A live demo runs at bridge.zebridge.eu/demo, where five trucks drive across a map of France's 16,173 charge points and change destination from any open screen.

Production-ready is therefore the wrong question for a 27-day-old 0.x project. The right question is whether the risk fits your app.

For a B2B field-team app where offline work matters and the team can run a hub, a careful pilot on pinned 0.2.11 is reasonable. For a consumer app, a regulated workload, or a team that needs a vendor to call, it is too early, and PowerSync or Electric is the safer pick today.

What Do You Need to Run ZeBridge Yourself?

The hub needs three things: PostgreSQL with logical replication enabled and the privileges to install ZeBridge SQL objects, plus a server for NATS, the bridge, mutation admission, and the sweeper. PostgreSQL may be managed and run on another machine, which is where a managed database in the cloud computing world usually lives.

The quickstart proves the shape: one Docker Compose file starts PostgreSQL, NATS, the bridge, the sweeper, and two browser demos. In production the same pieces move to real servers, with the hub on one machine and PostgreSQL wherever you already run it. The bridge, admission, and sweeper are small processes, and the measured hub run used a single VPS with 6 vCPUs and 11.7 GB of memory.

Regional leaves are the scaling knob. A leaf runs its own JetStream domain and mirrors the authorized tenants snapshot data, so clients far from the hub download snapshots locally instead of across an ocean. Authoritative streams, mutation processing, and verdicts stay at the hub, so a leaf is a cache for seeding, not a second authority.

Budget for the unglamorous parts too. Back up PostgreSQL, because it is the authority and the only copy that matters.

Protect device identity and storage, because a deleted replica can destroy unsent writes. Watch the sweeper, because tombstones older than the garbage-collection floor are deleted and old clients that reconnect late may need a reseed. And keep the client and hub versions matched, since one version covers everything.

Sources

ZeBridge README, GitHub repository ndrean/ZeBridge — https://github.com/ndrean/zebridge — what ZeBridge is, the hub architecture, the fit and boundary quotes, the quickstart, the demo, and the maker's measured performance figures.

ZeBridge distribution notes, DISTRIBUTION.md — https://github.com/ndrean/zebridge/blob/main/DISTRIBUTION.md — libzb engines, client packages, Linux packages, and the one-version rule.

zebridge package, pub.dev — https://pub.dev/packages/zebridge and https://pub.dev/packages/zebridge/versions — version 0.2.11, first release 10 October 2026, Apache 2.0 license, platform support, and the Dart usage sketch.

Show HN records, Hacker News Algolia API — https://hn.algolia.com/api/v1/search?query=ZeBridge — submissions of 3 and 5 November 2026, items 50354763 and 50376801.

NATS, about page — https://nats.io/about/ — what NATS is and what JetStream provides.

PowerSync v1.0 announcement — https://powersync.com/blog/introducing-powersync-v1-0-postgres-sqlite-sync-layer — what PowerSync is and which SDKs it ships.

PowerSync pricing — https://powersync.com/pricing — Cloud Free, Pro from $49 a month, Team from $599 a month.

PowerSync open era post — https://powersync.com/blog/new-open-era-for-powersync — Functional Source License and the two-year conversion to Apache 2.0.

Electric homepage — https://electric-sql.com/ — Postgres Sync, Shapes, TanStack DB, and PGlite.

Electric Cloud pricing — https://electric.ax/pricing — pay-as-you-go $0, Pro $249 a month, Scale $1,999 a month.

Frequently Asked Questions

Is ZeBridge free?

Yes. ZeBridge is open source under the Apache 2.0 license, so there is no license fee and no managed cloud to pay for.

You pay only for the servers you run yourself: the hub machine, PostgreSQL, and NATS. There is no ZeBridge price list, because there is nothing to buy.

Does ZeBridge replace PostgreSQL?

No. PostgreSQL remains the authority in every ZeBridge deployment.

The device holds a replica of selected tables, and every offline write is provisional until PostgreSQL applies the rules, settles conflicts, and returns a verdict. ZeBridge moves PostgreSQL data to the edge; it does not replace the database.

Does ZeBridge work fully offline?

Reads and writes work offline, because the data and the outbox live on the device. Writes queue while the device is offline and sync when it reconnects. Full sync still needs the connection: verdicts, fresh changes from other devices, and snapshots all come through NATS, so a device that never reconnects never learns what changed elsewhere.

Does ZeBridge support Windows?

Not yet. The Dart and Flutter package supports Android, iOS, macOS, and Linux, and Windows has no libzb build yet. Windows is a stated target in the distribution notes, but Windows release builds do not exist yet, so do not plan a Windows desktop client until the project ships one.

How is ZeBridge different from PowerSync?

Both keep a local SQLite replica of PostgreSQL on the device, but the write path and the hosting differ. ZeBridge runs as one hub you host yourself, PostgreSQL judges every write and returns a verdict, and the bridge sends the table schema to the client.

PowerSync is a hosted or self-hosted service with a free cloud tier, your backend applies uploads through its own function, and the app declares the schema again. ZeBridge is also newer and narrower: it targets B2B operational apps, while PowerSync targets local-first apps generally.