Configure Your Instance
A self-hosted instance needs four things before clients can sync:- A connection to your source database, which PowerSync replicates data from.
- A bucket storage database, where the PowerSync Service stores the data it prepares for syncing to clients. MongoDB and Postgres are supported.
- Client authentication. When getting started, you can use temporary development tokens instead of setting up a full auth provider.
- A sync configuration defining what data syncs to which clients, written as Sync Streams.
service.yaml
Example service.yaml
The config used by the Node.js (Postgres) demo in
self-host-demo. Similar examples exist for MongoDB, MySQL, and SQL Server. Use the demos as a working reference for your own setup.Supplying the Config File
Both YAML and JSON config files are supported. The PowerSync Service can read the config in three ways:- From a config file mounted on a volume
- From an environment variable containing the Base64 encoding of the config file
- From a command line parameter (also Base64 encoded)
self-host-demo app.
Environment Variable Substitution
The config file uses custom tags for environment variable substitution.!env [variable name] substitutes the value of the environment variable named [variable name]. For example, with the environment variable PS_MONGO_URI=mongodb://mongo:27017/powersync, the YAML
service.yaml
uri: mongodb://mongo:27017/powersync.
Only environment variables with names starting with PS_ can be substituted.
Substituted values are strings. For options that expect a number or boolean, append ::number or ::boolean to the variable name to cast the value. A ::boolean cast accepts true or false.
service.yaml
Service Commands
Each container that uses the PowerSync Service Docker image runs one command. The command determines which part of the Service runs in that container. If you do not set a command, the image runsstart.
The
-r option, or --runner-type, sets the runner type for start. You can also set the runner type with the PS_RUNNER_TYPE environment variable. The -r option takes precedence over the environment variable.
The unified and sync runner types apply storage migrations on startup, unless disable_auto_migration is true. The api runner type never applies migrations. If you run API and replication in separate containers, the replication container or a separate migrate up job applies them.
All commands read the config file in the ways that Supplying the Config File describes.
Setting the Command
The command is a list of arguments to the image’s entrypoint. Withdocker run, put the arguments after the image name. On other platforms, set the arguments in the field that overrides the image’s default command. Docker Compose and AWS ECS name this field command. Kubernetes names it args.
Configuration Reference
The config file supports the following top-level keys, documented in the sections below:replication
The replication section defines the source database that PowerSync replicates data from. Specify the connection details in replication.connections. Only one connection is currently supported; multiple connection support is on our roadmap.
For instructions on preparing your source database, see Source Database Setup.
Hosted Supabase only allows direct database connections over IPv6, and PowerSync cannot connect using the connection pooler. You can:
- Enable IPv6 for Docker as per the Docker docs.
- Enable IPv4 on your Supabase project.
- Run Supabase locally.
Unique identifier for the connection. Optional when only a single connection is present.
Postgres connection options
Postgres connection options
service.yaml
Connection URI in the format
postgresql://user:password@hostname:5432/database. Individual connection parameters take precedence over values in the URI.SSL mode:
verify-full, verify-ca, or disable. disable is only suitable for local/private networks, not for public networks.Prefix for Postgres logical replication slot names and replication stream names.
Connection timeout in seconds. Takes precedence over a
connect_timeout query parameter in the URI.Idle timeout in seconds for snapshot connection sockets. If the storage database cannot keep up during the initial snapshot, a storage flush can stall the snapshot for longer than this timeout, which closes the source connection mid-snapshot. This appears in the Service logs as
Socket timed out errors during the initial snapshot. Increase the timeout if you see these errors. Available since Service version 1.26.0.MongoDB connection options
MongoDB connection options
service.yaml
Connection URI in the format
mongodb:// or mongodb+srv://. Standard connection options such as connectTimeoutMS, socketTimeoutMS, serverSelectionTimeoutMS, maxPoolSize and maxIdleTimeMS can be set as query parameters in the URI.Controls how change stream post-images are used:
off, auto_configure, or read_only. auto_configure is recommended for new instances. See Post Images for details on each option.MySQL connection options
MySQL connection options
MySQL support is currently in a Beta release.
service.yaml
Connection URI in the format
mysql://user:password@hostname:3306/database. Individual connection parameters take precedence over values in the URI.SQL Server connection options
SQL Server connection options
SQL Server support is currently in a Beta release. Also see SQL Server Additional Configuration.
service.yaml
Connection URI in the format
mssql://user:password@hostname:1433/database. Individual connection parameters take precedence over values in the URI.Use a servername for TLS that is different from
hostname. Available since Service version 1.25.0.Convex connection options
Convex connection options
The Convex replicator is currently released as an experimental feature and is available since Service version v1.22.0. See Convex source database setup.
service.yaml
A deploy key for the Convex deployment, used to authenticate against the Convex Streaming Export API.
storage
The PowerSync Service requires a storage database to store the data and metadata for buckets. You can use either MongoDB or Postgres for this purpose.
The bucket storage database is separate from your source database.
Storage version to use when deploying a Sync Config that does not specify a storage version. When unset, MongoDB bucket storage uses storage version 4 and Postgres bucket storage uses version 2. Service versions 1.26.x default to version 2. An explicit
config.storage_version takes precedence over this default. Available since Service version 1.26.0.Postgres bucket storage does not currently support version 4.
MongoDB Storage
service.yaml
Database username. Defaults to the username in the URI. See Required Permissions below for the roles the user needs.
Sets replication batch targets for MongoDB bucket storage:
small, medium, or large. Applies to all MongoDB storage versions. Available since Service version 1.29.0.Use small in memory-constrained environments. large doubles the batch targets of medium, allowing more operations per transaction and fewer storage round trips, at the cost of higher memory usage and larger transactions.These targets are estimates, not hard memory or transaction size limits.Throttles the clearing of old bucket data after deploying a new sync configuration, by pausing between batches. The pause is proportional to the previous batch duration. Increase this to reduce the impact of clear operations on the storage cluster, or use
0 to clear as fast as possible. Must be between 0 and 20. Available since Service version 1.24.0.Read preference for bulk checksum and bucket data reads:
primary, primaryPreferred, secondary, secondaryPreferred, or nearest. If unset, MongoDB driver defaults are used. This is an experimental option and may be removed in a future release. Available since Service version 1.23.2.Read preference for collection storage statistics:
primary, primaryPreferred, secondary, secondaryPreferred, or nearest. If unset, MongoDB driver defaults are used. Not relevant for most self-hosted deployments. Available since Service version 1.28.2.Maximum number of buckets that chunk-merge compaction processes at the same time on storage version 4. Defaults to
4 when object_storage is configured, otherwise 2. Must be between 1 and 64. Full compaction still processes one bucket at a time.Chunk-merge compaction runs after initial replication, before the new Sync Config becomes active, and as part of scheduled compact runs. With object storage, request latency, not processing, takes most of the time per bucket. A higher value lets the Service merge more buckets during those waits, which shortens the delay before activation. All compaction jobs in a Service process share this limit. Available since Service version 1.26.1.Stores large blocks of bucket data in Amazon S3 or an S3-compatible object store instead of MongoDB. Requires Service version 1.26.0 or later with storage version 4, the default since Service version 1.27.0. Sync Configs on version 2 keep all data in MongoDB even when this is configured.Follow Self-Hosted S3 Setup to create the bucket, configure permissions and lifecycle settings, and enable object storage in the Service. The fields below describe the available configuration options.
Required Permissions
The Service creates and manages all collections and indexes in the storage database itself, so no manual schema setup is needed. When authentication is enabled, the user needs the built-inreadWrite and dbAdmin roles on the storage database:
readWrite role covers regular operation, including creating and dropping collections and indexes. The dbAdmin role is additionally needed to drop the database when an instance is torn down.
Create the user with:
admin, add authSource=admin to the connection URI. On MongoDB Atlas, assign the same two roles restricted to the storage database.
Replica Set Requirement
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 deployments. 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:docker-compose file to configure a replica set as once-off operation:
docker-compose.yaml
Postgres Storage
You can use Postgres as an alternative bucket storage database.service.yaml
uri, hostname, port, username, password, database, sslmode, cacert, client_certificate, client_private_key, tls_servername and connect_timeout. In addition, batch limits can be tuned:
Limits for batch operations during replication. Increasing these limits can improve replication performance, at the cost of higher memory usage.
Database Setup
You’ll need to create a dedicated user and schema for PowerSync bucket storage. You can either:- Let PowerSync create the schema (recommended):
- Or manually create the schema:
Postgres Version Requirements
Separate Postgres servers are required for replication connections (i.e. source database) and bucket storage if using Postgres versions below 14.port
The port setting determines where clients and tools connect to your instance. Change it if the default conflicts with another service in your deployment.
The port on which the PowerSync API server will listen for connections. Can be specified as a number or string.
sync_config
The sync_config section points the Service at your Sync Streams definition, usually a separate file referenced with path:
Path to the sync configuration YAML file. Ensure the file is available at that path, e.g. in the same directory as your main config or on a mounted volume.
Whether to exit the process when the configured Sync Config has a parsing error or a fatal validation error, such as using a feature that the source does not support.Since Service version 1.28.0, setting this to
false keeps the Service running without storing, replicating, or serving the rejected config to clients. Pending config processing stops, while any previous active config continues replicating and serving clients. Inspect deploying_sync_rules.errors[] in the Diagnostics API to identify and correct the errors.sync_rules key is a deprecated alias for sync_config. Use sync_config in new configurations.
client_auth
The client_auth section defines how the Service verifies your app’s users when they connect to sync. Clients authenticate with JWTs, which the Service validates using the settings here. For more details, see Client Authentication.
service.yaml
URI or array of URIs pointing to JWKS endpoints, used to fetch public keys for JWT verification.
Enables Supabase authentication integration. JWKS details are derived from the Supabase connection. See Supabase Auth.
For production environments, we recommend using JWKS with asymmetric keys (RS256, EdDSA, or ECDSA) rather than shared secrets (HS256). Asymmetric keys provide better security through public/private key separation and easier key rotation. See Custom Authentication for more details.
api
The api section protects the Service’s admin API routes with access tokens, and sets limits that protect the Service from excessive load. Configure tokens if you use the PowerSync CLI against this instance; the limits rarely need changing.
Access tokens for the Service’s admin API routes, provided by clients as a Bearer token. If no tokens are configured, the admin API routes reject all requests.
telemetry
The telemetry section controls the operational metrics the Service shares with PowerSync and exposes for your own monitoring. See Usage Reporting and Monitoring for details.
When
true, disables sharing of anonymized usage metrics with the PowerSync telemetry service.Port on which Prometheus metrics will be exposed. When set, metrics will be available on this port for scraping.
healthcheck
Configures how health check status is exposed. See Health Checks for details on the available probes and endpoints.
Mechanisms for exposing health check data. If this is not configured, the Service defaults to legacy behavior for backwards compatibility (filesystem probes always enabled, plus HTTP probes depending on the Service mode). When
probes is configured, each mechanism requires explicit opt-in.migrations
The migrations section controls whether the Service updates its bucket storage database schema automatically when a new version starts up. Most deployments can keep the default automatic behavior.
When
true, disables automatic storage database schema migrations on startup. Run migrations yourself with the migrate up command.system
The system section configures how the Service itself runs. Currently this covers logging.