Protocol

Self-Hosted Architecture

GitHub

Community Discord

PowerSync Dashboard

PowerSync Website

PowerSync

Client SDKs

Self-Hosting

Tutorials

Resources

Get Started

Dashboard

The core components of PowerSync are the service and client SDKs

Architecture Overview

Sync Engine for Local-First & Offline-First Apps

PowerSync Overview

Our vision is that a local-first or offline-first app architecture should be easier for the developer than cloud-first, and give a better experience for the end-user — even when they're online.

PowerSync Philosophy

Quickstart / Overview

Quickstart Guide / Installation Overview

Configure your backend database for PowerSync

Overview

Source Database Setup

Security & IP Filtering

Connect a PowerSync Cloud instance to your backend database.

Database Connection

Include the PowerSync Client SDK in your project

Client-Side Setup

You need to set up your client-side schema in your app project. This involves defining your schema in code using the PowerSync syntax.

Define your Schema

You need to instantiate the client-side PowerSync database — this is the core managed local SQLite database.

Instantiate PowerSync Database

The PowerSync 'backend connector' provides the connection between your application backend and the PowerSync client-slide managed SQLite database.

Integrate with your Backend

App Backend Setup

Your app backend needs to expose an API endpoint to write changes to your backend database that are received from the PowerSync client.

Writing Client Changes

Authentication Setup

Development Tokens

Firebase Auth

Auth0

Any authentication provider can be supported by generating custom JWTs for PowerSync.

Custom

Sync Rules

The simplest Sync Rules are for "global" data — synced to all users. 

Global Data

Organize Data Into Buckets

Parameter Queries

Data Queries

PowerSync's Sync Rules use the [SQLite type system](https://www.sqlite.org/datatype3.html).

Types

On the client, PowerSync only supports a single primary key column called `id`, of type `text`.

Client ID

Operators and functions can be used to transform columns/fields before being synced to a client.

Operators and Functions

Schemas and Connections

For simplicity, we recommend using only lower case identifiers for all table/collection and column/field names used in PowerSync. If you need to use a different case, continue reading.

Case Sensitivity

A group of rows/documents, from one or more tables/collections.

Glossary

Guide: Many-to-Many and Join Tables

This section covers use cases that will arise throughout the lifetime of your application as you add new features, refactor tech debt into oblivion, and upgrade dependencies.

Lifecycle / Maintenance

Implementing Schema Changes

The general approach is that for transient errors (e.g. server or database unavailable), the changes are kept in the client-side upload queue, and retried at 5 second intervals, keeping the original order. In the future it will be possible to control the retry behavior.

Handling Write / Validation Errors

Upgrading the Client SDK

Postgres Maintenance

[Buckets](/usage/sync-rules/organize-data-into-buckets) store data as a history of changes, not only the current state.

Compacting Buckets

Learn how to use PowerSync in common use cases

Use Case Examples

Syncing large attachments/files directly using PowerSync is not recommended.

Attachments / Files

You might want to run PowerSync operations while the client device is inactive or the app is in the background.

Background Syncing

