Source Database Setup
Configure your backend database for PowerSync
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:
For other providers and self-hosted databases:
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:
To allow PowerSync to automatically enable changeStreamPreAndPostImages
on
replicated collections, additionally add the dbAdmin
permission:
If you are replicating from multiple databases in the cluster, you need read permissions on the entire cluster, in addtion to the above:
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: ""
.
- This must apply to the entire database, not individual collections,
- On each collection being replicated:
find
. - On the
_powersync_checkpoints
collection:createCollection
,dropCollection
,find
,changeStream
,insert
,update
, andremove
. - To allow PowerSync to automatically enable
changeStreamPreAndPostImages
on replicated collections, additionally add thecollMod
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
: UsesfullDocument: '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 thechangeStreamPreAndPostImages
option on collections as needed. Requires the permissions/privileges mentioned above. -
post_images: read_only
: UsesfullDocument: 'required'
and requireschangeStreamPreAndPostImages: { 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:
You can view which collections have the option enabled using:
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:
Next Step
Next, connect PowerSync to your database:
Self-hosting: If you are self-hosting PowerSync, refer to PowerSync Service Setup next.
Was this page helpful?