Source Database Setup

​

Postgres

1. Ensure logical replication is enabled
2. Create a PowerSync database user
3. Create powersync logical replication publication

Supabase

Try our new guided Supabase setup in the PowerSync Dashboard. It configures your Supabase project and PowerSync Cloud instance for you.Look for the Set Up with Supabase button in your instance’s Health or Database Connection view, then follow the on-screen steps.

To set up Supabase manually instead, follow the steps below.

​

1. Ensure logical replication is enabled

No action required: Supabase has logical replication enabled by default.

​

2. Create a PowerSync database user

-- Create a role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

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

​

3. Create powersync publication

-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

Also see our Supabase integration guide.

AWS RDS

​

Prerequisites

The instance must be publicly accessible using an IPv4 address.

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

​

1. Ensure logical replication is enabled

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 BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';

-- Allow the role to perform replication tasks
GRANT rds_replication TO powersync_role;

-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role;

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 a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

AWS Aurora

​

Supported Scaling Options

PowerSync replicates only from the writer. Clusters can also include reader instances.

Scaling Option	Scaling Model	PowerSync Support
Provisioned	Configured instance capacity	Supported
Aurora Serverless v2	Automatically adjusts instance capacity	Supported
Aurora Postgres Limitless	Horizontally scales writes and reads across multiple nodes	Not supported

​

Prerequisites

PowerSync must be able to reach the writer. Either make the writer publicly accessible over IPv4 and restrict access to PowerSync’s IPs (see IP Filtering), or connect through a Private Endpoint using AWS PrivateLink. If you use public access, apply the same network settings to reader instances that can become the writer.

​

1. Ensure logical replication is enabled

In Aurora, rds.logical_replication is a setting of the DB cluster parameter group, not of a DB instance parameter group.

1. In the Amazon RDS console, open your cluster’s Configuration tab and follow the Parameter group link of type DB cluster parameter group. If the cluster still uses a default parameter group, create a custom DB cluster parameter group and assign it to the cluster first. Default parameter groups cannot be edited.
2. Set rds.logical_replication to 1 and save.
3. Reboot the writer. The change only takes effect after the reboot.
4. Connect to the writer through the cluster endpoint and confirm the settings:

SHOW rds.logical_replication; -- on
SHOW wal_level;               -- logical

For the related parameters max_replication_slots, max_wal_senders and max_worker_processes, see Setting up logical replication for your Aurora PostgreSQL DB cluster. PowerSync uses one replication slot per instance, plus a second slot while it processes a new Sync Config version. See Postgres Maintenance.

​

2. Create a PowerSync database user

Create a PowerSync user on Postgres:

-- SQL to create powersync user
CREATE ROLE powersync_role WITH BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';

-- Allow the role to perform replication tasks
GRANT rds_replication TO powersync_role;

-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role;

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 a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

Azure Postgres

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. Ensure logical replication is enabled

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

​

2. Create a PowerSync database user

-- Create a role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

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

​

3. Create powersync publication

-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

Google Cloud SQL

​

1. Ensure logical replication is enabled

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

​

2. Create a PowerSync database user

-- Create a role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

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

​

3. Create powersync publication

-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

Neon

​

1. Ensure logical replication is enabled

Enabling logical replication can’t be undone. It also restarts your project’s computes, which drops active connections.

• Web UI
• CLI

In the Neon Console, go to Settings > Postgres and enable Logical Replication.

Run the following Neon CLI command, replacing <project-id> with your Neon project ID:

neon projects update <project-id> --enable-logical-replication --yes

While PowerSync is connected, its replication connection keeps your Neon compute active, so the compute doesn’t scale to zero. This uses compute hours continuously, which counts toward your Neon plan’s limits.

​

2. Create a PowerSync database user

-- Create a role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

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

​

3. Create powersync publication

-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

Also see our Neon integration guide.

Fly Postgres

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

​

1. Ensure logical replication is enabled

Once you’ve deployed your Fly Postgres cluster, you can use the following command to ensure logical replication is enabled:

fly pg config update --wal-level=logical

​

2. Create a PowerSync database user

-- Create a role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

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

​

3. Create powersync publication

-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

PlanetScale

​

1. Ensure logical replication is enabled

No action required: PlanetScale has logical replication (wal_level = logical) enabled by default.

​

2. Create a PowerSync database user

-- Create a role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

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

​

3. Create powersync publication

  -- Create a publication to replicate tables.
  -- PlanetScale does not support ON ALL TABLES so
  -- Specify each table you want to sync
  -- The publication must be named "powersync"
  CREATE PUBLICATION powersync
  FOR TABLE public.lists, public.todos;

