How to Use PowerSync: The Beginner’s Guide (First Sync, the Schema Lesson, Sync Rules, and the Offline Arc)

CodexFuse Team · 2026-11-02T05:47:11.331Z · 15 min read min read

Learn how to use PowerSync, the sync engine that keeps on-device SQLite in sync with Postgres: your first sync, the client-side schema lesson, sync rules, the offline arc, and pricing.

Learning how to use PowerSync starts with a simple idea: your app reads and writes a local SQLite database, and PowerSync keeps that database in sync with your backend database in the background. That is the entire mental model of an offline-first app, and once it clicks, everything else about PowerSync — the schema, the sync rules, the SDKs — falls into place.

A quick disambiguation before we begin, because the search results will confuse you: this guide is about PowerSync, the sync engine for apps (powersync.com), not ASUS Power Sync monitor software, the Weather Guard Power Sync truck-wiring system, the Powermax SYNC plasma cutter, or Tony Horton's PowerSync 60 fitness program. Those products share the name and dominate several search results; none of them are this product.

PowerSync's own tutorials are built on top of Supabase, and this guide is too: if you are new to the stack, our Supabase beginner guide covers the database half of the pair before you add the sync layer.

What Is PowerSync, Exactly?

PowerSync is a sync engine that consists of two components: a service that integrates with your existing backend database to enable highly-scalable partial data syncing, and a set of client SDKs that manage client-side data — persistence in SQLite with real-time streaming updates and consistency guarantees, instant UI reactivity, and syncing write operations back. The homepage definition is even tighter: "The sync engine for real-time, fast, consistent, network-resilient applications. PowerSync keeps a local SQLite database for every user (or agent) in sync with the backend database you already have."

The emphasis in that definition is on what you do not have to do. You do not rewrite your app around an offline-first database, you do not stand up a new backend, and you do not migrate your data. You keep your Postgres (or MongoDB, MySQL, SQL Server, or Azure DocumentDB) exactly where it is. PowerSync sits between that database and your app, replicating the rows each user is allowed to see down into a SQLite database on their device, and queuing their writes back up.

Reads and writes in the application hit the local SQLite database first, which is why the app feels instant — near-zero latency, as the docs put it. There is no network round trip in the path of a tap. The network is only used, asynchronously, to keep the local copy consistent with the server.

How Does PowerSync Actually Work?

Data flows downhill from your database to the device and uphill from the device back to your database. The downhill path uses Postgres logical replication (the write-ahead log, or WAL) for Postgres backends, or change streams for MongoDB and Azure DocumentDB. The PowerSync Service captures those changes and streams them to each client's SQLite database according to your Sync Streams — the rules that decide which rows each user receives.

The uphill path is a queue, not a live write. When the app writes to SQLite, the PowerSync SDK also adds the change to an upload queue. While the device is online, the SDK calls the app's uploadData() function, which sends queued changes to your backend through your own client library — for example, the Supabase client. One architectural fact worth stating once: PowerSync never writes directly to your database. Your backend API stays in control of every write, which is how you keep validation, auth, and business logic exactly where they already live.

PowerSync vs Supabase: Do You Need Both?

Supabase is the managed Postgres database of record — auth, storage, and APIs included. PowerSync is the sync engine that replicates that Postgres data down to on-device SQLite and queues writes back up. They answer different questions: Supabase answers "where does my data live," PowerSync answers "how does my app keep working when the network does not."

This is also the line that separates PowerSync from the database-side alternatives in the same neighborhood. RxDB, for example, is the reactive NoSQL database your app code runs against, with optional replication plugins — the database itself, not a sync service. PowerSync is the sync engine that mirrors your existing Postgres into SQLite on the device. Database vs sync service; they are not rivals, and this page covers only the sync-engine lane.

Which Backend Databases Does PowerSync Support?

PowerSync began life as a Postgres-only product — version 1.0 was billed as "a Postgres–SQLite bi-directional sync layer." The backend list has since grown, so if you already run a non-Postgres database, check the current list before assuming you are locked out.

The Azure DocumentDB integration was announced on October 14, 2026, and the alpha caveat matters for beginners: only the managed Azure DocumentDB service is supported, and the architecture mirrors the MongoDB connector — DocumentDB feeds change streams into the PowerSync Service, which syncs to local SQLite; client writes go from local SQLite through the upload queue to your application backend and into DocumentDB.

How Much Does PowerSync Cost?

PowerSync is a commercial service with a free tier, and like most hosted pricing, the figures move — treat the limits below as current as of this writing and confirm them before planning around them. The free tier includes up to 2 GB of data synced per month, 500 MB of data hosted, 50 peak concurrent clients, 2 instances, and 1 source database connection per instance, with community support. One rule to memorize: free projects are deactivated after 1 week of inactivity, so do not use a free instance as a permanent staging backend and walk away.

