PowerSync Service Setup
Configuration details for connecting the PowerSync Service to your database
After configuring your source database for PowerSync, you’ll need to setup your PowerSync Service.
This entails:
-
Configuring sync bucket storage
-
Defining your PowerSync config
-
Defining connections to your source database, and sync bucket storage database
-
Defining your Sync Rules
-
Defining your auth method
-
Examples of the above can be found in our demo application here. Below we go through these in more detail.
Deploy PowerSync on Coolify: See our integration guide for deploying the PowerSync Service on Coolify. This can simplify the setup and management of the deployment.
Configure Sync Bucket Storage
The PowerSync Service requires a storage backend for sync buckets. You can use either MongoDB or Postgres for this purpose. The storage backend is separate from your source database.
MongoDB Storage
MongoDB requires at least one replica set node. A single node is fine for development/staging environments, but a 3-node replica set is recommended for production.
MongoDB Atlas enables replica sets by default for new clusters.
However, if you’re using your own environment you can enable this manually by running:
If you are rolling your own Docker environment, you can include this init script in your docker-compose file to configure a replica set as once-off operation:
Postgres Storage (Beta)
Available since version 1.3.8 of journeyapps/powersync-service
, you can use Postgres as an alternative storage backend for sync buckets. This feature is currently in beta.
Database Setup
You’ll need to create a dedicated user and schema for PowerSync storage. You can either:
- Let PowerSync create the schema (recommended):
- Or manually create the schema:
Demo app: A demo app with Postgres bucket storage is available here.
PowerSync Configuration
The PowerSync Service is configured using key/value pairs in a config file, and supports the following configuration methods:
-
Inject config as an environment variable (which contains the base64 encoding of a config file)
-
Use a config file mounted on a volume
-
Specify the config as a command line parameter (again base64 encoded)
Both YAML and JSON config files are supported, and you can see examples of the above configuration methods in our demo app’s docker-compose file.
A detailed config.yaml
example with additional comments can be found here:
self-host-demo/config/powersync.yaml at main · powersync-ja/self-host-demoGitHub
The config file schema is also available here:
self-host-demo/schema/schema.json at main · powersync-ja/self-host-demoGitHub
Below is a skeleton config file you can copy and paste to edit locally:
Specify the connection to Postgres in the replication
section. Retrieving your database connection string / individual parameters differs by database hosting provider. See Database Connection for further details.
If you are using hosted Supabase, you will need to enable IPv6 for Docker as per https://docs.docker.com/config/daemon/ipv6/
If your host OS does not support Docker IPv6 e.g. macOS, you will need to run Supabase locally.
This is because Supabase only allows direct database connections over IPv6 — PowerSync cannot connect using the connection pooler.
Specify the connection to your sync bucket storage provider (Postgres or MongoDB) in the storage
section.
Postgres Storage
Separate Postgres servers are required for replication connections and sync bucket storage if using Postgres versions below 14.
Postgres Version | Server configuration |
---|---|
Below 14 | Separate servers are required for the source and sync bucket storage. Replication will be blocked if the same server is detected. |
14 and above | The source database and sync bucket storage database can be on the same server. Using the same database (with separate schemas) is supported but may lead to higher CPU usage. Using separate servers remains an option. |
Environment Variables
The config file uses custom tags for environment variable substitution.
Using !env [variable name]
will substitute the value of the environment variable named [variable name]
.
Only environment variables with names starting with PS_
can be substituted.
See examples here:
self-host-demo/config/powersync.yaml at main · powersync-ja/self-host-demoGitHub
Sync Rules
Your project’s sync rules can either be specified within your configuration file directly, or in a separate file that is referenced.
We recommend starting with syncing a single table in a global bucket. Choose a table and sync it by adding the following to your sync rules:
For more information about sync rules see:
Checkpoint
To verify that your sync rules are functioning correctly, inspect the contents of your sync bucket in MongoDB.
If you are running MongoDB in Docker, run the following:
Was this page helpful?