Render Postgres

Logical replication can be enabled for Render Postgres but you need to contact their support team. Here are some prerequisites before contacting them:

• The disk size must be at least 10 GB.
• You must be on a Professional workspace or higher.

The Render support team will ask you the following:

• Database user for replication (you can use the default or create a new user yourself)
• Schema(s)
• Publication name (only if you want them to set FOR ALL TABLES; otherwise, you’ll be able to create publications per table yourself later)

If you want to create the publication FOR ALL TABLES, you must let their support team know that you want the publication name to be powersync.Additional notes they’ll share with you:

We will reserve approximately 1/8 of your storage for wal_keep_size. This will not be available for your normal operations and will always be reserved no matter what. We will also schedule maintenance for the database to pick up the changes. It will be initially scheduled for 14 days out with a deadline of 30 days out. Once the maintenance is added, you can reschedule to any time between immediately and the deadline. If you do nothing, it will run automatically at the initially scheduled time of 14 days out.

Xata

​

1. Ensure logical replication is enabled

ALTER SYSTEM SET wal_level = logical;
ALTER SYSTEM SET max_replication_slots = 10;
ALTER SYSTEM SET max_wal_senders = 10;

​

2. Create a PowerSync database user

-- Create a role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

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

​

3. Create powersync publication

-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

See Xata’s documentation for more information on setting up logical replication with Xata.

Other / Self-hosted

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

​

1. Ensure logical replication is enabled

PowerSync reads the Postgres WAL using logical replication in order to create buckets in accordance with your Sync Streams.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 ensure logical replication is enabled:

-- Check the replication type

SHOW wal_level;

-- Ensure logical replication is enabled

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 role/user with replication privileges for PowerSync
CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
-- Set up permissions for the newly created role
-- Read-only (SELECT) access is required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;  

-- Optionally, grant SELECT on all future tables (to cater for schema additions)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role; 

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

​

3. Create powersync publication

-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

Note that the PowerSync Service has to read all updates present in the publication, regardless of whether the table is referenced in your Sync Streams. This can cause large spikes in memory usage or introduce replication delays, so if you’re dealing with large data volumes, you’ll want to specify a comma-separated subset of tables to replicate instead of FOR ALL TABLES.

The snippet above replicates all tables and is the simplest way to get started in a dev environment.

​

Unsupported Hosted Postgres Providers

​

See Also

• Postgres Maintenance: Logical Replication Slots

​

MongoDB

​

MongoDB Permissions

​

Permissions Required: MongoDB Atlas

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

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

readAnyDatabase@admin

​

Privileges Required: Self-Hosted or Custom Roles

• listCollections: This privilege must be granted on the database being replicated.
• find: This privilege must be granted either at the database level or on specific collections.
• changeStream: This privilege must be granted at the database level (not on individual collections). In MongoDB Atlas, set collection: "" or check Apply to any collection in MongoDB Atlas if you want to apply this privilege on any collection.
  • If replicating from multiple databases, this must apply to the entire cluster. Specify db: "" or check Apply to any database in MongoDB Atlas.
• For the _powersync_checkpoints collection add the following privileges: createCollection, dropCollection, find, changeStream, insert, update, and remove
• To allow PowerSync to automatically enable changeStreamPreAndPostImages on replicated collections (i.e. the Post Images setting for the MongoDB connection on your PowerSync instance is set to Auto-Configure, which is the default for new PowerSync instances), additionally add the collMod permission on the database and all collections being replicated.

​

Post Images

