Skip to main content

Minimal Setup

For a runnable development setup, use the self-hosting examples, which include Docker Compose files and configuration. For development and testing, use:
  1. One PowerSync container running in unified mode (API and replication): 1 vCPU, 512 MiB memory.
  2. A MongoDB or Postgres bucket storage database. For MongoDB, use one node in replica set mode: 1 vCPU, 2 GiB memory (M10+ on Atlas).
  3. A load balancer for TLS.
This setup has no redundancy. If bucket storage data is lost, re-replicate from the source database. All clients must then download their data again.

Production

Run API and replication in separate containers so you can scale them independently.

Storage Requirements

You can use MongoDB or Postgres for bucket storage, independently of your source database: With S3 object storage, S3 stores larger blocks of sync data while MongoDB retains smaller blocks and metadata.

Compute Sizing

Use these CPU and memory settings as a starting point. These may be scaled up or down depending on your specific load patterns.

Replication Container

Run start -r sync to replicate source changes into bucket storage. Only one process can replicate from the source database at a time. Running multiple replication containers provides failover, not more throughput. It is recommended to run 2 replication processes for failover purposes. During rolling deploys or failover, PSYNC_S1003 is expected briefly while another process holds the replication lock. Size replication for source database write volume, row size, and buckets per row. A row in ten buckets creates more replication work than a row in one bucket. Initial replication and catch-up after a large batch update can need more capacity than steady-state replication. Use replication lag, replication throughput, CPU, memory, and database metrics to assess capacity.

API Containers

Run at least two API containers in production for high availability. Scale horizontally by adding API containers as the concurrent client load grows. Run start -r api for client connections. Collect metrics separately from API and replication containers. The max_concurrent_connections config parameter determines the maximum number of concurrent client connections that each API process can handle. The default is 200. We recommend keeping autoscaling targets below the max_concurrent_connections limit (e.g. ~100 concurrent connections per API process) to allow for headroom.
Depending on the use case, handling up to 1,000 concurrent clients per API process is possible. Contact us to discuss your specific requirements and we will recommend an optimal setup.
Scale on both CPU utilization and concurrent connections per API process. Idle connections can keep CPU low, while initial syncs can saturate CPU with fewer connections. Add API containers before many clients are expected to run an initial sync at once, or before deployments that make clients redownload all their data again. Wait for the new containers to become healthy before those initial syncs or deployments begin. Adding containers does not immediately redistribute existing long-lived connections. Reduce capacity gradually after the download load subsides.

Compact Job

Run compact as a separate scheduled job, hourly for storage version 4 or daily for storage version 2. Compaction resources depend on bucket size, accumulated changes, and concurrency. Monitor completion, duration, CPU, and peak memory to size the job for your dataset. If jobs fail or overlap, check the compact job’s CPU and memory usage and bucket storage performance before changing resources or the schedule. See Compacting Buckets.

Memory Configuration

Set the environment variable NODE_OPTIONS=--max-old-space-size-percentage=80 for the API, replication, and compact containers. This allocates 80% of the container’s assigned memory to the Node.js heap. This avoids manually retuning when scaling resources up or down.

Load Balancer

Use a redundant load balancer to terminate TLS and distribute connections across API containers. Host the API on a dedicated subdomain. For HTTP streaming with nginx, add this proxy block to your TLS server configuration. Replace powersync:8080 with your PowerSync API hostname and port. Disabling response buffering lets sync data reach clients as it arrives.
For nginx Kubernetes ingress, use this annotation:

Health Checks

Configure load-balancer health checks to poll /probes/liveness. See Health Checks.

Migrations

Occasionally, new versions of the PowerSync Service image may require migrations on the underlying storage database. This is also specifically required the first time the service starts up on a new storage database. Replication containers run storage migrations on startup. Unified containers, which run both API and replication, also run them. API containers do not run migrations. Large migrations can delay startup during an update. To run migrations as a separate job before replacing the containers, disable automatic migrations:
service.yaml
Then run migrate up as a separate job before each deployment, including the first.

Backups

Keep non-secret configuration in version control and credentials in a secrets manager. None of the containers use any local storage, so no backups are required there. Recover PowerSync’s sync data by re-replicating from the source database. Allow for the time and capacity needed for full replication and for clients to download their data again.

Self-Hosted Architecture Diagram

The diagram omits S3 object storage.
Source database changes flow through replication and bucket storage to API containers, a TLS load balancer, and clients. Client writes go through the app backend.

PowerSync Deployment Architecture