Source Database Setup

Postgres

Version compatibility: PowerSync requires Postgres version 11 or greater.

Configuring your Postgres database with PowerSync generally involves three tasks:

Enable logical replication
Create a PowerSync database user
Create powersync publication

We have documented steps for some hosting providers:

1. Enable logical replication

Supabase has logical replication enabled by default — no action required.

2. Create a PowerSync Database User

It is not currently possible to create a new user on Supabase with replication permissions without contacting their support. Instead, use the default postgres user.

3. Create “powersync” Publication

The postgres user does not have access to create a publication for all tables. Instead, list each table explicitly.

This can also be done on the Supabase dashboard in the database Replication page.

CREATE PUBLICATION powersync FOR TABLE public.lists, public.todos;

Prerequisites

The instance must be publicly accessible using an IPv4 address.

Access may be restricted to specific IPs if required — see IP Filtering.

1. Enable Logical Replication

Set the rds.logical_replication parameter to 1 in the parameter group for the instance.

2. Create a PowerSync Database User

Create a PowerSync user on Postgres:

-- SQL to create powersync user

CREATE ROLE powersync_role WITH LOGIN PASSWORD 'myhighlyrandompassword';

-- Allow the role to perform replication tasks

GRANT rds_replication TO powersync_role;

-- Set up permissions for the newly created role

GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role;

For read-only access, only the SELECT privilege is required — INSERT, UPDATE and DELETE can be removed.

To restrict read access to specific tables, explicitly list allowed tables for both the SELECT privilege, and for the publication (as well as for any other publications that may exist).

3. Create “powersync” Publication

-- Create publication to replicate tables. Specify a subset of tables if required.

-- NOTE: this must be named "powersync" at the moment

CREATE PUBLICATION powersync FOR ALL TABLES;

PowerSync supports both “Azure Database for PostgreSQL” and “Azure Database for PostgreSQL Flexible Server”.

Prerequisites

The database must be accessible on the public internet. Once you have created your database, navigate to Settings -> Networking and enable Public access.

1. Enable Logical Replication

Follow the steps as noted in this article to allow logical replication:

https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-logical#prerequisites-for-logical-replication-and-logical-decoding

2. Create a PowerSync Database User

Create a PowerSync user on Postgres:

-- SQL to create powersync user

CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword';

GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role;

For read-only access, only the SELECT privilege is required — INSERT, UPDATE and DELETE can be removed.

To restrict read access to specific tables, explicitly list allowed tables for both the SELECT privilege, and for the publication (as well as for any other publications that may exist).

3. Create “powersync” Publication

-- Create publication to replicate tables. Specify a subset of tables if required.

-- NOTE: this must be named "powersync" at the moment

CREATE PUBLICATION powersync FOR ALL TABLES;

-- Example for specifying a subset of tables:

-- CREATE PUBLICATION powersync FOR table users, projects, user_projects, checklists;

1. Enable Logical Replication

In Google Cloud SQL Postgres, enabling the logical replication is done using flags:

2. Create a PowerSync Database User

Create a PowerSync user on Postgres:

-- SQL to create powersync user

CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword';

GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role;

For read-only access, only the SELECT privilege is required — INSERT, UPDATE and DELETE can be removed.

To restrict read access to specific tables, explicitly list allowed tables for both the SELECT privilege, and for the publication (as well as for any other publications that may exist).

3. Create “powersync” Publication

-- Create publication to replicate tables. Specify a subset of tables if required.

-- NOTE: this must be named "powersync" at the moment

CREATE PUBLICATION powersync FOR ALL TABLES;

Neon is a serverless Postgres environment with an innovative pricing model that separates storage and compute.

1. Enable Logical Replication

Open your project and navigate to “Settings” -> “Beta”, then click “Enable”.

2. Create a PowerSync Database User

Create a PowerSync user on Postgres:

-- SQL to create powersync user

CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword';

GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role;

For read-only access, only the SELECT privilege is required — INSERT, UPDATE and DELETE can be removed.

To restrict read access to specific tables, explicitly list allowed tables for both the SELECT privilege, and for the publication (as well as for any other publications that may exist).

3. Create “powersync” Publication

-- Create publication to replicate tables. Specify a subset of tables if required.

-- NOTE: this must be named "powersync" at the moment

CREATE PUBLICATION powersync FOR ALL TABLES;