1. Off: (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.
2. Auto-Configure: (post_images: auto_configure) The 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 Streams, you need to manually disable changeStreamPreAndPostImages on that collection.
3. Read-only: (post_images: read_only): Uses fullDocument: 'required' and requires changeStreamPreAndPostImages: { enabled: true } to be set on every collection referenced in your Sync Streams. Replication will error if this is not configured. This option is ideal when permissions are restricted.

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

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

​

MongoDB Atlas Private Endpoints Using AWS PrivateLink

​

Azure DocumentDB

​

Supported Variants

​

Limitations to Check Before You Connect

• Source database only. DocumentDB is supported as a source database, not as PowerSync’s storage database (especially relevant if you are self-hosting PowerSync). We don’t currently plan to support it for storage.
• Post-images are not supported. Set Post Images to Off (post_images: off, the default); the auto_configure and read_only modes fail. This does not reduce correctness: DocumentDB always includes the full current document on update events, so updates and deletes still replicate correctly.
• Collection drop and rename are not replicated. Already-synced rows remain in PowerSync storage under the old name. To recover, redeploy your Sync Streams to trigger a resync. Regular inserts, updates, and deletes are unaffected.
• Large initial snapshots may not complete on legacy storage. DocumentDB keeps source changes for a limited time. On storage versions 1 and 2, PowerSync waits for the initial scan to finish before reading those changes. On a large or busy source, the earliest required changes can expire before the scan finishes, forcing PowerSync to start over. Use storage version 4, which processes new source changes while the initial snapshot runs.
• Rows of 15 MiB or larger are not synced. Such rows are dropped with a logged error. This is a general PowerSync limit, not DocumentDB-specific, but it is more reachable on DocumentDB because the source permits documents up to 16 MiB and every change event carries the full document.
• Large documents replicate very slowly. DocumentDB delivers large change events much more slowly than standard MongoDB. The document still replicates correctly, but latency spikes around large documents (including updates that change only a small field), and a single large event delays every change behind it. If your workload includes large documents, validate replication latency against your cluster.
• Streaming updates can be delayed by up to roughly 1 second after an idle period. DocumentDB does not currently support reliable long-polling on its change stream, so PowerSync adds a short, capped delay between polls when the stream is idle. This is a temporary workaround and is expected to be resolved in an upcoming Azure DocumentDB release.
• Do not modify the internal checkpoints collection. PowerSync maintains a _powersync_checkpoints collection in the source database for replication bookkeeping. Dropping it or deleting its documents disrupts replication.

​

MySQL

AWS Aurora MySQL

PowerSync supports provisioned Aurora MySQL clusters and Aurora Serverless v2 clusters with a single writer. The cluster can include reader instances, but PowerSync replicates only from the writer.

​

Prerequisites

For PowerSync Cloud, make the writer publicly accessible over IPv4 and allow inbound traffic from PowerSync’s IP addresses on the database port (3306 by default). Apply the same network settings to reader instances that can become the writer. Private Endpoints are not currently supported for MySQL.

1

Configure a DB Cluster Parameter Group

In the Amazon RDS console, open the DB cluster parameter group linked from your cluster’s Configuration tab. If the cluster uses a default group, create a custom DB cluster parameter group with the family that matches your Aurora MySQL version. Default parameter groups cannot be edited.

Set these parameters to enable binary logging and global transaction identifiers (GTIDs):

Parameter in the AWS Console	Required Value
binlog_format	ROW
binlog_row_image	FULL
enforce_gtid_consistency	ON
gtid-mode	ON

Aurora enables binary logging through binlog_format. You do not need to configure log_bin or server_id separately. The AWS console calls the GTID parameter gtid-mode; its SQL variable is gtid_mode.

2

Apply the Parameter Group

If you created a new parameter group, assign it to the cluster through Modify in the RDS console. Save your changes and reboot the writer for the settings to take effect. If reader instances do not restart with the writer, reboot them manually to apply the same settings.

3

Verify the Settings

Connect to the writer through the cluster endpoint and run this query:

SELECT
  @@GLOBAL.log_bin AS log_bin,                                   -- 1
  @@GLOBAL.gtid_mode AS gtid_mode,                               -- ON
  @@GLOBAL.enforce_gtid_consistency AS enforce_gtid_consistency, -- ON
  @@GLOBAL.binlog_format AS binlog_format,                       -- ROW
  @@GLOBAL.binlog_row_image AS binlog_row_image;                 -- FULL

4

Set Binlog Retention

Set binlog retention long enough to cover the initial snapshot and expected downtime or replication lag. If required binlogs are purged before PowerSync reads them, PowerSync must take a new snapshot.Replace 24 with the number of hours your workload requires:

CALL mysql.rds_set_configuration('binlog retention hours', 24);

Monitor storage usage after increasing retention.

5

Create a PowerSync Database User

Follow Database User Configuration to create a user with replication privileges and read access to the tables you want to sync.

​

Binlog Configuration

• server_id: Uniquely identifies the MySQL server instance in the replication topology. Default value is 1.
• log_bin: ON. Enables binary logging. Default is ON for MySQL 8.0 and later, but OFF for MySQL 5.7.
• enforce_gtid_consistency: ON. Enforces GTID consistency. Default is OFF.
• gtid_mode: ON. Enables GTID based logging. Default is OFF.
• binlog_format: ROW. Sets the binary log format to row-based replication. This is required for PowerSync to correctly replicate changes. Default is ROW.
• binlog_row_image: FULL. Captures the complete row data for each change. This is required for PowerSync to correctly replicate changes. Default is FULL. The MINIMAL/NOBLOB options will be supported in a future release.

server_id=<Unique Integer Value>
log_bin=ON
enforce_gtid_consistency=ON
gtid_mode=ON
binlog_format=ROW
binlog_row_image=FULL

​

Database User Configuration

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

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

-- Grant select access to the specific database
GRANT SELECT ON <source_database>.* TO 'repl_user'@'%';

-- Apply changes
FLUSH PRIVILEGES;

-- Grant select to the users and the invoices tables in the source database
GRANT SELECT ON <source_database>.users TO 'repl_user'@'%';
GRANT SELECT ON <source_database>.invoices TO 'repl_user'@'%';

-- Apply changes
FLUSH PRIVILEGES;

​

Additional Configuration (Optional)

​

Binlog

• binlog-do-db: Only updates for tables in the specified database will be logged.
• binlog-ignore-db: No updates for tables in the specified database will be logged.

# Only row events for tables in the user_db and invoices_db databases will appear in the binlog.
binlog-do-db=user_db
binlog-do-db=invoices_db

# Row events for tables in the user_db will be ignored. Events for any other database will be logged.
binlog-ignore-db=user_db

​

SQL Server

• Change Data Capture (SQL Server)
• Change Data Capture (Azure SQL Database)

​

Supported Editions/Versions

​

Limitations / Known Issues

• Schema changes are not adopted automatically. Adopting a schema change requires deploying an updated Sync Config. See SQL Server Specifics for the recommended workflows.
• There is an inherent latency in replicating data from SQL Server to PowerSync. See Latency for more details.
• Spatial data types are returned as JSON objects as supplied by the Tedious node-mssql client. See the notes here.
• Wildcard table names (%) are not supported. Every replicated table must be listed by name in your Sync Streams.

​

Database Setup Requirements

​

1. Enable CDC on the Database

-- Enable CDC on the database if not already enabled
USE <YOUR_DATABASE_NAME>; -- Only for SQL Server. To switch databases on Azure SQL, you have to connect to the specific database.
IF (SELECT is_cdc_enabled FROM sys.databases WHERE name = '<YOUR_DATABASE_NAME>') = 0
BEGIN
    EXEC sys.sp_cdc_enable_db;
END

​

2. Create the PowerSync Database User

• Read/Write permissions on the _powersync_checkpoints table
• Read permissions on the replicated tables
• cdc_reader role (grants access to CDC changetables and functions)
• SELECT permission on the CDC schema (grants access to CDC metadata tables)
• VIEW DATABASE PERFORMANCE STATE (SQL Server and Azure SQL)
• VIEW SERVER PERFORMANCE STATE (SQL Server only)

-- Create a SQL login for the powersync_user if missing. Note SQL Logins are created at the server level.
USE [master]; -- Use only works on SQL Server. For Azure SQL you have to connect to the master database to run these commands.
IF NOT EXISTS (SELECT 1 FROM sys.server_principals WHERE name = 'powersync_user')
BEGIN
    CREATE LOGIN [powersync_user] WITH PASSWORD = 'YOUR_DB_USER_PASSWORD', CHECK_POLICY = ON;
END

-- Create the powersync_user database user if missing. Note DB users are created at the database level.
USE [<YOUR_DATABASE_NAME>]; -- Use only works on SQL Server. For Azure SQL you have to connect to the specific database to run these commands.
IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE name = 'powersync_user')
BEGIN
    CREATE USER [powersync_user] FOR LOGIN [powersync_user];