While PowerSync does not use [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type) directly as part of its sync or conflict resolution process, CRDT data (from a library such as [Yjs](https://github.com/yjs/yjs) or y-crdt) may be persisted and synced using PowerSync.

CRDTs

PowerSync is fully compatible with more advanced Postgres types.

Custom Types, Arrays and JSON

Data Encryption

Client-side full-text search (FTS) is available using the [SQLite FTS5 extension](https://www.sqlite.org/fts5.html).

Full-Text Search

Infinite scrolling is a software design technique that loads content continuously as the user scrolls down the page/screen.

Infinite Scrolling

Some use cases require data persistence before the user has registered or signed in.

Local-only Usage

Custom types, arrays and [PostGIS](https://postgis.net/) are frequently presented together since geospatial data is often complex and multidimensional.

PostGIS

In some scenarios, you may want to sync tables using different priorities. For example, you may want to sync a subset of all tables first to log a user in as fast as possible, then sync the remaining tables in the background.

Prioritized Sync

Use Custom Write Checkpoints to handle asynchronous data uploads, as in chained data pipelines.

Data Pipelines

Tools

Introduction to and overview of the PowerSync Dashboard and Admin Portal

Manage your PowerSync Cloud environment programmatically

CLI (Beta)

Diagnostics App

Overview of monitoring and alerting functionality for PowerSync Cloud instances

Monitoring and Alerting

Learn how to integrate PowerSync with your favorite tools.

Integrations Overview

Tutorial-style integration guide for creating offline-first apps with Supabase and PowerSync, using a demo to-do list app in Flutter, React Native, JavaScript Web, Kotlin Multiplatform and Swift.

Supabase + PowerSync

Examples of syncing attachments between a client app and Supabase Storage.

Handling Attachments

Real-time Streaming

RLS and Sync Rules

Local development with Supabase and PowerSync.

Local Development

Integration guide for creating offline-first apps with FlutterFlow and PowerSync with Supabase as the backend.

FlutterFlow + PowerSync

Flutter Web

PowerSync supports [Full-Text Search](/usage/use-case-examples/full-text-search) on all Flutter platforms.

Advanced workflow for users requiring more control.

GitHub Workflow

Integration guide for deploying a Postgres database and custom backend using Railway for Postgres and Node.js hosting.

Railway + PowerSync

Integration guide for deploying the [PowerSync Service](http://localhost:3333/architecture/powersync-service) on Coolify

Coolify + PowerSync

Deploy PowerSync Service on Coolify

MongoDB Atlas Migration Guide

ElectricSQL (Legacy) Migration Guide

WatermelonDB Migration Guide

PowerSync Service

Client Architecture

PowerSync Protocol

PowerSync uses the concept of "checkpoints" to ensure the data is consistent.

Consistency

PowerSync supports multiple client-side frameworks with official SDKs

Introduction

Full SDK reference for using PowerSync in Flutter/Dart clients

Flutter

Web Support (Beta)

Flutter Web Support (Beta)

ORM Support (Alpha)

Flutter ORM Support (Alpha)

Code snippets and guidelines for common scenarios

Usage Examples

Guidelines for unit testing with PowerSync

Unit Testing

API Reference

Full SDK reference for using PowerSync in React Native clients

React Native & Expo

React Native Web Support

ORM Support

JavaScript ORM Support

Full SDK reference for using PowerSync in JavaScript Web clients

JavaScript Web

JavaScript SPA Frameworks

Kotlin Multiplatform (Beta)

Swift (Beta)

Self-host PowerSync in your own infrastructure (PowerSync Open Edition or PowerSync Enterprise Self-Hosted Edition).

Getting Started

Deploy PowerSync on your own infrastructure (PowerSync Open Edition or PowerSync Enterprise Self-Hosted Edition).

Installation

Configuration details for connecting the PowerSync Service to your database

PowerSync Service Setup

Using Docker Compose to simplify your local development stack

From a security perspective, the primary activity required will be placing a load balancer with TLS in front of PowerSync. 

Securing Your Deployment

Server Specs

Healthchecks

Telemetry

Enterprise

Appendix

A collection of tutorials showcasing solutions to common use cases across the PowerSync stack.

A collection of tutorials for client-side use cases.

A collection of tutorials exploring storage strategies.

In this tutorial, we will show you how to replace Supabase Storage with AWS S3 for handling attachments in the [React Native To-Do List demo app](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-supabase-todolist).

AWS S3 Storage

Use AWS S3 for attachment storage

In this tutorial we will show you how to modify the [PhotoAttachmentQueue](https://github.com/powersync-ja/powersync-js/blob/main/demos/react-native-supabase-todolist/library/powersync/PhotoAttachmentQueue.ts) for PDF attachments.

PDF attachments

A collection of tutorials exploring performance strategies.

In this tutorial we will show you how to improve the performance of the Supabase Connector for the [React Native To-Do List demo app](https://github.com/powersync-ja/powersync-js/tree/main/demos/react-native-supabase-todolist).

Improve Supabase Connector

A collection of tutorials showcasing various data management strategies and use cases.

In this tutorial we will show you how to perform a cascading delete on the client.

Cascading Delete

In this tutorial we will show you how to map a local UUID to a remote sequential (auto-incrementing) ID.

Sequential ID Mapping

A collection of tutorials related to self-hosting.

In this tutorial we will show you how to generate a development token for the self-hosted [PowerSync Service](https://powersync.mintlify.app/architecture/powersync-service#powersync-service).

Generate a Development Token

Gallery of example projects built with PowerSync.

Demo Apps / Example Projects

How does PowerSync fit in to the local-first software movement?

Local-First Software

Usage & billing for PowerSync Cloud (our cloud-hosted offering).

Usage & Billing

Practical example of how pricing is calculated on the Pro or Team plan of PowerSync Cloud (usage-based pricing)

Pricing Example

Usage and billing FAQs and troubleshooting strategies.

FAQ & Troubleshooting

Summary of common issues, troubleshooting tools and pointers.

Troubleshooting

Performance and Limits

PowerSync feature states and their implications for factors such as API stability and support.

Introduction

Installation

Usage

Integration Guides

Migration Guides

Architecture

Architecture Overview

PowerSync Service

Client Architecture

Protocol

PowerSync Protocol

Consistency

Self-Hosted Architecture

Installation

Introduction

Installation

Usage

Integration Guides

Migration Guides

Architecture

PowerSync Service

Client Architecture

​Protocol

PowerSync Protocol

Consistency

​Self-Hosted Architecture

Installation

Protocol

Self-Hosted Architecture