Fly Postgres is a Fly app with flyctl sugar on top to help you bootstrap and manage a database cluster for your apps.

1. Enable Logical Replication

Once you’ve deployed your Fly Postgres cluster, it’s time to enable logical replication.

This is performed by running the below command:

fly pg config update --wal-level=logical

2. Create a PowerSync Database User

Create a PowerSync user on Postgres:

-- SQL to create powersync user

CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword';

GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role;

For read-only access, only the SELECT privilege is required — INSERT, UPDATE and DELETE can be removed.

To restrict read access to specific tables, explicitly list allowed tables for both the SELECT privilege, and for the publication (as well as for any other publications that may exist).

3. Create “powersync” Publication

-- Create publication to replicate tables. Specify a subset of tables if required.

-- NOTE: this must be named "powersync" at the moment

CREATE PUBLICATION powersync FOR ALL TABLES;

For other providers and self-hosted databases:

Need help? Simply contact us on Discord and we’ll help you get set up.

1. Enable Logical Replication

PowerSync reads the Postgres WAL using logical replication in order to create sync buckets in accordance with the specified PowerSync Sync Rules.

If you are managing Postgres yourself, set wal_level = logical in your config file:

Alternatively, you can use the below SQL commands to check and enable logical replication:

-- Check the replication type

SHOW wal_level;

-- Enable logical replication

ALTER SYSTEM SET wal_level = logical;

Note that Postgres must be restarted after changing this config.

If you’re using a managed Postgres service, there may be a setting for this in the relevant section of the service’s admin console.

2. Create a PowerSync Database User

Create a PowerSync user on Postgres:

-- SQL to create powersync user

CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword';

GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role;

For read-only access, only the SELECT privilege is required — INSERT, UPDATE and DELETE can be removed.

To restrict read access to specific tables, explicitly list allowed tables for both the SELECT privilege, and for the publication (as well as for any other publications that may exist).

3. Create “powersync” Publication

-- Create publication to replicate tables. Specify a subset of tables if required.

-- NOTE: this must be named "powersync" at the moment

CREATE PUBLICATION powersync FOR ALL TABLES;

Unsupported Hosted Postgres Providers

Due to the logical replication requirement, not all hosting providers are supported.

Notably, some “serverless Postgres” providers do not support logical replication, and are therefore not supported by PowerSync yet.

MongoDB (Beta)

Version compatibility: PowerSync requires MongoDB version 6.0 or greater.

Status of MongoDB support in PowerSync

Beta Released — December 2024

Our MongoDB connector is in Beta as of December 2024 and is supported for use in production environments. See the full release notes.

In PowerSync nomenclature, Beta means the package is ready to be used for production given you have adequately tested your use case. We typically don’t make any breaking API changes when moving from Beta to V1 (learn more about feature states here).

V1 (In Progress — ETA 2025Q1)

Our roadmap to V1 remains flexible and is strongly guided by customer feedback. Our focus includes enhancing usability, improving documentation such as migration guides, developing reference/demo applications, and exploring support for sharded MongoDB clusters. If you’d like to see any of these features, please visit our product roadmap and upvote/submit ideas.

Permissions required - MongoDB Atlas

For MongoDB Atlas databases, the minimum permissions are:

readWrite@<your_database>._powersync_checkpoints
read@<your_database>

To allow PowerSync to automatically enable changeStreamPreAndPostImages on replicated collections, additionally add the dbAdmin permission:

readWrite@<your_database>._powersync_checkpoints
read@<your_database>
dbAdmin@<your_database>

If you are replicating from multiple databases in the cluster, you need read permissions on the entire cluster, in addtion to the above:

readAnyDatabase@admin

Privileges required - Self-hosted / Custom roles

For self-hosted MongoDB, or for creating custom roles on MongoDB Atlas, PowerSync requires the following privileges/granted actions:

On the database being replicated: listCollections.
On all collections in the database: changeStream.
- This must apply to the entire database, not individual collections, collection: "".
- If replicating from multiple databases, this must apply to the entire cluster, db: "".
On each collection being replicated: find.
On the _powersync_checkpoints collection: createCollection, dropCollection, find, changeStream, insert, update, and remove.
To allow PowerSync to automatically enable changeStreamPreAndPostImages on replicated collections, additionally add the collMod permission on all replicated collections.

Post-Images