END

-- Grant SELECT on the specific replicated tables
GRANT SELECT ON dbo.<YOUR_TABLE_NAME> TO [powersync_user];

-- Grant access to CDC tables and functions using the cdc_reader role
IF IS_ROLEMEMBER('cdc_reader', 'powersync_user') = 0
BEGIN
    ALTER ROLE cdc_reader ADD MEMBER powersync_user;
END

-- Grant select on the CDC schema
GRANT SELECT ON SCHEMA::cdc TO [powersync_user];

-- Grant the necessary permissions to the user to access the performance state views

-- Note: For Azure SQL, only VIEW DATABASE PERFORMANCE STATE is required. Granted at the database level.
-- PowerSync uses this to access the sys.dm_db_log_stats DMV and the sys.dm_db_partition_stats DMV
GRANT VIEW DATABASE PERFORMANCE STATE TO [powersync_user];

-- VIEW SERVER PERFORMANCE STATE is only necessary on SQL Server (not Azure SQL). Granted at the server/master database level.
-- PowerSync requires this permission to access the sys.dm_db_log_stats DMV on SQL Server.
USE [master];
BEGIN
    GRANT VIEW SERVER PERFORMANCE STATE TO [powersync_user];
END

​

3. Create the PowerSync Checkpoints Table

-- Create the PowerSync checkpoints table in your schema
IF OBJECT_ID('dbo._powersync_checkpoints', 'U') IS NULL
BEGIN
CREATE TABLE dbo._powersync_checkpoints (
    id INT IDENTITY PRIMARY KEY,
    last_updated DATETIME NOT NULL DEFAULT GETUTCDATE()
);
END

