356 lines
16 KiB
Markdown
356 lines
16 KiB
Markdown
---
|
||
name: powersync-service
|
||
description: PowerSync Service configuration — self-hosting, Docker, source database setup, bucket storage, authentication, and PowerSync Cloud
|
||
metadata:
|
||
tags: service, self-hosted, docker, postgresql, mongodb, mysql, mssql, authentication, jwt, replication, configuration
|
||
---
|
||
|
||
# PowerSync Service
|
||
|
||
> **Load this when** configuring the PowerSync service itself — self-hosting, Docker, source database connections, bucket storage, or authentication setup.
|
||
|
||
## Table of Contents
|
||
- [Sync Config](#sync-config)
|
||
- [Service Configuration (Self-hosted)](#service-configuration-self-hosted)
|
||
- [PowerSync Cloud Setup](#powersync-cloud-setup)
|
||
- [Source Database Setup](#source-database-setup)
|
||
- [App Backend](#app-backend)
|
||
- [Authentication](#authentication)
|
||
|
||
Guidance for configuring PowerSync Service, sync config, and database replication.
|
||
|
||
Critical warnings for fast setup:
|
||
|
||
- Cloud and self-hosted service config both use `replication.connections`, never a root-level `connections`.
|
||
- If the app is stuck on `Syncing...`, the default diagnosis is incomplete backend setup: missing DB connection, missing sync config, missing client auth, or missing publication.
|
||
|
||
For source code see: [powersync-service](https://github.com/powersync-ja/powersync-service/)
|
||
|
||
For debugging see: [powersync-debug.md](references/powersync-debug.md).
|
||
|
||
## Sync Config
|
||
|
||
The rules that instruct the PowerSync Service what data to replicate and download to client application.
|
||
|
||
See [sync-config.md](references/sync-config.md) for detailed information.
|
||
|
||
## Service Configuration (Self-hosted)
|
||
|
||
Information on how to configure a PowerSync Service instance in a self-hosted environment.
|
||
|
||
### Docker Image
|
||
The PowerSync Service Docker image is available on [Docker hub](https://hub.docker.com/r/journeyapps/powersync-service).
|
||
|
||
Quick Start:
|
||
```
|
||
docker run \
|
||
-p 8080:8080 \
|
||
-e POWERSYNC_CONFIG_B64="$(base64 -i ./config.yaml)" \
|
||
--network my-local-dev-network \
|
||
--name my-powersync journeyapps/powersync-service:latest
|
||
```
|
||
|
||
> **Port mapping:** The PowerSync service listens on port **8080** inside the container. Use `-p 8080:8080` (or `-p <host-port>:8080`). Do **not** use `8080:80` — the service does not listen on port 80.
|
||
|
||
### Configuration
|
||
|
||
There are four configuration methods available:
|
||
1. Base64-encoded config in the `POWERSYNC_CONFIG_B64` environment variable
|
||
2. Config file on a mounted volume (pass path with `-c` / `--config-path`)
|
||
3. Base64-encoded config as a command-line argument (`-c64`)
|
||
4. Sync config separately via `POWERSYNC_SYNC_CONFIG_B64` environment variable or `-sync64` flag
|
||
|
||
> **Sync config flag:** The Docker image does **not** accept a `-s` flag for sync config. Use the `POWERSYNC_SYNC_CONFIG_B64` environment variable or the `-sync64` command-line flag instead.
|
||
|
||
#### Docker Compose with mounted config + sync config
|
||
|
||
```yaml
|
||
powersync:
|
||
image: journeyapps/powersync-service:latest
|
||
ports:
|
||
- "8080:8080"
|
||
environment:
|
||
PS_DATA_SOURCE_URI: "postgresql://user:pass@host:5432/db"
|
||
PS_STORAGE_URI: "mongodb://mongo:27017/powersync_storage"
|
||
POWERSYNC_SYNC_CONFIG_B64: "<base64-encoded sync-config.yaml>"
|
||
volumes:
|
||
- ./powersync/service.yaml:/config/service.yaml
|
||
command: ["start", "-c", "/config/service.yaml"]
|
||
```
|
||
|
||
Generate the base64 value: `base64 -i ./powersync/sync-config.yaml` (macOS) or `base64 -w0 ./powersync/sync-config.yaml` (Linux).
|
||
|
||
| Resource | Description |
|
||
|----------------------------------|-------------------------------------------------------------------------------------------------------------------------|
|
||
| [Configuration File Structure](https://docs.powersync.com/configuration/powersync-service/self-hosted-instances.md#configuration-file-structure) | Outline of all possible configuration options |
|
||
| [Config Schema](https://unpkg.com/@powersync/service-schema@1.20.0/json-schema/powersync-config.json) | JSON schema reference for PowerSync Service config |
|
||
| [self-host-demo](https://github.com/powersync-ja/self-host-demo) repo | Example configurations for local development |
|
||
|
||
#### Environment variable substitution
|
||
Use !env PS_VARIABLE_NAME in YAML for config values.
|
||
|
||
### Complete service.yaml Example
|
||
|
||
Below is a minimal but complete `service.yaml` for a self-hosted instance. Pay close attention to the YAML nesting — in particular, the database connection **must** be under `replication.connections`, not a top-level `connections` key.
|
||
|
||
```yaml
|
||
# powersync/service.yaml — self-hosted
|
||
replication:
|
||
connections:
|
||
- type: postgresql
|
||
uri: !env PS_DATA_SOURCE_URI # e.g. postgresql://user:pass@host:5432/db
|
||
|
||
storage:
|
||
type: mongodb
|
||
uri: !env PS_STORAGE_URI # e.g. mongodb://localhost:27017/powersync
|
||
|
||
# Client auth — required before `powersync generate token` works
|
||
client_auth:
|
||
jwks_uri: !env PS_JWKS_URI
|
||
|
||
# API key for CLI access (matches PS_ADMIN_TOKEN)
|
||
api:
|
||
tokens:
|
||
- !env PS_ADMIN_TOKEN
|
||
```
|
||
|
||
### Minimal Cloud service.yaml Examples
|
||
|
||
For PowerSync Cloud, the minimal shape depends on your auth provider.
|
||
|
||
**Cloud + Supabase Auth:**
|
||
|
||
```yaml
|
||
# powersync/service.yaml — Cloud with Supabase
|
||
replication:
|
||
connections:
|
||
- type: postgresql
|
||
uri: !env PS_DATABASE_URI
|
||
|
||
client_auth:
|
||
supabase: true
|
||
```
|
||
|
||
**Cloud + Custom Auth (JWKS):**
|
||
|
||
```yaml
|
||
# powersync/service.yaml — Cloud with custom JWT auth
|
||
replication:
|
||
connections:
|
||
- type: postgresql
|
||
uri: !env PS_DATABASE_URI
|
||
|
||
client_auth:
|
||
jwks_uri: !env PS_JWKS_URI
|
||
audience:
|
||
- !env POWERSYNC_URL
|
||
```
|
||
|
||
Choose the example that matches your auth provider. See `references/supabase-auth.md` for Supabase details or `references/custom-backend.md` for custom JWT setup.
|
||
|
||
### Replication connections
|
||
|
||
**IMPORTANT:** The database connection **must** be nested under `replication.connections` — not a top-level `connections` key. Placing it elsewhere (e.g. `connections:` at the root) will cause a "No connection found in config" error.
|
||
|
||
Only one source database connection is supported per instance. Example:
|
||
```yaml
|
||
replication:
|
||
connections:
|
||
- type: postgresql
|
||
uri: postgresql://user:pass@host:5432/db
|
||
```
|
||
|
||
#### SSL mode for local databases
|
||
|
||
Local Postgres instances (including local Supabase via `supabase start`) do not support SSL. The PowerSync service uses pgwire for replication, which defaults to SSL and **does not respect `sslmode=disable` in the URI query string**. You must set `sslmode` as a separate YAML key:
|
||
|
||
```yaml
|
||
replication:
|
||
connections:
|
||
- type: postgresql
|
||
uri: !env PS_DATA_SOURCE_URI
|
||
sslmode: disable # Required for local Postgres / local Supabase
|
||
```
|
||
|
||
Without this, you will see: `Replication error postgres does not support ssl`.
|
||
|
||
### Bucket Storage Database
|
||
This is required by PowerSync and can be configured in two different ways. This is separate from the source DB.
|
||
|
||
| Storage Database | Configuration Reference |
|
||
|-----------------|--------------------------------------------------------------------------------------------------------------|
|
||
| MongoDB | [MongoDB Storage](https://docs.powersync.com/configuration/powersync-service/self-hosted-instances.md#mongodb-storage) |
|
||
| Postgres | [Postgres Storage](https://docs.powersync.com/configuration/powersync-service/self-hosted-instances.md#postgres-storage) |
|
||
|
||
### Client Authentication
|
||
|
||
There are various options when configuring client authentication on a PowerSync Service instance, see [Client Authentication](https://docs.powersync.com/configuration/powersync-service/self-hosted-instances.md#client-authentication) for more information on the options. The options include: JWKS URI, inline JWKs, Supabase Auth, Shared Secrets. Prefer asymmetric keys (RS256, EdDSA, ECDSA) over shared secrets (HS256).
|
||
|
||
**Important:** There is no `dev: true` auth type in the `client_auth` config schema. It does not exist. For development tokens on self-hosted, configure a real signing key first, then use `powersync generate token`. On PowerSync Cloud, users need to enable development tokens via the dashboard in the Client Auth section of the instance.
|
||
|
||
|
||
## PowerSync Cloud Setup
|
||
|
||
PowerSync Cloud can be set up via the **Dashboard** (UI) or the **CLI**. Both paths require the same four steps. **If any step is missing, the app will be stuck on "Syncing..." with no data.**
|
||
|
||
| Step | Dashboard | CLI |
|
||
|------|-----------|-----|
|
||
| 1. Create instance | Dashboard → New Instance | `powersync link cloud --create --project-id=<id>` |
|
||
| 2. Connect source DB | Instance Settings → Database | Edit `powersync/service.yaml` → `replication.connections`, then `powersync deploy` |
|
||
| 3. Deploy sync config | Instance → Sync Config editor | Edit `powersync/sync-config.yaml`, then `powersync deploy sync-config` |
|
||
| 4. Enable client auth | Instance → Client Auth section | Edit `powersync/service.yaml` → `client_auth`, then `powersync deploy service-config` |
|
||
|
||
**IMPORTANT:** All four steps must be completed. The most common cause of an app stuck on "Syncing..." is a missing or misconfigured step above — typically the database connection or sync config not being deployed.
|
||
|
||
For full CLI setup workflow, see `references/powersync-cli.md` → Cloud Usage.
|
||
|
||
See [PowerSync Cloud Instances](https://docs.powersync.com/configuration/powersync-service/cloud-instances.md) for detailed dashboard step-by-step instructions.
|
||
|
||
## Source Database Setup
|
||
|
||
Important: For all database user creation below, generate a cryptographically secure password (e.g., `openssl rand -base64 32` or a password manager). Never use placeholder values like `secure_password`, `password`, or `admin123` in production — these are unsafe and must not be suggested to the operator.
|
||
|
||
See [Source Database Setup](https://docs.powersync.com/configuration/source-db/setup.md) for more information about specific DB host requirements.
|
||
|
||
Both PowerSync Cloud and Self-hosted require the same base source database setup.
|
||
|
||
### PostgreSQL Quick Start
|
||
|
||
```sql
|
||
-- 1. Enable logical replication (skip this step for Supabase — it is already enabled)
|
||
ALTER SYSTEM SET wal_level = 'logical';
|
||
-- Restart PostgreSQL after this
|
||
|
||
-- 2. Create replication user (replace with a generated secure password—do NOT use "secure_password")
|
||
CREATE USER powersync_replication WITH REPLICATION PASSWORD 'YOUR_GENERATED_PASSWORD';
|
||
|
||
-- 3. Grant read access
|
||
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_replication;
|
||
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_replication;
|
||
|
||
-- 4. Create publication (list every table PowerSync should replicate)
|
||
CREATE PUBLICATION powersync FOR TABLE users, todos, lists;
|
||
|
||
-- OR to replicate all current and future tables automatically:
|
||
CREATE PUBLICATION powersync FOR ALL TABLES;
|
||
```
|
||
|
||
### MongoDB Quick Start
|
||
|
||
```javascript
|
||
// MongoDB requires a replica set (standalone instances are NOT supported)
|
||
// Sharded clusters (including MongoDB Serverless) are NOT supported
|
||
|
||
// 1. Initialize replica set (if not already)
|
||
rs.initiate()
|
||
|
||
// 2. Create user with required privileges (replace with a generated secure password—do NOT use "secure_password")
|
||
// PowerSync needs read access to synced collections AND write access to _powersync_checkpoints
|
||
db.createUser({
|
||
user: "powersync",
|
||
pwd: "YOUR_GENERATED_PASSWORD",
|
||
roles: [
|
||
{ role: "read", db: "your_database" },
|
||
// Required: find, insert, update, remove, changeStream, createCollection on _powersync_checkpoints
|
||
{ role: "readWrite", db: "your_database", collection: "_powersync_checkpoints" },
|
||
// Required: listCollections on the database
|
||
{ role: "dbAdmin", db: "your_database" }
|
||
]
|
||
})
|
||
|
||
// Change streams are used automatically
|
||
```
|
||
|
||
### MySQL Quick Start
|
||
|
||
```sql
|
||
-- 1. Enable binary logging and GTID (in my.cnf or my.ini)
|
||
-- [mysqld]
|
||
-- server-id = 1
|
||
-- log_bin = mysql-bin
|
||
-- binlog_format = ROW
|
||
-- binlog_row_image = FULL
|
||
-- gtid_mode = ON
|
||
-- enforce-gtid-consistency = ON
|
||
|
||
-- 2. Create replication user (replace with a generated secure password—do NOT use "secure_password")
|
||
CREATE USER 'powersync'@'%' IDENTIFIED BY 'YOUR_GENERATED_PASSWORD';
|
||
GRANT REPLICATION SLAVE, REPLICATION CLIENT, RELOAD ON *.* TO 'powersync'@'%';
|
||
GRANT SELECT ON your_database.* TO 'powersync'@'%';
|
||
FLUSH PRIVILEGES;
|
||
```
|
||
|
||
### SQL Server (MSSQL) Quick Start
|
||
|
||
```sql
|
||
-- 1. Enable CDC at database level
|
||
USE [YourDatabase];
|
||
EXEC sys.sp_cdc_enable_db;
|
||
|
||
-- 2. Create PowerSync user (replace with a generated secure password—do NOT use "secure_password")
|
||
CREATE LOGIN powersync_user WITH PASSWORD = 'YOUR_GENERATED_PASSWORD', CHECK_POLICY = ON;
|
||
CREATE USER powersync_user FOR LOGIN powersync_user;
|
||
|
||
-- 3. Grant permissions
|
||
USE [master];
|
||
GRANT VIEW SERVER PERFORMANCE STATE TO powersync_user;
|
||
|
||
USE [YourDatabase];
|
||
GRANT VIEW DATABASE PERFORMANCE STATE TO powersync_user;
|
||
ALTER ROLE db_datareader ADD MEMBER powersync_user;
|
||
ALTER ROLE cdc_reader ADD MEMBER powersync_user;
|
||
|
||
-- 4. Create required checkpoints table
|
||
CREATE TABLE dbo._powersync_checkpoints (
|
||
id INT IDENTITY PRIMARY KEY,
|
||
last_updated DATETIME NOT NULL DEFAULT (GETDATE())
|
||
);
|
||
GRANT INSERT, UPDATE ON dbo._powersync_checkpoints TO powersync_user;
|
||
|
||
-- 5. Enable CDC on checkpoints table
|
||
EXEC sys.sp_cdc_enable_table
|
||
@source_schema = N'dbo',
|
||
@source_name = N'_powersync_checkpoints',
|
||
@role_name = N'cdc_reader',
|
||
@supports_net_changes = 0;
|
||
|
||
-- 6. Enable CDC on each synced table
|
||
EXEC sys.sp_cdc_enable_table
|
||
@source_schema = N'dbo',
|
||
@source_name = N'todos',
|
||
@role_name = N'cdc_reader',
|
||
@supports_net_changes = 0;
|
||
|
||
-- 7. Optional: Reduce polling interval (default 5s)
|
||
-- pollinginterval = 0: fastest, highest CPU
|
||
-- pollinginterval = 1: 1 second, good production compromise
|
||
EXEC sys.sp_cdc_change_job @job_type = N'capture', @pollinginterval = 1;
|
||
```
|
||
|
||
## App Backend
|
||
|
||
PowerSync does not write client-side changes stored in the SQLite database back to the connected source database. Client applications are required to implement the `uploadData` function which should call a backend API to persist the local SQLite changes to the source database.
|
||
|
||
| Resource | Description |
|
||
|----------|-------------|
|
||
| [App Backend Setup](https://docs.powersync.com/configuration/app-backend/setup.md) | Overview of setting up the app backend for PowerSync. |
|
||
| [Client-Side Integration with Your Backend](https://docs.powersync.com/configuration/app-backend/client-side-integration.md) | How to implement a "backend connector" and links to example implementations. |
|
||
|
||
## Authentication
|
||
|
||
PowerSync Client Applications use JWTs to authenticate agaist the PowerSync Service.
|
||
|
||
| Topic | Resource Link |
|
||
|----------------------|------------------------------------------------------------------------------------------------------|
|
||
| Authentication Setup | [Authentication Setup](https://docs.powersync.com/configuration/auth/overview.md) |
|
||
| Development Tokens | [Development Tokens](https://docs.powersync.com/configuration/auth/development-tokens.md) – Configure tokens for development testing. |
|
||
| Custom Auth | [Custom Auth](https://docs.powersync.com/configuration/auth/custom.md) – Configure custom authentication for PowerSync. |
|
||
|
||
PowerSync can also integrate with Auth providers, with official guides for the following:
|
||
|
||
| Provider | Resource Link |
|
||
|------------|-----------------------------------------------------------------------------------|
|
||
| Supabase | [Supabase](https://docs.powersync.com/configuration/auth/supabase-auth.md) |
|
||
| Firebase | [Firebase](https://docs.powersync.com/configuration/auth/firebase-auth.md) |
|
||
| Auth0 | [Auth0](https://docs.powersync.com/configuration/auth/auth0.md) |
|