A licensing note that beginners often miss: the client SDKs are open source (Apache 2.0 and MIT), while the server-side PowerSync Service and CLI are source-available under the Functional Source License — readable, but not the same as open source. The flagship JS SDK repository (powersync-ja/powersync-js) had about 737 stars and 101 forks when fetched; star counts move, so treat that as a snapshot, not a ranking.

How Do You Run Your First Sync?

Your first sync follows the Supabase path, because that is the path the PowerSync Supabase integration guide documents end to end. Here is the full arc, numbered so you can check off each step.

1. Create a Supabase project. This is your database of record. PowerSync's tutorials use the hosted Supabase cloud, so there is no server to provision.
2. Create your tables with row-level security. The demo apps use tables like lists and todos. Row-level security is not optional decoration — it is part of how PowerSync knows who may see what.
3. Create a Postgres role with replication privileges. PowerSync reads your database through this role (the guides call it powersync_role), keeping its replication traffic separate from your application's database user.
4. Create a publication for the tables you want synced. This is the exact command the Flutter chat tutorial uses, with your table names substituted:

   CREATE PUBLICATION powersync FOR TABLE public.messages, public.profiles;

5. Create a PowerSync Cloud instance. Every account gets Development and Production instances by default. Start in Development.
6. Connect the instance to your database. In the PowerSync Dashboard, open Database Connection, choose the Postgres tab, and paste your Supabase direct connection string. Set the username and password to your replication role, set SSL to verify-full, then Test Connection and Save.
7. Set up client authentication. Choose Supabase Auth in the dashboard's Client Auth section. (The alternative is a JWKS URI at https://<your-project>.supabase.co/auth/v1/.well-known/jwks.json with the audience authenticated.)
8. Configure Sync Streams, then wire up the app. Write your sync rules, Validate, and Deploy in the dashboard. Your app config needs three things: the Supabase URL, the Supabase publishable key, and the PowerSync instance URL.

One setting deserves the "say it once" treatment: paste the direct Supabase connection string, not the pooled one. The pooled (pgBouncer) connection does not support the replication protocol PowerSync needs, and this is the single most common first-sync failure.

What Is the Client-Side Schema?

The client-side schema defines the tables and columns of the SQLite database that the PowerSync client SDK manages and that your app reads from and writes to. This is the schema lesson, and it is deliberately small: you define only the tables your app needs locally, with column types of text, integer, or real (auto-cast). There are no migrations to write — the data is schemaless, served through SQLite views — and you can include local-only tables that never sync at all, for things like UI state or cached preferences.

For TypeScript apps, the recommended pattern is to pair that schema with Kysely, which generates type-safe queries and TypeScript types from the client schema — the Ignite React Native cookbook demonstrates this pairing. The habit to build from day one: keep your schema file and your sync rules under version control, exactly as our Git beginner guide teaches for any other code artifact. A schema that drifts between developers silently produces different local databases. Every PowerSync SQLite database on a device is a real SQLite file, so you can open it in any SQLite browser while developing and inspect exactly what your app sees.

What Are PowerSync Sync Rules?

Sync rules are the rules that decide which rows each client receives — the heart of partial syncing. The format PowerSync's docs now call "Sync Rules (Legacy)" used a bucket_definitions YAML block, and the current term is Sync Streams, where buckets are created implicitly. The concept is identical: per-user buckets, defined by a parameterized query. This minimal per-user example comes from InfoWorld's hands-on piece:

config:
  edition: 2
bucket_definitions:
  user_counters:
    parameters: SELECT request.user_id() as user_id
    data:
      - SELECT * FROM counters WHERE owner_id = bucket.user_id

Read it line by line: the parameters query pulls the authenticated user's ID out of the request; the data query selects only the rows whose owner_id matches that ID. Each user gets a bucket like user_counters["1"] containing exactly their rows. That is the whole mechanism — one section, as promised, because the rule file is short but the consequences of getting it wrong (syncing everyone's data to everyone) are not.

What Happens When Your App Goes Offline?

Everything keeps working, and nothing is lost. Writes apply immediately to the local SQLite database and are recorded in the upload queue — PUT for a new row, PATCH for changed fields, DELETE for the row id. If connectivity drops, the SDK's rule is simple: "writes remain available locally and queued until the SDK can retry them." When the device comes back online, the SDK uploads the queued changes and they appear in your database's table editor.

The beginner's proof is the airplane-mode test, straight from the official guide: put your device in airplane mode and add a to-do. When the device is back online, the SDK uploads the queued changes, and they appear in the Supabase Dashboard's Table Editor. Run this test on every app you build with PowerSync before you ship it — it is the fastest way to prove the offline arc works end to end.