-- Enable CDC for the powersync checkpoints table if not already enabled
-- Note: the cdc_reader role created the first time CDC is enabled on a table
IF NOT EXISTS (SELECT 1 FROM cdc.change_tables WHERE source_object_id = OBJECT_ID(N'dbo._powersync_checkpoints'))
BEGIN
    EXEC sys.sp_cdc_enable_table
        @source_schema = N'dbo',
        @source_name   = N'_powersync_checkpoints',
        @role_name     = N'cdc_reader',
        @supports_net_changes = 0;
END

GRANT SELECT, INSERT, UPDATE ON dbo._powersync_checkpoints TO [powersync_user];

​

4. Enable CDC on Tables

-- Enable CDC for specific tables in your schema if not already enabled
IF NOT EXISTS (SELECT 1 FROM cdc.change_tables WHERE source_object_id = OBJECT_ID(N'dbo.<YOUR_TABLE_NAME>'))
BEGIN
    EXEC sys.sp_cdc_enable_table
        @source_schema = N'dbo',
        @source_name   = N'<YOUR_TABLE_NAME>',
        @role_name     = N'cdc_reader',
        @supports_net_changes = 0;
END

​

CDC Management

• Polling Interval: The frequency at which the capture job reads changes from the transaction log. Default is every 5 seconds. Can be set to 0 so that there is zero downtime between scans, but this will impact database performance.
• Max Trans: The maximum number of transactions that are processed per scan. Default is 500.
• Max Scans: The maximum number of scans that are performed per capture job scan cycle. Default is 10.

• Retention: The retention period before data is expired from the CDC tables. Default is 3 days. If your PowerSync instance is offline for longer than this period, data will need to be fully re-synced. Specified in minutes.

​

Latency

1. Transaction Log Scan Interval: The frequency at which the CDC capture job scans the transaction log for changes. The default value of 5 seconds can be changed by modifying the capture job settings on SQL Server. The recommended value is 1 second, but this can also be set to 0 based on the database load. For Azure SQL Database, the default value is 20 seconds and cannot be changed. See Azure CDC Customization Limitations for more details.
2. Polling Interval: The frequency at which PowerSync polls the CDC change tables for changes. The default value is once every 1000ms. This can be changed by setting the pollingIntervalMs parameter in the PowerSync configuration.

​

Memory Management

​

Convex

​

Connection Requirements

• A Convex deployment URL.
• A Convex deploy key. In the Convex Dashboard, go to Settings → General and generate a deploy key for the deployment PowerSync should replicate. Create the key with Custom permissions and include deployment:data:view; the Deploy only option does not work for PowerSync replication.
• The powersync_checkpoints table and createCheckpoint mutation described below.

​

Checkpoint Table

import { defineSchema, defineTable } from 'convex/server';
import { v } from 'convex/values';

export default defineSchema({
  // ... your other tables

  powersync_checkpoints: defineTable({
    last_updated: v.float64()
  })
});

​

Checkpoint Mutation

import { mutation } from './_generated/server';

export const createCheckpoint = mutation({
  args: {},
  handler: async (ctx) => {
    const existing = await ctx.db.query('powersync_checkpoints').first();

    if (existing) {
      await ctx.db.patch(existing._id, { last_updated: Date.now() });
    } else {
      await ctx.db.insert('powersync_checkpoints', { last_updated: Date.now() });
    }
  }
});

​

Latency

replication:
  connections:
    - type: convex
      deployment_url: https://<your-deployment>.convex.cloud
      deploy_key: <your-deploy-key>
      polling_interval_ms: 1000
      request_timeout_ms: 60000

​

Client ID Mapping

​

Client Writes

​

Demo App

​

Next Step