To replicate data from MongoDB to PowerSync in a consistent manner, PowerSync uses Change Streams with post-images to get the complete document after each change. This requires the changeStreamPreAndPostImages option to be enabled on replicated collections.

PowerSync supports three configuration options for post-images:

post_images: off: Uses fullDocument: 'updateLookup' for backwards compatibility. This was the default for older instances. However, this may lead to consistency issues, so we strongly recommend enabling post-images instead.
post_images: auto_configure (Default for new instances): Automatically enables the changeStreamPreAndPostImages option on collections as needed. Requires the permissions/privileges mentioned above. If a collection is removed from Sync Rules, developers can manually disable changeStreamPreAndPostImages.
post_images: read_only: Uses fullDocument: 'required' and requires changeStreamPreAndPostImages: { enabled: true } to be set on every collection referenced in Sync Rules. Replication will error if this is not configured. This option is ideal when permissions are restricted.

To manually configure collections for read_only mode, run this on each collection:

db.runCommand( {
 collMod: <collection>,
 changeStreamPreAndPostImages: { enabled: <boolean> }
} )

You can view which collections have the option enabled using:

db.getCollectionInfos().filter(c => c.options?.changeStreamPreAndPostImages?.enabled)

Post-images can be configured for PowerSync Cloud instances under the connection settings in the Dashboard (right-click on your instance to edit it). For self-hosted PowerSync instances, configure post-images in the config.yaml file; see an example here.

MongoDB Atlas private endpoints using AWS PrivateLink

If you need to use private endpoints with MongoDB Atlas, see Private Endpoints.

Migrating from MongoDB Atlas Device Sync

For more information on migrating from Atlas Device Sync to PowerSync, see our migration guide and this post on our blog.

MySQL (Alpha)

This section is a work in progress. More details for MySQL connections are coming soon. In the meantime, ask on our Discord server if you have any questions.

Version compatibility: PowerSync requires MySQL version 5.7 or greater.

MySQL connections use the binary log to replicate changes.

Generally, this requires the following config:

gtid_mode : ON
enforce_gtid_consistency : ON
binlog_format : ROW

PowerSync also requires a user with replication permissions on the database. An example:

-- Create a user with necessary privileges
CREATE USER 'repl_user'@'%' IDENTIFIED BY 'good_password';

-- Grant replication client privilege
GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'repl_user'@'%';

-- Grant access to the specific database
GRANT ALL PRIVILEGES ON powersync.* TO 'repl_user'@'%';

-- Apply changes
FLUSH PRIVILEGES;

Next Step

Next, connect PowerSync to your database:

Database Connection

Self-hosting: If you are self-hosting PowerSync, refer to PowerSync Service Setup next.

Introduction

Installation

Usage

Integration Guides

Migration Guides

Architecture

​ Postgres

1. Enable logical replication

2. Create a PowerSync Database User

3. Create “powersync” Publication

Prerequisites

1. Enable Logical Replication

2. Create a PowerSync Database User

3. Create “powersync” Publication

Prerequisites

1. Enable Logical Replication

2. Create a PowerSync Database User

3. Create “powersync” Publication

1. Enable Logical Replication

2. Create a PowerSync Database User

3. Create “powersync” Publication

1. Enable Logical Replication

2. Create a PowerSync Database User

3. Create “powersync” Publication

1. Enable Logical Replication

2. Create a PowerSync Database User

3. Create “powersync” Publication

1. Enable Logical Replication

2. Create a PowerSync Database User

3. Create “powersync” Publication

​Unsupported Hosted Postgres Providers

​ MongoDB (Beta)

​Status of MongoDB support in PowerSync

​Beta Released — December 2024

​V1 (In Progress — ETA 2025Q1)

​Permissions required - MongoDB Atlas

​Privileges required - Self-hosted / Custom roles

​Post-Images

​MongoDB Atlas private endpoints using AWS PrivateLink

​Migrating from MongoDB Atlas Device Sync

​ MySQL (Alpha)

​Next Step

Postgres

Unsupported Hosted Postgres Providers

MongoDB (Beta)

Status of MongoDB support in PowerSync

Beta Released — December 2024

V1 (In Progress — ETA 2025Q1)

Permissions required - MongoDB Atlas

Privileges required - Self-hosted / Custom roles

Post-Images

MongoDB Atlas private endpoints using AWS PrivateLink

Migrating from MongoDB Atlas Device Sync

MySQL (Alpha)

Next Step