Conflicts are resolved server-authoritatively. The backend implementation you write yourself follows per-field last-write-wins, and deletes always win — if two devices edit different fields of the same row, both edits survive; if one deletes what the other edited, the delete wins. Your backend operations must be idempotent (each operation carries a per-client incrementing ID so a retried upload never double-applies), and if your validation rejects a change, it is automatically rolled back on the client.

Which PowerSync SDK Should You Pick?

Pick the SDK for the framework you already ship in. PowerSync has SDKs for Flutter, React Native, web JavaScript, Vue, Nuxt, Kotlin Multiplatform, Swift, .NET, Rust, and Node.js, and the reactive hooks (usePowerSync(), useQuery(), useSyncStream()) and CRUD helpers (get, getAll, watch, execute) are consistent across them.

For choosing a learning path, the vendor tutorials are framework-scoped: the 30–45 minute PowerSync Flutter tutorial (an offline-first chat app with Supabase), and the 30–45 minute Vue offline-first ToDo app with Supabase. The only genuinely independent hands-on found this run is InfoWorld's "Hands-on with React, Supabase, and PowerSync," which is React-only. No unified PowerSync for beginners tutorial exists in the vendor ecosystem, so the guide you are reading is currently the closest thing to a framework-agnostic PowerSync tutorial.

Can You Self-Host PowerSync?

Yes. The PowerSync Service ships as a Docker image (journeyapps/powersync-service), so a self-hosted instance is a container on a box you control — our Docker beginner guide covers the container side, and what is VPS hosting covers where to put the box. Self-hosting suits teams that need data to stay inside their own VPC or have steady, predictable sync volumes where the hosted per-gigabyte metering adds up.

The honest tradeoff for beginners: self-hosting moves the operational burden — replication health, checkpoints, backups, upgrades — onto you. Start on the hosted free tier, prove the sync model against your schema, and only then decide whether the ops work is cheaper than the invoice. The one-week idle deactivation on free projects is the nudge to either keep the instance warm or commit to a real deployment.

7 Beginner Mistakes With PowerSync

Sources

1. PowerSync homepage — product definition and "keeps a local SQLite database for every user in sync with the backend database you already have"
2. PowerSync pricing — Free/Pro/Team/Enterprise plans, free-tier limits, 1-week idle deactivation (fetched 2026-11-02)
3. PowerSync open-source page — SDKs under Apache 2.0/MIT, Service and CLI under the Functional Source License
4. Flutter tutorial: building an offline-first chat app with Supabase and PowerSync — 30–45 min vendor walkthrough, CREATE PUBLICATION example
5. Vue tutorial: offline-first ToDo app with Supabase and PowerSync — 30–45 min vendor walkthrough
6. Introducing PowerSync v1.0: Postgres–SQLite sync layer — the product began Postgres-only
7. PowerSync docs: Supabase integration guide — sync architecture, upload queue, airplane-mode test
8. PowerSync docs: handling update conflicts — server-authoritative reconciliation, last-write-wins, deletes always win
9. InfoWorld: Hands-on with React, Supabase, and PowerSync (May 2026) — independent hands-on, Sync Streams YAML example, JWKS client-auth setup
10. Microsoft devblogs: Build offline-first apps with Azure DocumentDB and PowerSync (Oct 14, 2026) — DocumentDB alpha integration announcement
11. Ignite cookbook: Local-First Data with PowerSync — React Native, Kysely type-safe queries
12. GitHub API: powersync-ja/powersync-js — 737 stars, 101 forks, Apache-2.0 (fetched 2026-11-02)
13. Docker Hub: journeyapps/powersync-service — the self-hosted service image

Frequently Asked Questions

Is PowerSync the same as Supabase?

No. Supabase is the managed Postgres database of record — auth, storage, and APIs. PowerSync is the sync engine that replicates that Postgres data down to on-device SQLite and queues writes back up. PowerSync's own tutorials use Supabase as the backend; the two are a pair, not substitutes.

Does PowerSync work offline?

Yes — offline-first is the entire point. Your app reads and writes the local SQLite database with near-zero latency, writes are recorded in an upload queue, and the SDK syncs them to your backend when connectivity returns. The airplane-mode test (add a record offline, watch it appear in the database when you reconnect) proves the arc end to end.

Is PowerSync free?

There is a free tier: up to 2 GB of data synced per month, 500 MB hosted, 50 peak concurrent clients, and 2 instances — but free projects are deactivated after 1 week of inactivity. Paid plans start at $49/month for Pro. Pricing figures move, so confirm them on powersync.com before planning around them.

Does PowerSync support databases other than Postgres?

Yes. It began Postgres-only in v1.0, and now also supports MongoDB, MySQL, SQL Server, and Azure DocumentDB (the DocumentDB integration is in alpha, and its behavior may still change).

Is PowerSync open source?

Partly. The client SDKs are open source under Apache 2.0 and MIT licenses; the server-side PowerSync Service and CLI are source-available under the Functional Source License, which is not the same as open source.